Teradici APEX 2800 TER1109003, Teradici APEX 2800 Server Offload card by, APEX 2800 Administrator's Manual

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

1

Teradici APEX™ 2 800

Server Offload Car d

Administrator's Guide

TER1109003

Issue 3

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

2

Teradici Corporation
#101-4621 Canada Way, Burnaby, BC V5G 4X8 Canada
p [phone] f [phone]
www.teradici.com

The information contained in this document represents the current view of Teradici Corporation as of the date of
publication. Because Teradici must respond to changing market conditions, it should not be interpreted to be a
commitment on the part of Teradici, and Teradici cannot guarantee the accuracy of any information presented after
the date of publication.

This document is for informational purposes only. TERADICI MAKES NO WARRANTIES, EXPRESS, IMPLIED OR
STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under
copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted
in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose,
without the express written permission of Teradici Corporation.

Teradici may have patents, patent applications, trademarks, copyrights, or other int ellectual property rights covering
subject matter in this document. Except as expressly provided in any written license agreement from Teradici, the
furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other
intellectual property. Visit www.teradici.com/teradici/pat

© 2012 Teradici Corporation. All rights reserved.
Teradici, PC-over-IP, and PCoIP are registered trademarks of Teradici Corporation.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

for more information.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

3

Revision History

Version

Date

Description

3

Sep 25, 2012

2

Feb 24, 2012

1

Jan 27, 2012

Initial release

• Replaced screen shots where new values are now seen

• Updated information as related to new features in the latest

• Updated the document for ESXi 5.0.

• Added Lenovo RD240 to list of tested VDI Server Platforms

• Added information about disabling the ESXi interrupt remapping to

• Removed the information about the PCoIP Imaging Caching Size

• Added hyperlink to Patents webpage from the Copyrights page

software release

the Troubleshooting sectio n

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

4

Contents

Table of Figures ............................................................................................................................... 6

Definitions ........................................................................................................................................ 7

1 Introduction ......................................................................................................................... 9

Benefits ............................................................................................................................................. 9

System Requirements .................................................................................................................... 10

Virtual Desktop Server Platform...................................................................................................... 10

Client .............................................................................................................................................. 10

Network .......................................................................................................................................... 10

2 Installation and Configuration ........................................................................................... 11

Before you Begin ............................................................................................................................ 11

Installing the APEX 2800 Card ....................................................................................................... 11

Installing the ESXi Driver Package ................................................................................................. 12

Installing the Virtual Machine Driver ............................................................................................... 14

Verifying the Policy Settings ........................................................................................................... 15

Installing Additional APEX 2800 Cards ........................................................................................... 16

3 Administration ................................................................................................................... 17

Setting Priority Levels ..................................................................................................................... 17

Assigning the Priority to the Global Pool ......................................................................................... 17

Assigning the Priority to a Desktop Pool ......................................................................................... 18

Assigning the Priority to an Individual End User ............................................................................. 19

Session Variables ........................................................................................................................... 20

APEX 2800 Command Line Interface (CLI) .................................................................................... 20

Command Structure ........................................................................................................................ 20

Commands ..................................................................................................................................... 20

Enabling/Disabling the APEX 2800 Card ........................................................................................ 22

Working with the Property Settings ................................................................................................. 22

Displaying General Device and Driver Information ......................................................................... 23

Setting the Log Level for the APEX 2800 ESXi Driver and Firmware ............................................. 23

Displaying the APEX 2800 Properties for a VM .............................................................................. 24

Monitoring the VDI Server Load ..................................................................................................... 25

ESXtop PCPU ................................................................................................................................ 25

vCenter Performance Tab .............................................................................................................. 26

Viewing the Status of the APEX 2800 Card .................................................................................... 26

Viewing the Usage and Monitoring Status of the Virtual Machines ................................................. 28

Legend: ........................................................................................................................................... 28

Viewing and Setting the Maximum Display Resolution ................................................................... 29

4 Troubleshooting ................................................................................................................ 31

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

5

Enabling a Syslog Server ............................................................................................................... 31

Determining the APEX 2800 Card Status ....................................................................................... 32

