Skip to content

Installing the Graphics Agent for Linux on Ubuntu

To install the PCoIP Graphics Agent for Linux software:

  1. If a Teradici signing key already exists on the desktop, delete it:

    sudo apt-key del 4E45878267D7ADA8
    
  2. Download the Teradici repo:

    sudo wget -O teradici-repo-latest.deb https://downloads.teradici.com/ubuntu/teradici-repo-$(lsb_release -cs)-latest.deb
    
  3. Install the Teradici repo:

    sudo apt install --reinstall ./teradici-repo-latest.deb
    
  4. Select the beta channel, by editing the pcoip-list file and commenting the appropriate lines:

    sudo vi /etc/apt/sources.list.d/pcoip.list
    
  5. 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
    
  6. Install the PCoIP Graphics Agent for Linux:

    sudo apt update
    sudo apt install pcoip-agent-graphics
    
  7. Note your machine's local IP address. Clients connecting directly to the host workstation will need this number to connect.

  8. Enter the license registration code you received from Teradici.

    Note: These instructions are for Cloud Licensing

    These instructions assume you are using Teradici Cloud Licensing to activate your PCoIP session licenses. If you are using the Teradici 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>
    
  9. Reboot the Linux instance.

Installing on stock Ubuntu 18.04 installations

When connecting to the Graphics Agent for Linux installed on a stock Ubuntu 18.04 installation, users may not be able to establish PCoIP sessions. You can work around this issue by setting the pcoip.desktop_session value in pcoip-agent.conf:

  1. Open /etc/pcoip-agent/pcoip-agent.conf in a text editor

  2. Add the following line:

    pcoip.desktop_session = ubuntu
    
  3. Save and close the editor.

Note: Desktop user interfaces will only be available using PCoIP

Once installed and running, the PCoIP 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 PCoIP client.

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

Installing the Graphics Agent for Linux on a Physical PC

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

Important: Install the agent first

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

These steps are only required when installing on a bare metal machine:

  1. Attempt to start a PCoIP session. The session will not be successful, but the attempt generates log information we'll use next.

  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 four outputs with the highest maximum pixel clocks. In the above example, you would note DFP-0, DFP-2, DFP-4, and DFP-6.

    Note: Systems with fewer than four displays

    If there are fewer than four outputs in your system, note them all.

  4. On the host machine, look in /tmp for a generated configuration file with a name similar to xorg.pcoip.######.conf.

  5. Copy this file to /etc/X11/xorg.conf.d/10-xorg-pcoip.conf, and make it writeable (replacing ##### with the actual value):

    cp /tmp/xorg.pcoip.######.conf /etc/X11/xorg.conf.d/10-xorg-pcoip.conf
    chmod u+w /etc/X11/xorg.conf.d/10-xorg-pcoip.conf
    
  6. Open /etc/X11/xorg.conf.d/10-xorg-pcoip.conf in a text editor.

  7. Change the ConnectedMonitor and UseDisplayDevice settings to 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. In the Device section of 10-xorg-pcoip.conf, 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-xorg-pcoip.conf.

    Continuing our example, we would map the four outputs to four monitors like this (yours may be different):

        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-xorg-pcoip.conf.

  10. 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:

      sudo update-grub
      
    5. Reboot the machine.

  11. 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.