Graphics Agent for Linux Administrators' Guide

Installing the Agent

Instructions are provided here for installing the Graphics Agent for Linux on RHEL/Rocky Linux and Ubuntu. If you are installing on a physical machine, see the special instructions provided below.

Note: Disabling GSP

Some GPUs include a GPU System Processor (GSP), which may be used to offload GPU initialization and management tasks. GSP is supported only for vCS in GPU pass through and bare-metal deployments. If you are using any other product in a GPU pass through or bare-metal deployment, you must disable the GSP firmware. Failure to disable GSP can lead to inability in resizing desktops or incorrect display configuration. For more information, see this article on the NVDIA Docs Site.

Important: Required ports will be automatically opened

The Graphics Agent for Linux installer will add firewall exceptions for the following required PCoIP ports during installation: TCP 443, TCP 4172, UDP 4172, and TCP 60443.

Note: Desktop user interfaces will only be available using PCoIP

Once installed and running, the Anyware Graphics Agent for Linux takes over the graphics subsystem which is then unavailable to hypervisors. You can only view the graphical user interface when connecting with a Anyware client.

For example, you cannot view an ESXi virtual machine console through VSphere; you must connect to the machine using PCoIP.

Installing the Agent on RHEL or Rocky Linux

These instructions are for RHEL or Rocky Linux machines. For Ubuntu instructions, see Installing the Agent on Ubuntu, below.

Important: IP Configuration Considerations

For the Anyware Agent installation to complete successfully, the RHEL/Rocky 8 host machine must be configured to use both IPv4 and IPv6.

To install the Anyware Graphics Agent for Linux software on a RHEL/Rocky Linux machine:

  1. Download and install the repository via the shell script provided here.

  2. Install the EPEL repository:

    sudo yum install epel-release

  3. Optionally install USB dependencies, if you intend to support USB devices other than keyboards, mice, and pointer devices. If you skip this step, USB redirection will be completely disabled and bridged USB devices will not work.

    sudo yum install usb-vhci

  4. Install the Anyware Graphics Agent for Linux:

    sudo yum install pcoip-agent-graphics

  5. Note your machine's local IP address. Clients connecting directly to the host workstation will need this number to connect.

  6. Enter the license registration code you received from us.

    Note: These instructions are for Cloud Licensing

    These instructions assume you are using Anyware Cloud Licensing to activate your PCoIP session licenses. If you are using the License Server instead, see Licensing the Graphics Agent for Linux.

    For unproxied internet connections, type:

    pcoip-register-host --registration-code=<XXXXXX@YYY-YYYY-YYY>

    For proxied internet conections, type:

    pcoip-register-host --registration-code=<XXXXXX@YYY-YYYY-YYY> --proxy-server=<serverURL> --proxy-port=<port>

  7. Reboot the desktop.

Installing on RHEL or Rocky Linux in a Dark Site

Note: RHEL/Rocky Linux instructions

Dark site support is provided for RHEL and Rocky Linux installations only.

Important: Install GPU drivers before proceeding

The appropriate GPU driver must be downloaded, transferred, and installed before installing the Graphics Agent for Linux. The procedure for downloading GPU drivers varies by manufacturer and environment; a list of resources is located in Installing GPU Drivers on Linux Machines.

The Graphics Agent for Linux can be installed in dark site environments, also referred to as offline environments, that do not have a connection to the public internet. We provide archived bundles (tar.gz archives) for each supported operating system, which includes the core application and all dependencies.

  1. From an internet-connected machine, open a browser and navigate to HP's documents and downloads site. Look in the sidebar for documentation and download links.

  2. Click the Downloads and scripts button.

    Note: An account is required

    If you are not logged in, you will see a log in prompt instead:

    You can create an account when you click this button if you do not already have one.

  3. Read and accept the End User License Agreement.

  4. Under Darksite packages, find the download that matches your operating system, and click to download it. The installer is downloaded as a TAR file.

    For brevity, this example shows only the Rocky Linux 8.6 package; all supported operating systems have an available download.

  5. Transfer the downloaded file to the production Linux machine using any acceptable method, such as a USB drive.

  6. On the production machine, open a console window and navigate to the directory where you placed the installer.

  7. If you want to install USB dependencies, the usb-vhci kernel modules need be built for which kernel-devel and kernel-headers that correspond to the version of the current Linux image must be installed on kernel image.

    To do this:

    1. Make sure that kernel-devel and kernel-headers corresponding to the current kernel are installed in your kernel image.

    2. Check the status of kernel-devel and kernel-headers:

      rpm -qa kernel{, -devel, -headers} | sort

  8. Extract the installation files by running this command:

        sudo tar xvf <file path>/pcoip-agent-offline-rhel8.6_<pcoip version>.tar.gz

    where <pcoip_version> is the version of the Anyware Agent.

  9. Install the agent by running the following command:

    • To install with USB device support:

      sudo ./install-pcoip-agent.sh pcoip-agent-standard usb-vhci

    • To install without USB device support, omit the usb-vhci parameter:

      sudo ./install-pcoip-agent.sh pcoip-agent-standard

  10. Provide the following when prompted:

    • Agent type: choose Graphics Agent for Linux.

    • USB device support: If you will be allowing USB devices (other than keyboards, mice, and pointers), accept this option. If you install the agent without USB device support, only keyboards, mice, and pointers will work, and more sophisticated devices like Wacom tablets will act as pointing devices without any advanced functionality.

  11. Update the kernel when prompted.

  12. When prompted, reboot the machine.

  13. Register your Graphics Agent for Linux's license with your License Server. See Licensing Anyware Agents With a Local License Server for details.

  14. Reboot the desktop.