From an Administrative Console ..................................................................................................... 32

At the User's Desk .......................................................................................................................... 32

Identifying a Failed Card ................................................................................................................. 32

Disabling the ESXi Interrupt Remapping (Communication with PCIe Devices Stops) .................... 33

5 Appendix A: VDI Server Platforms Tested ....................................................................... 34

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

6

Table of Figures

Figure 1-1: APEX 2800 firmware 2.0 maximum number of display offloads at different resolutions. ................. 9

Figure 2-1: VMware vShpere Client configuration for the Apex 2800 install ..................................................... 11

Figure 2-2: WinSCP Login Window .................................................................................................................... 12

Figure 2-3: WinSCP browser window showing placement of the zip file to the tmp folder. ............................... 13

Figure 2-4: Zip command format for ESXi 4.1. ................................................................................................... 13

Figure 2-5: Successful zip command results for ESXi 4.1 with the reboot command. ........................................ 14

Figure 2-6: Virtua l M a c hine Desktop .................................................................................................................. 14

Figure 2-7: Pcoip-ctrl output with the -V option .................................................................................................. 15

Figure 2-8: Vie w Connection Server Global Po lic ie s configuration window. ..................................................... 16

Figure 3-1: Vie w Connection Server Global Po lic ie s priority settings. ............................................................... 17

Figure 3-2: VCS local inventory pools policies. .................................................................................................. 18

Figure 3-3: VCS lo c a l inventory pools Policies Prior ity setting. ......................................................................... 19

Figure 3-4: VCS Glo bal Policies individual priority options. .............................................................................. 19

Figure 3-5: Esxtop command output .................................................................................................................... 25

Figure 3-6: vCenter Performance Tab .................................................................................................................. 26

Figure 3-7: Pcoip-ctrl output with the -I option, ESXi 5.0 and driver 1.x ............................................................ 27

Figure 3-8: Pcoip-ctrl output with the -I option, ESXi 5.0 and driver 2.x ............................................................ 27

Figure 3-9: Pcoip-ctrl command output with the -V option ................................................................................. 28

Figure 3-10: Pcoip-ctrl output with the --get-max-resolution option ................................................................... 29

Figure 4-1: ESXi Host Advanced Settings (Enabling a Syslog Server ) .............................................................. 31

Figure 4-2: APEX 2800 desktop offload indicator. .............................................................................................. 32

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

7

Definitions

Definition

AWI

Administrative Web Interface

CLI

Command Line Interface

CPU

Central Processing Unit

ECC

Error Correction Code

FPS

Frames Per Second

GPU

Graphics Processing Unit

GUI

Graphical User Interface presented by the client On Screen
Display when not operating in a PC-over-IP session

MC

Management Console

Mpps

Mega pixels per second

OS

Operating System

OSD

On Screen Display

PCIe

Peripheral Component Interconnect Express

PC-over-IP®

Personal Computer over Internet Protocol

PCoIP®

Personal Computer over Internet Protocol (PC-over-IP)

PCoIP Zero Client
PCoIP Host

Host side of PC-over-IP syste m

QoS

Quality of Service

vCPU

Virtual CPU within a virtual machine

VSC

View Connection Server

VDI

Virtual Desktop Infrastructure

VIB

VMware vSphere Installation Bundle

VM

Virtual Machine

VPN

Virtual Private Network

Description

Desktop side of PC-over-IP system (that is, client). For example,
PCoIP zero client or PCoIP integrated display

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

8

Definition

Description

Zero Client

See PCoIP zero client

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

9

1 Introduction

The Teradici APEX™ 2800 server offload card provides hardware-accelerated PCoIP® image
encoding for server-hosted VMwa re View v irtual desk tops (of ten re ferred to as Virtual
Desktop Infrastructure or VDI). Available as a standard PCI Express (PCIe) expansion card
for industry-standard servers, the APEX 2800 card monitors the graphical demands of VDI
displays and automatically offloads the PCoIP encoding tasks of the most demanding
displays from the vCPUs to the APEX 2800 card.

As demands change, the card seamlessly and automatically shifts between hardware
encoding on the APEX 2800 card and software encoding on the virtual desktops' vCPU(s).
This lets the APEX 2800 card support a large number of virtual desktops while providing
optimal use of resources. The APEX 2800 card offloads up to 100 displays depending on the
maximum display resolution set up in the environment, and is described in the table below.

Note: Each virtual machine display is monitored separately. The number of displays
offloaded may vary based on screen resolution and display activity.

Figure 1-1: APEX 2800 firmware 2.0 maximum nu mber of display offloads at different

resolutions.

1.1 Benefits

• Protected end-user experience from pixel-encoding CPU peaks

• Increased VDI consolidation ratios per server

• Full integration into VMware View and managed through View Administrator

• Simple install and setup

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

10

For more details, see http://www.teradici.com/pcoip/pcoip-products/pcoip-server-offload-

card.php.

1.2 System Requirements

The APEX 2800 card can be used in virtual desktop environments that meet the following
system requirements.

1.2.1 Virtual Desktop Server Platform

• Server platform with an available PCI Express (PCIe) x8, full height, half length

compatible card slot

• ESXi 4.1 Update 1 build 348481, 4.1 Update 2 build 502767, or ESXi 5.0, ESXi 5.0.0 U1

• VMware View 4.6 or View 5.0

• Supported virtual machine operating systems:

o Windows 7 32-bit/64-bit
o Windows Vista 32-bit/64-bit
o Windows XP

• Maximum of two APEX 2800 cards per server with up to 200 displays offloaded.
To get the latest driv e rs , re g is ter at http://techsupport.teradici.com

Knowledge Base article 650.

and subscribe to

1.2.2 Client

• PCoIP zero clients with firmware 3.5 or later

• VMware View 4.6 clients or later

• Displays with a resolution of 2560 x 1600 or less (Displays with a higher resolution

settings may become available in future software releases)

1.2.3 Network

The PCoIP protocol provides a real-time delivery of a rich user desktop experience. To
ensure a responsive desktop, the PCoIP protocol must be deployed across a properly
architected virtual desktop network infrastructure that meets bandwidth, QoS, latency and
packet-loss requirements. For more details, see the PCoIP Protocol Virtual Desktop Network
Design Checklist TER1105004 document at http://techsupport.teradici.com

.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

11

2 Installation and Configuration

This section steps you through the process to set up and configure the APEX 2800 card.

Warning:
Power down and disconnect devices from AC power before handling them. Failure to do this

can result in personal injury or equipment damage. Some circuitry on the server PC can
continue to operate even though the front panel power switch is off.

Ensure you observe correct anti-static handling to avoid potential ESD damage to the card.

2.1 Before you Begin

1. Get the latest drivers by registering at the Teradici support website

http://techsupport.teradici.com

2. Download the APEX 2800 drivers to a convenient PC.

2.2 Installing the APEX 2800 Card

1. Make sure all virtual machines hosted by the server are powered down or migrated to

another server.

2. In the VMware vSphere client, right-click on the ESXi server in the inventory, and then

select Enter Maintenance Mod e.

, review and subscribe to Knowledge Base article 650.

Figure 2-1: VMware vShpere Client configuration for the Apex 2800 install

3. Make sure the server is turned off and disconnected from AC power.

4. Insert the APEX 2800 card into an available PCI Express slot and secure the metal

bracket.

5. Plug the server into a surge-protected AC outlet, and then power it on.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

12

2.3 Installing the ESXi Driver Package

1. Enable remote login on the VMware ESXi server:
a. Press F2 to enter cu s to mization.

b. Enter your username and password.
c. Enable SSH:

• ESXi 5.0: Select Troubleshooting Mode Options > Enable SSH.

• ESXi 4.1: Select Troubleshooting Mode Options > Enable Remote Tech

Support (SSH).

2. Copy the driver package from your PC to the ESXi server using secure copy.

a. Download and install WinSCP on your PC.
b. Start WinSCP and specify your ESXi server host name (IP address), username and

password.

c. Make sure the File protocol field is SCP.
d. Click Login.

Figure 2-2: WinSCP Login Window

e. Drag the apex2800-version-esxi-version-xxxxx.zip package to the /tmp folder in your