GNOME Display Manager Support

GNOME Display Manager (GDM) is supported by the Graphics Agent for Linux as a credential authenticator when gdm-runtime-config is available. This allows PCoIP sessions to be locked and unlocked within the remoted session. When the PCoIP service starts, GDM is configured to run without obstructing access to the GPU. This configuration is reverted when the PCoIP service stops. This behavior is always on and requires no configuration on the Anyware agent. For more information on GDM, see the GNOME Display Manager Reference Manual.

Installing the Agent on Ubuntu

These instructions are for Ubuntu machines. For RHEL/Rocky Linux instructions, see Installing the Agent on RHEL or Rocky Linux, above.

To install the Anyware Graphics Agent for Linux software on an Ubuntu machine:

  1. Download and install the repository via the shell script provided here.

  2. Optionally install USB dependencies, if you intend to support USB devices other than keyboards, mice, and pointer devices. If you skip this step, USB redirection will be completely disabled and bridged USB devices will not work.

    sudo apt install usb-vhci-dkms

  3. Install the Anyware Graphics Agent for Linux:

    sudo apt update
sudo apt install pcoip-agent-graphics

  4. Note your machine's local IP address. Clients connecting directly to the host workstation will need this number to connect.

  5. Enter the license registration code you received from us.

    Note: These instructions are for Cloud Licensing

    These instructions assume you are using Anyware Cloud Licensing to activate your PCoIP session licenses. If you are using the License Server instead, see Licensing the Graphics Agent for Linux.

    For unproxied internet connections, type:

    pcoip-register-host --registration-code=<XXXXXX@YYY-YYYY-YYY>

    For proxied internet conections, type:

    pcoip-register-host --registration-code=<XXXXXX@YYY-YYYY-YYY> --proxy-server=<serverURL> --proxy-port=<port>

  6. Reboot the desktop.

Note: Desktop user interfaces will only be available using PCoIP

Once installed and running, the Anyware Graphics Agent for Linux takes over the graphics subsystem which is then unavailable to hypervisors. You can only view the graphical user interface when connecting with a Anyware client.

For example, you cannot view an ESXi virtual machine console through VSphere; you must connect to the machine using PCoIP.

Installing USB Drivers on Secure Boot Enabled Linux Machines

If Secure Boot is enabled on a Linux host machine with UEFI, USB drivers cannot be installed on that host machine. This stops the client-side USB devices from getting bridged to the host machine. To prevent this from occurring, perform the following steps, provided that you have access to the UEFI Firmware Menu.

Note: If You Do Not Have UEFI Firmware Menu Access

If you do not have access to the UEFI Firmware Menu, either disable Secure Boot or deploy the Virtual Machine without Secure Boot.

  1. Connect to the remote host machine via SSH.

  2. Run the following command:

    sudo mokutil --import /var/lib/dkms/mok.pub

  3. If the Machine Owner Key (MOK) is not set, the mokutil utility will prompt you to create one.

  4. Reboot the machine.

  5. Enroll the MOK in the UEFI firmware menu.

  6. Reboot the machine again.

  7. Run the following commands:

    lsmod | grep usb
dmesg | grep vhci

The output of this command indicates that usb-vhci is installed on the host machine.

Installing on a Physical Machine

When installing the Anyware Agent on a physical machine with a Quadro card, additional steps are required. If you installed the Graphics Agent for Linux on a virtual machine, you can ignore these steps.

Note: Install the agent first

You must install the Graphics Agent for Linux as described above before proceeding.

Important: Some GPUs are automatically configured

The Graphics Agent for Linux can use the following NVIDIA GPUs automatically:

  • K2000
  • K2200
  • K4000
  • K4200
  • K5200
  • M4000
  • P2000
  • P4000
  • P5000
  • P6000
  • RTX4000

If you are unable to start a session using any of these GPUs, follow the procedure described next.