ESXi server.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

13

Figure 2-3: WinSCP browser window showing placement of the zip file to the tmp

folder.

3. Connect to the ESXi server using an SSH client (e.g., PuTTy) from your PC and install
the driver package:

a. Navigate to the /tmp folder.
b. Depending on your EXSi version, type:

• ESXi 5.0 esxcli software vib install -d /tmp/apex2800-

version-esxi-version-xxxxxx.zip

• ESXi 4.1: esxupdate --bundle apex2800-version-esxi-version-

xxxxxx.zip update

Figure 2-4: Zip command format for ESXi 4.1.

The following message appears when the installation finishes.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

14

Figure 2-5: Successful zip command results for ESXi 4.1 with the reboot command.

4. Type reboot at the prompt to restart the ESXi server.

From the vSphere Client, right-click the ESXi server in the inventory, and then select Exit
Maintenance Mode.

2.4 Installing the Vir tual Machine Driver

You must install the APEX 2800 virtual machine driver on each virtual machine.

1. Power up the virtual machine.

2. Open a console window to the virtual machine from the vSphere client.

Figure 2-6: Virtual Machine Desktop

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

15

3. Run the apex2800-version-xxxxxx.exe on the virtual machine and follow the onscreen
steps.

Note: You cannot install this package from within a PCoIP session to the virtual
machine. You must install it from the vSphere VMConsole.

4. After the installation finish es, choose to reboot the machine later.

Important Note: Make sure to power the virtual machine off and then back on again. This
ensures that the ESXi inspects the updated virtual machine image. A simple reboot does
not cause the driver to take effect.

.

Figure 2-7: Pcoip-ctrl output with the -V option

2.5 Verifying the Policy Settings

1. From the View Connection Server, select Global Policies.

2. Make sure that the PCoIP hardware acce ler at ion setting is enabled for any policies that
inherit from the global policy.

3. In any custom policies, make sure the option for enabling and disabling PCoIP hardware
acceleration is set to Allow.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

16

Figure 2-8: View Connection Server Global Policies configuration window.

4. Click OK.

2.6 Installing Additional APEX 2800 Cards

When additional APEX 2800 cards are installed on the same server, they act as a single
resource and can automatically offload additional displays. To install an additional card and
check its status, repeat the following steps:

Installing the APEX 2800 Card
Viewing the Status of the APEX 2800 Card

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

17

3 Administration

This section describes the management functions for your APEX 2800 card(s).
To manage the APEX 2800 card, use View Administrator. It does not require the installation

of any other management tool.

3.1 Setting Priority Levels

You can refine how the APEX 2800 card prioritizes display offloads when the card is
operating at full capacity. By assigning one of five available priority levels to the global pool,
a specific desktop pool, or an individual user in View Connection Server, you can apply your
knowledge about the known graphic demands of existing desktop pools to the APEX 2800
card's prioritization of display offloads.

Note: In VMware View 4.6 and 5.0, the default priority level for PCoIP hardware
acceleration is set to Medium .

This ensures that displays belonging to higher priority desktop pools are encoded on the
APEX 2800 card processor before lower priority displays, regardless of the amount of pixel
activity being generated by the higher priority desktops. To change the priority from Medium
to another level, follow the steps in the next sections.

3.1.1 Assigning the Priority to the Global Pool

To change the priority setting for your global pool:

1. From the View Connection Server, select Policies > Global Policies.

The View Policies window appea rs:

Figure 3-1: View Connection Server Global Policies priority settings.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

18

2. The PCoIP hardware acceleration drop-down box is set to Allow (by default). You can
change the Priority setting to any of the available options. This change is applied to your
desktop pools that currently are set up to inherit the global setting.

3.1.2 Assigning the Priority to a Desktop Pool

To assign a priority level to a desktop pool:

1. From the View Connection Server, select Inventory > Pools.

2. Double-click the ID of the applicable desktop pool, and then click the Policies tab.

3. Configure session policies for the pool.

• To configure general session policies, click Edit Policies from the View Policies

window.

• To configure local session policies for the pool, click Edit Policies from the Local

Mode Policies window.

Figure 3-2: VCS local inventory pools policies.

1. The Priority drop-down box becomes enabled. Change the Priority setting as required.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

19

Figure 3-3: VCS local inventory pools Policies Priority setting.

2. Click OK to save your changes. The new priority setting is applied to all users within the
desktop pool (except any users that have a Priority setting applied to them individually).

3.1.3 Assigning the Priority to an Individual End User

To assign a priority to a specific end user within a desktop pool:

1. From the View Connection Server, select Inventory > Pools.

2. Click User Overrides.

3. Select the user to which you wa nt to app ly the pr io r ity s et ting.

4. Click Next. The Edit View Policies window appears.

Figure 3-4: VCS Global Policies individual priority options.

5. Set the PCoIP hardware acceleration field to Allow.

6. Change the Priority setting as required.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

20

3.2 Session Variables

Session Setting

Supported by the APEX 2800 Card

No. This is set to 24 frames per second (fps)

Most of the PCoIP session settings configured in View are maintained by the APEX 2800
card. The following table shows common session settings and if they are supported by the
APEX 2800 card.

Table 3-1: Apex 2800 supported common session variables

PCoIP Image Quality Levels:

• Minimum Image Quality • Yes

• Maximum Initial Image Quality • Yes

• Maximum Frame Rate •

Maximum PCoIP Session Bandwidth Supported dynamically receiving the bandwidth

PCoIP Session Bandwidth Floor Supported dynamically receiving the bandwidth

Turn Off Build-to-Lossless Yes

which is the default for VMware View using
the PCoIP protocol.

limit values from the PCoIP software in VMware
View.

floor from the PCoIP software in VMware View.

3.3 APEX 2800 Command Line Interface (CLI)

The APEX 2800 card supports a command line interface from the ESXi, which you can use
to configure and monitor your APEX 2800 cards.

Note: All configured settings, with the exception of the offload indicator setting, appear in
the PCoIP Server Logs.

3.3.1 Command Structure

From the ESXi CLI:

ESXi 4.1: pcoip-ctrl [-d<device number>][-x][-e][-L log level][-I][­V][-O][-P “name value”][-X name]

ESXi 5.0: /opt/teradici/pcoip-ctrl [-d<device number>][-x][-e][-L
log level][-I][-V][-O][-P “name value”][-X name]

Note: The only difference between the two ESXi versions is that for ESXi 5.0 you must add
/opt/teradici/ before the command.

3.3.2 Commands

Table 3-2: Pcoip-ctrl command line switches

Null Switches Output the command usage information

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

21

Null Switches Output the command usage information

-d Specify the device number (bus number) to control

-x Disable the APEX 2800 device specified using the -d option

-e Enable the APEX 2800 device specified using the -d option

-I Output the general driver and device information

-V Output virtual machine and display usage information

-C Output all software and firmware log event categories and

current levels

-O Output all virtual machine properties

-P <property_name property_value) Set the specified property value

offload_indicator Enable/disable the red dot offload

indicator if eligible. (Disabled by
default)

bw_enable_threshold

bw_disable_threshold

-X <property_name> Remove the specified property

-L <log level> Set the default log level in the APEX 2800 ESXi driver and

firmware: (ex. pcoip-ctrl -L0)

0 CRITICAL log level

1 ERROR log level

2 INFO log level

--get-max-resolution Retrieve a list of supported maximum resolutions and the

current maximum resolution

--set-max-resolution Select a particular maximum resolution

--enable-portrait-mode Enables portrait mode. It is disabled by default

Enable/disable network bandwidth
thresholds for offload canceling for
View 5.0 clients

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

22

Null Switches Output the command usage information

--disable-portrait-mode Disables portrait mode

--reset-properties Reset all properties to the manufacturing default (deletes all

properties set by the user)

--get-encoder-mode-switch-

thresholds

--set-encoder-mode-switch-

thresholds "<enable_kbps>
<disable_kbps>"

Retrieves the client capability thresholds at which the encoder
mode is switched

Sets the client capabilit thresholds at which the encoder mode
is switched.

3.3.3 Enabling/Disabling the APEX 2800 Card