These steps are only required when installing on a physical, non-virtualized machine with a Quadro card:

  1. Attempt to start a PCoIP session. If the connection attempt succeeds, you can stop here. Your GPU will work without further configuration. If the attempt fails, continue on; we will use the log information generated by the failed attempt in the next steps.

  2. Look in /var/log/Xorg.100.log for lines like this:

    [   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-0): connected
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-0): Internal DisplayPort
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-0): 1440.0 MHz maximum pixel clock
[   293.834] (--) NVIDIA(GPU-0): 
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-1): connected
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-1): Internal TMDS
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-1): 165.0 MHz maximum pixel clock
[   293.834] (--) NVIDIA(GPU-0): 
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-2): connected
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-2): Internal DisplayPort
[   293.834] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-2): 1440.0 MHz maximum pixel clock
[   293.835] (--) NVIDIA(GPU-0): 
[   293.835] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-3): connected
[   293.835] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-3): Internal TMDS
[   293.835] (--) NVIDIA(GPU-0): LNX Linux XGA (DFP-3): 165.0 MHz maximum pixel clock
[   293.835] (--) NVIDIA(GPU-0): 
[   293.835] (--) NVIDIA(GPU-0): DFP-4: disconnected
[   293.835] (--) NVIDIA(GPU-0): DFP-4: Internal DisplayPort
[   293.835] (--) NVIDIA(GPU-0): DFP-4: 1440.0 MHz maximum pixel clock
[   293.835] (--) NVIDIA(GPU-0): 
[   293.835] (--) NVIDIA(GPU-0): DFP-5: disconnected
[   293.835] (--) NVIDIA(GPU-0): DFP-5: Internal TMDS
[   293.835] (--) NVIDIA(GPU-0): DFP-5: 165.0 MHz maximum pixel clock
[   293.835] (--) NVIDIA(GPU-0): 
[   293.835] (--) NVIDIA(GPU-0): DFP-6: disconnected
[   293.835] (--) NVIDIA(GPU-0): DFP-6: Internal DisplayPort
[   293.835] (--) NVIDIA(GPU-0): DFP-6: 1440.0 MHz maximum pixel clock
[   293.835] (--) NVIDIA(GPU-0): 
[   293.835] (--) NVIDIA(GPU-0): DFP-7: disconnected
[   293.835] (--) NVIDIA(GPU-0): DFP-7: Internal TMDS
[   293.835] (--) NVIDIA(GPU-0): DFP-7: 165.0 MHz maximum pixel clock

  3. Note the names of the outputs with the highest maximum pixel clocks (as many as four will be shown). In the above example, you would note DFP-0, DFP-2, DFP-4, and DFP-6.

    Note: Systems with fewer than four displays (Quadro K series)

    If there are fewer than four outputs in your system, note them all. K-series cards only support two enabled outputs at a time, but may show more.

  4. Create a file called /etc/X11/xorg.conf.d/10-pcoip.conf:

    touch /etc/X11/xorg.conf.d/10-pcoip.conf

  5. Open /etc/X11/xorg.conf.d/10-pcoip.conf in a text editor.

  6. Paste the following text into the file:

    Section "Screen"
Identifier "dummy_screen"
Device "dummy_videocard"
Option "UseDisplayDevice" ""
Option "ConnectedMonitor" ""
Option "Monitor-" "Monitor0"
Option "Monitor-" "Monitor1"
Option "Monitor-" "Monitor2"
Option "Monitor-" "Monitor3"
Monitor "Monitor0"
EndSection

  7. Populate the ConnectedMonitor and UseDisplayDevice settings with the display IDs you noted earlier, as a comma-separated list. Using our example (your values may be different):

    Option "UseDisplayDevice" "DFP-0,DFP-2,DFP-4,DFP-6"
Option "ConnectedMonitor" "DFP-0,DFP-2,DFP-4,DFP-6"

  8. Next, map these output values to your expected displays. Modify the monitor options to correspond to the displays in the previous step. Each output should be mapped to a monitor identifier from one of the Monitor sections in 10-pcoip.conf.

    Continuing our example, we would map the four outputs to four monitors like this (yours may be different; for example, you may only have two outputs):

    Option "Monitor-DFP-0" "Monitor0"
Option "Monitor-DFP-2" "Monitor1"
Option "Monitor-DFP-4" "Monitor2"
Option "Monitor-DFP-6" "Monitor3"

  9. Save and close 10-pcoip.conf.

  10. Attempt another PCoIP session. If the session is still unsuccessful, and you have a Quadro K series card, repeat steps 7 and 8 with a different output combination, e.g. if you tried DFP-3,DFP-4, try DFP-1,DFP-2. Due to driver differences certain output combinations may not work.

  11. To prevent the NVIDIA driver from changing the kernel mode setting, add the nomodeset parameter to the GRUB configuration:

    1. Open /etc/default/grub in a text editor.

    2. Add nomodeset to GRUB_CMDLINE_LINUX_DEFAULT.

    3. Save and close the file.

    4. Rebuild the GRUB configuration:

      • RHEL/Rocky Linux

        sudo update-grub

      • Ubuntu

        sudo grub2-mkconfig -o /boot/grub2/grub.cfg

    5. Reboot the machine.

  12. Attempt a PCoIP connection again. The connection should succeed.

    If the session does not start, make sure that the displays are correctly configured.

Once you've installed the software, you can configure it, register licenses, or connect to it.

Last updated: Thursday, July 18, 2024