You can enable or disable the APEX 2800 card using the pcoip-ctrl command from the ESXi
CLI.

Note: The VM must be eligible for offloading for these settings to take effect.

Disable the APEX 2800 card.
Example: To disable the APEX 2800 card in bus number 6, type ESX>pcoip-ctrl -d 6

-x

Enable the APEX 2800 card.
Example: To enable the APEX 2800 card in bus number 6, type ESX>pcoip-ctrl –d 6

–e

Note: If you use ESXi 5.0, remember to add /opt/teradici/[command].

3.3.4 Working with the Property Settings

This section describes the property values available in the APEX 2800 card. For the full list
of available commands, see APEX 2800 Command Line Interface (CLI)

Table 3-3: APEX 2800 property values

APEX 2800 Property Description

offload_indicator Set the red dot display offload indicator option.

Operation: Provides a way to see if a display is offloaded at the end user's
display by a small dot overlay appearing at the top left corner of the screen.

• Red dot: The display is offloaded using PCoIP hardware compression in
the APEX 2800 card.

• Blue dot: The display is using PCoIP software compression and is not
offloaded.

Property value:

• 1: Enable the offload indicator

.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

23

• 2: Disable the offload indicator

Default: Disabled

bw_disable_threshold
bw_enable_threshold

Set the enable/disable network bandwidth threshold for offload canceling. To
view the enable or disable state for a VM, type pcoip-ctrl -V.

Note: This setting applies for VMware View 5.0 clients and later.

Operation: When the network bandwidth for a session goes below the
threshold, display offloading is cancelled. Once the network bandwidth is
above the threshold, the display(s) are eligible for offloading again based on
the VM priority and APEX 2800 card resource availability.

Property value: 0 to any bandwidth number.
Usage: At lower network bandwidths, there is a smaller load on the APEX

2800 card and as a result, less offload benefit. Automatically cancelling display
offload below a network threshold helps maximize the benefit of the APEX
2800 card.

Also, automatic display offload cancelling below a network threshold lets the
session take advantage of WAN bandwidth optimization features in PCoIP
software such as client image caching (if available on the clie nt).

Note: The APEX 2800 card does not support client image caching at this time.
It will be available in a future release.

Default:
Session bandwidth threshold for offload cancelling: 800 Kbps.
Session bandwidth threshold for offload enabling : 1 Mbps.

Setting a Property
To set an APEX 2800 card feature property type ESX> pcoip-ctrl –P

<property_name property_value>
Example (to enable the offload indicator):

ESX>pcoip-ctrl -P "offload_indicator 1"

Example (to disable the offload indicator):

ESX>pcoip-ctrl -P "offload_indicator 0"

Note: If you use ESXi 5.0 or later, remember to add /opt/teradici/[command].

3.3.5 Displaying General Device and Driver Information

To display general information about the APEX 2800 card and ESXi driver, type pcoip­ctrl –I.

Note: If you use ESXi 5.0, remember to add /opt/teradici/[command].

See Viewing the Status of the APEX 2800 Card

.

3.3.6 Setting the Log Level for the APEX 2800 ESXi Driver
and Firmware

The APEX 2800 ESXi driver and firmware support multiple levels of logging to balance
sufficient data, system performance, and log file size. There are three log levels that are set in

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

24

both the APEX 2800 ESXi driver as well as in the APEX 2800 card firmware. These levels

Log
Level

Description

include:

Table 3-4: APEX 2800 log levels.

0-Critical The system can no longer function correctly. This log level only shows the critical event

messages in the log.

1-Error This is the default log level. It inclu des crit ical and er ror even t message but does not

include Information messages.

2-Info This event log shows all log levels.

Example

ESX>pcoip-ctrl -L 1

Note: We recommend you use a syslog server to ensure necessary information is available in
the event of an issue. See Enabling a Syslog Server

for more details.

Note: If you use ESXi 5.0 or above, remember to add /opt/teradici/[command]

Displaying Firmware Log Event Categories
To view the current level of event messages that appear in your error log, type pcoip-

ctrl -C -d <device number>.
Example:

pcoip-ctrl -C -d 4

Note: If you use ESXi 5.0 or above, remember to add /opt/teradici/[command].

Displaying Software and Firmware Log Event Categories

To view the current level of event messages that appear in your error log, type pcoip­ctrl -C -d <device number>.

Example:

pcoip-ctrl -C -d 4

Note: If you use ESXi 5.0 or above, remember to add /opt/teradici/[command].

3.3.7 Displaying the APEX 2800 Properties for a VM

To view the properties for a virtual machine, type pcoip-ctrl -O.

Note: If you use ESXi 5.0 or above, remember to add /opt/teradici/[command].

Example:

bw_disable_threshold ==> 0
bw_enable_threshold ==> 100
offload_indicator ==> 1

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

25

3.4 Monitoring the VDI Server Load

3.4.1 ESXtop PCPU

You can use esxtop to monitor the physical CPU loading for a VDI server by using the PCPU
statistics. While you can do this live, we recommend you run esxtop in batch mode to save
the values to a file.

Use the esxtop command: esxtop –b > myfile.csv to save server performance
information to a file. You can view this with Microsoft Excel

®

or another applicable tool. For
instructions on the esxtop batch mode see VMware's Knowledge Base
articlehttp://kb.vmware.com/kb/1033346

(current at time of writing).

The PCPU values appear at the top part of the window as shown in the following figure:

Figure 3-5: Esxtop command output

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

26

3.4.2 vCenter Performance Tab

Figure 3-6: vCenter Performance Tab

Note: While you can monitor the server CPU resources through vCenter, it is not
recommended for benchmarking the APEX 2800 card since the usage is only updated every
20 seconds. This timing misses spikes in server CPU loads.

3.5 Viewing the Status of the APEX 2800 Card

When the installation and configuration of the APEX 2800 card is complete, you can verify
the working status of the APEX 2800 card.

Note: The latest software driver adds additional information showing the number of displays
supported and the display orientation highlighted below.

Note: If you use ESXi 5.0 or later, remember to add /opt/teradici/[command].

1. Enter the following command in your SSH session:

/opt/teradici/pcoip-ctrl -I

• This outputs the following for APEX driver 1.x and ESXi 5.0:

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

27

Figure 3-7: Pcoip-ctrl output with the -I option, ESXi 5.0 and driver 1.x

This outputs the following for driver 2.0 and ESXi 5.0:

Figure 3-8: Pcoip-ctrl output with the -I option, ESXi 5.0 and driver 2.x

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

28

The line containing "(1) APEX2800 device present" indicates that the card is installed
correctly.

Other information provided includes:

• Onboard temperatures (for both the processor and board)

• Device utilization: This shows the current activity for the card. The value ranges from 0

to 99 with 0 indicating idle.

• Image pipeline: The rate at which the card is processing pixels (measured in kilopixels

per second).

• Portrait mode status (software 2.0 and above).

• Number of displays supported (software 2.0 and above).

3.6 Viewing the Usage and Monitoring Status of the
Virtual Machines

You can view information about each virtual machine which the APEX 2800 card is
currently monitoring. The figure below and the following command provides information
about each display and if a particular display is offloaded:

ESXi>pcoip-ctrl -V

Note: If you use ESXi 5.0 or above, remember to add /opt/teradici/[command].

Figure 3-9: Pcoip-ctrl command output with the -V option

3.6.1 Legend:

(XX): Number of displays currently offloaded. In the figure, there are three displays
offloaded.

(HostName) Unavailable: (Not shown in the figure.) Indicates the VM does not have the
APEX 2800 VM software installed and running.

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

29

(HostName) PCoIP Session Closed: Indicates the VM is not currently in an active PCoIP

•

•

session. If APEX 2800 hardware acceleration is disabled for this user’s VM in View
Connection Server, this command also reports the PCoIP session as closed.

(HostName)(APEX VM Driver build #) [E] **[0](display #0 resolution) –[1](display #1
resolution) (Not shown in the figure.)

[E] Indicates the VM is either above the bandwidth threshold, or is connected to a

client not capable of image caching.

[D] Indicates the VM is connected to a PCoIP client that supports image caching,

and the bandwidth available between the VM and PCoIP client is below the
configurable bandwidth threshold.

Note: The bandwidth threshold setting only applies to VMware View 5.0 (or later)
clients.

• ** indicates that particular display is offloaded.

• -- indicates the display is not offloaded (uses PCoIP software encoding).

3.7 Viewing and Setting the Maximum Display
Resolution

To view the configured maximum display resolution use the --get-max-resolution option
with the pcoip-ctrl command.

Example.

# /opt/teradici/pcoip-ctrl --get-max-resolution

Note: The displayed output also descr ibes the com mand to select a new resolution.

Figure 3-10: Pcoip-ctrl output with the --get-max-resolution option

To select a new resolution use the --set-max-resolution <selection> option.
Use 1-4 as the selection value where each number represents the configurable resolution as

shown in the figure above and listed below.

1. 2560 X 1600

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

30

2. 1920 X 1200

3. 1680 X 1050

4. 1280 X 1024

Example
To set a new maximum resolution of 1920 x 1200 use the associated number 2.

/opt/teradici/pcoip-ctrl --set-max-resolution 2

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

31

4 Troubleshooting

This section describes some troubleshooting procedures specific to the APEX 2800 card. For
more details, see the Knowledge Base at http://techsupport.teradici.com

4.1 Enabling a Syslog Server

It is important to enable a syslog server to capture the log data in the event of an issue. Due
to the volume of information, the event logs are over-written quickly. Also, the logs can be
lost during a reboot. Enabling a syslog server in the advanced settings of your ESXi host
ensures necessary data is available for troubleshooting.

.

Figure 4-1: ESXi Host Advanced Settings (Enabling a Syslog Server )

If a syslog server is not available, you can move your logging to a non-scratch directory by
following the steps outlined in the following VMware Knowledge Base articles:

http://kb.vmware.com/kb/1016621
http://kb.vmware.com/kb/1005030

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

32

4.2 Determining the APEX 2800 Card Status

4.2.1 From an Administrative Console

To view the status of one, or multiple APEX 2800 cards, enter the following command in
your SSH session:

pcoip-ctrl -I

For more information about pcoip-ctrl -I command, see View ing the Status of the APEX

2800 Card.

Note: If you use ESXi 5.0 or later, remember to add /opt/teradici/[command].

4.2.2 At the User's Desk

If you have enabled the offload indicator, you can also determine if an individual display is
offloaded by viewing the individual screen:

Offloaded (using PCoIP hardware compression in the APEX 2800 card): A small, red
square appears in the top left-hand corner of the screen.

Not offloaded (using PCoIP software compression): A small blue square appears in the top
left-hand corner of the screen.

Note: By default the offload indicator is disabled.

Figure 4-2: APEX 2800 desktop offload indicator.

4.3 Identifying a Failed Card

Enter the following command in your SSH session:

pcoip-ctrl –I

If the output does not show information for your card or the number of devices present does
not match the number of installed cards (maximum of two), then one or more APEX 2800
cards have failed.

For more information about the pcoip-ctrl -I command, see

APEX 2800 Card.

Note: If you use ESXi 5.0 or later, remember to add /opt/teradici/[command].

Viewing the Status of the

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

33

4.4 Disabling the ESXi I nterrupt Remapping
(Communication with PCIe Devices Stops)

In some cases unrelated to the APEX 2800 card, enabling the interrupt remapping on the
server can cause a loss of communication with PCIe devices. This problem can occur to any
other PCIe card. The interrupt remapping triggers the halt of any display offload onto the
card. As such, it is recommended to disable the ESXi interrupt remapping. See the

Knowledge Base Article 1030265 for details (current at time of writing).

VMware

Teradici APEX 2800 Server Offload Card Administrator's Guide

TER1109003 Issue 3

34

5 Appendix A: VDI Server Platforms Tested

VDI server platforms tested to date:

• Cisco C200

• Cisco C250

• Cisco C260

• Dell R610

• Dell R710

• Dell 2970

• HP DL385G7

• HP DL585G7

• IBM x3650

• IBM x369

• Lenovo RD240

• Dell R720