Your First vGPU Virtual Desktop¶
This chapter describes how to:
Create and configure a virtual machine in vSphere
Install Windows and VMware Tools on the VM
Customize Windows settings
Install Teradici Cloud Access Software Agent and PCoIP connect to Host
Adjust some additional VM settings and enable VM console access
Enable the NVIDIA vGPU and finalizing the installation
Creating a Virtual Machine¶
These instructions are to assist in making a VM from scratch that will support NVIDIA vGPU. Later the VM will be used as a gold master image. Use the following procedure to configure a vGPU for a single guest desktop:
Browse to the host or cluster using the vSphere Web Client.
Right-click the desired host or cluster and select New Virtual Machine.
The New Virtual Machine wizard begins.
Select Create a new virtual machine and click Next.
Enter a name for the virtual machine. Choose the location to host the virtual machine using the Select a location for the virtual machine section. Click Next to continue.
Select a compute resource to run the VM. Click Next to continue.
Select the datastore to host the virtual machine. Click Next to continue.
Select compatibility for the virtual machine. This allows VMs to run on different versions of vSphere. To run vGPU select ESXi 6.0 and later. Click Next to continue.
Select the appropriate Windows OS from the Guest OS Family and Guest OS Version pull-down menus. Click Next to continue.
Customize hardware is next. Set the virtual hardware based on your desktop workload requirements. Click Next to continue.
Review the New Virtual Machine configuration prior to completion. Click Finish when ready.
The new virtual machine container has now been created.
Installing Windows¶
Use the following procedure to install Windows on the virtual machine.
Select the virtual machine, right click on the virtual machine, and select Edit Settings.
Locate the CD/DVD entry under the Virtual Hardware tab. Select the arrow drop down to reveal data sources for the CD/DVD media. (In this example a Datastore ISO file will be used.) Check the Connect checkbox for CD/DVD drive 1. This will connect the ISO file to the VMs virtual CD/DVD drive.
Toggle the carrot next to the CD/DVD drive 1 icon to reveal the details of the virtual device. For Status check the Connect At Power On checkbox. This will connect the ISO file to the VM’s virtual CD/DVD drive during boot up. Next Click on the Browse button for the CD/DVD Media.
- Navigate to and select the OS ISO file to be used for installation. Click OK to select the ISO.
Note
Teradici Cloud Access Software Plus CAS+ supports the following versions of Windows: - Windows 10 1809, 1903, 1909 (64-bit Professional and Enterprise) - Windows Server 2016, 2019 (single user only)
Right-click the virtual machine, and then select Power>Power On to start the virtual machine and boot from the .ISO to install the operating system.
The virtual machine boots from the selected .ISO.
Note
If you are creating a new virtual machine and using the vSphere Web Client’s VM console functionality, then the mouse may not be usable within the virtual machine until after the both the operating system and VMware tools have been installed.
Perform a Custom (fresh) installation of Windows 10 on the virtual machine.
During installation, Windows reboots the VM several times.
Disconnect the .ISO from the VM when Windows is done installing.
Go through the initial Windows setup wizard to name the computer, create a local account, set the time-zone, choose update installation policy, etc.
Windows 10 is now installed on the virtual machine.
Installing VMware Tools on the VM¶
After Windows completes the initial installation and configuration process, the next step is to install VMware Tools on the virtual machine.
Select the Summary tab from the virtual machine console.
Click the Install VMware Tools link in the yellow bar. The Install VMware Tools window displays.
Click Install VMware Tools.
Back in the virtual machine console, Windows 10 detects the CD image, and the AutoPlay window should open. If not, browse to the virtual CD-ROM in the virtual machine and access it manually.
Click Run
setup.exe
orsetup64.exe
.- The User Account Control popup may display.
If UAC prompts, then click
Yes
.
The installer begins, click
Next
.When prompted, select Complete installation, click Next, and accept all defaults.
When prompted, select Install to begin installation.
Click Finish in the VMware Tools installer and reboot the virtual machine when prompted. This reboot is critical to ensure the tools are now the loaded drivers.
VMware Tools is now installed on the virtual machine.
Note
Take a snapshot of the virtual machine to preserve your work. Label this snapshot pre-vGPU, and revert to it if you encounter any problems going forward, such as driver issues.
Additional Virtual Machine Settings¶
Perform the following additional tasks on the virtual machine as required:
Note
To evaluate browser based HTML5 applications, consider using newer browsers that utilize hardware acceleration within virtual desktop environments.
Turn Off Windows Firewall for all network types.
Important
These instructions assume that the VM is being used as a proof-of-concept only and that disabling the firewall will therefore pose only a minimal security breach. Always follow your established security procedures and best practices when setting up security for a production machine or any environment that can be accessed from outside your network.
Shut down the virtual machine once this is completed
Close the remote console; this will not be functional when vGPU is configured.
Adding the Golden Master to the Domain¶
By joining the VM to the Windows Active Directory domain you are then able to manage it as you would any physical desktop in the domain. Customize Windows on the virtual machine as follows:
Join the domain
Add appropriate Domain groups to Local Administrators
Adding a VM to the Domain¶
On the VM, go to Control Panel, System and Security, System.
This brings up the System Properties window, on the Computer Name tab click Change.
On the Computer Name/Domain Changes window, enter in an appropriate Computer name, then Domain name, and click OK. Our chosen naming is shown below, use what is appropriate for your POC/trial.
A security window pops up, fill in your specific domain administrator credentials and click OK.
On successful authentication you will see the following welcome pop-up showing your VM is now on the domain (the domain name should reflect your domain information).
Click OK and the VM needs to reboot to complete the process, click OK again and the VM reboots immediately.
Enabling the NVIDIA vGPU¶
Use the following procedure to enable vGPU support for your virtual machine (you must edit the virtual machine settings):
Power down the virtual machine.
Click on the VM in the Navigator window. Right click the VM and Edit Settings.
The Edit Settings dialog appears.
Click on the New Device bar and select Shared PCI device.
Click on Add to continue
The new PCI device will show the NVIDIA vGPU device has been added.
Use the GPU Profile selection bar to configure the GPU. Click Reserve all memory!
Click OK to complete the configuration.
Repeat steps 4 through 9 to add additional vGPUs.

Installing NVIDIA Driver in Windows Virtual Desktop¶
Start the virtual machine, and then connect to it using either VMware Remote Console through the vSphere Web Client or VMware Horizon Client (via Direct Connection). (When connected, a popup warning requesting that you restart the computer to apply changes will display the first time it is booted after enabling the NVIDIA vGPU.)
Click Restart Later to continue booting the virtual machine.
Important
Do not reboot the virtual machine if you have older nvidia drivers installed. doing this will cause a blue screen.
Log into Windows and open the Device Manager.
The Standard VGA Graphics Adapter displays in the Display adapters section of the Device Manager with an exclamation point by it to indicate a driver problem. This is normal.
Locate the NVIDIA driver and double-click the Setup icon to launch it. (Recommendation: Have the software on a share volume that can be mounted by the VM for quick access.).
Note
the version of NVIDIA must coincide with the revision of CAS+. For example, CAS+ version 20.07 requires NVIDIA driver version 443.05 to be used. More information can be found here: https://www.teradici.com/web-help/pcoip_agent/graphics_agent/windows/20.07/admin-guide/requirements/system-requirements/
Click OK to continue install.
The NVIDIA software license agreement window displays. Click the AGREE AND CONTINUE button to proceed.
The Installation Options window displays. Check the Custom (Advanced) radio button, then click Next. The Custom installation options window appears.
Check the Perform a clean installation checkbox, and then click Next.
A window displays when the NVIDIA Graphics Driver installation is complete.
Reboot the Virtual Machine to complete the install.
Note
After restarting, the mouse cursor may not track properly using VNC or vSphere console. If so, use Horizon Client to Direct Connect.
Installing Teradici Cloud Access Software¶
You need to install the correct version of Cloud Access Software Plus (CAS+) for your virtual machine.
Use the following procedure to install CAS+ on the virtual machine:
Navigate to: https://docs.teradici.com/find/product/cloud-access-software
Select and download the
Graphics Agent for Windows
- PCoIP Host OptionNote
As of September 2020, the latest version is:
pcoip-agent-graphics_20.07.0.exe
. Latest version is always defaulted as the first optionLaunch the installer.
The Installer Language window displays.
Select a language, then
OK
to proceed.The
Welcome Setup Window
displays.
Click
Next
to Proceed.PCoIP Agent Setup notification. Because the NVIDIA drivers has not been installed on the VM the installation wizard will message that it does not detect a discrete GPU. This is by design because when NVIDIA drivers are installed, the vSphere Web console or VMWARE Remote Console will not work. On next VM reboot the PCoIP Agent will detect and encode over NVIDIA NEVNC
Click
No
and Proceed with Installation.Accept the License Agreement values by clicking,
I Agree
.Chose installation locations then, Click Install to proceed
CAS+ installs on the virtual machine and the Installer Completed window displays when the installation process concludes.
Select the
I want to manually reboot later
.Click
Finish
to exit the installer.Teradici should provide you a registration code either for purchase or evaluation purposes. The registration code is tied to a number of concurrent licensing seats. Each running physical or virtual client will count against a pool of licenses tied this registration code. Under normal procedures, an instance can be snapshotted or created as a golden image with this registration on the image. As long as each instance can report to the licensing service via the internet. Each client will pull a license from the pool of available seats. If your organization operates as a “dark site” , a on premise licensing server maybe applicable.
Note
If you have not obtained a trail or production license, use the following URL to obtain them: https://connect.teradici.com/contact-us
Enter in a Registration Code. Click Next to proceed.
If your organization utilizes a proxy server to route traffic to the Internet, select checkbox option and enter the IP address of the proxy server. Click Next to proceed.
Click Finish to proceed.
Note
Teradici CAS+ is now installed on the virtual machine but still requires the installation of NVIDIA licenses for the CAS agent to function effectively.
Set PCoIP GPO for GPU offloading¶
In windows run windows, type ‘gpedit’ until windows auto-completes the “edit group policy” option is available.
Select the Edit group policy, option to continue.
Under Local Computer Policy > Computer Configuration, select the ‘Administrative Template’ folder.
Select the Computer Configuration > Administrative Template, option to continue.
Within the Administrative Template, Select the PCoIP Session Variables folder.
Select the Administrative Template > PCoIP Session Variables, option to continue.
Within the PCOIP Session Variables folder, Select the Overridable Administrative Default.
Select the Administrative Template > PCoIP Session Variables, option to continue.
Scroll through the setting policy setting on the right-hand side until you get to the Enable PCoIP Ultra GPU Optimization settings.
Click on Enable PCoIP Ultra GPU optimization, option to continue.
Enable the “Enable PCoIP GPU optimization” option.
Select the Enabled button option to continue.
Close the Group Policy Editor when finished.
Licensing NVIDIA vGPU Software¶
NVIDIA vGPU is a licensed product. When booted on a supported GPU, a vGPU runs at reduced capability until a license is acquired.
- The performance of an unlicensed vGPU is restricted as follows:
Frame rate is capped at 3 frames per second.
GPU resource allocations are limited, which will prevent some applications from running correctly.
On vGPUs that support CUDA, CUDA is disabled.
VGPU 6.0, 6.1 only: Screen resolution is limited to no higher than 1280×1024.
These restrictions are removed when a license is acquired. After you license NVIDIA vGPU, the VM that is set up to use NVIDIA vGPU can run all DirectX (up to and including DirectX12 and DX12-Raytracing on Turing architecture cards), OpenGL & Vulkan graphics applications. If licensing is configured, the virtual machine (VM) obtains a license from the license server when a vGPU is booted on these GPUs. The VM retains the license until it is shut down. It then releases the license back to the license server. Licensing settings persist across reboots and need only be modified if the license server address changes, or the VM is switched to running GPU pass through.
Note
For complete information about configuring and using NVIDIA vGPU software licensed features, including vGPU, refer to Virtual GPU Client Licensing User Guide.
Licensing NVIDIA vGPU on Windows¶
Open NVIDIA Control Panel.
Right-Click
on the Windows desktop and select NVIDIA Control Panel from the menu.Open Windows Control Panel and
double-click
the NVIDIA Control Panel icon.
In NVIDIA Control Panel, select the Manage License task in the Licensing section of the navigation panel.
The Manage License task pane shows that NVIDIA vGPU is currently unlicensed.
Note
If the Licensing section and Manage License task are not displayed in NVIDIA Control Panel, the system has been configured to hide licensing controls in NVIDIA Control Panel. For information about registry settings, see Virtual GPU Client Licensing User Guide.
Screen capture showing the Manage License option in NVIDIA Control Panel for a vGPU license
In the Primary License Server field, enter the address of your primary NVIDIA vGPU software License Server. The address can be a fully qualified domain name such as gridlicense1.example.com, or an IP address such as 10.31.20.45. If you have only one license server configured, enter its address in this field.
Leave the Port Number field under the Primary License Server field unset. The port defaults to 7070, which is the default port number used by NVIDIA vGPU software License Server.
In the Secondary License Server field, enter the address of your secondary NVIDIA vGPU software License Server. If you have only one license server configured, leave this field unset. The address can be a fully qualified domain name such as gridlicense2.example.com, or an IP address such as 10.31.20.46.
Leave the Port Number field under the Secondary License Server field unset. The port defaults to 7070, which is the default port number used by NVIDIA vGPU software License Server.
Click Apply to assign the settings. The system requests the appropriate license for the current vGPU from the configured license server.
The vGPU within the VM should now exhibit full frame rate, resolution, and display output capabilities. The VM is now capable of running the full range of DirectX and OpenGL graphics applications.
If the system fails to obtain a license, see Virtual GPU Client Licensing User Guide for guidance on troubleshooting.
Licensing NVIDIA vGPU on Linux¶
Start NVIDIA X Server Settings by using the method for launching applications provided by your Linux distribution. For example, on Ubuntu Desktop, open the Dash, search for
NVIDIA X Server Settings
, and click theNVIDIA X Server Settings
icon.In the NVIDIA X Server Settings window that opens, click
Manage NVIDIA License
. The License Edition section of the NVIDIA X Server Settings window shows that NVIDIA vGPU is currently unlicensed.In the Primary Server field, enter the address of your primary NVIDIA vGPU software License Server. The address can be a fully qualified domain name such as gridlicense1.example.com, or an IP address such as 10.31.20.45. If you have only one license server configured, enter its address in this field.
Leave the Port Number field under the Primary Server field unset. The port defaults to
7070
, which is the default port number used by NVIDIA vGPU software License Server.In the Secondary Server field, enter the address of your secondary NVIDIA vGPU software License Server. If you have only one license server configured, leave this field unset. The address can be a fully qualified domain name such as
gridlicense2.example.com
, or an IP address such as10.31.20.46
.Leave the Port Number field under the Secondary Server field unset. The port defaults to
7070
, which is the default port number used by NVIDIA vGPU software License Server.Click
Apply
to assign the settings. The system requests the appropriate license for the current vGPU from the configured license server.The vGPU within the VM should now exhibit full frame rate, resolution, and display output capabilities. The VM is now capable of running the full range of DirectX and OpenGL graphics applications.
If the system fails to obtain a license, see Virtual GPU Client Licensing User Guide for guidance on troubleshooting.
Finalizing the Installation¶
The final phase of the NVIDIA vGPU configuration is to connect to the virtual machine, verify settings, and then experience the power of fully virtualized GPU support in your favorite testing, benchmarking, multimedia, or 2D/3D/animation applications. Use the following procedure to finalize the installation.
Record in PCoIP Host address, the IP address assigned to the virtual machine by selecting the virtual machine, and then selecting the Summary tab.
Select the virtual machine in the vSphere Web Client and select the Summary tab.
Find the IP address assigned to the virtual machine by selecting the VM in the Navigator window and clicking on the Summary tab. The VM’s IP Address will appear in the window.
Note
The IP address information will only be displayed if the virtual machine has VMware Tools running and has successfully negotiated an IP address from a DHCP server or when using a static address.
Download the PCoIP Client on the device that will be used to connect to the VM.
For this example, we will be illustrating the windows PCoIP client, but there are versions for Linux, MAC, and Android also available.
Browse to https://docs.teradici.com/find/product/cloud-access-software/current and under the PCoIP Clients section click on the “Software Client for Windows” icon.
Select the Software Client for Windows option to continue.
From within the
Software Client for Windows
pop out display, click on the Download option.Click
Download
option to continueScroll all the way to the end of the Teradici EULA and click
Agree and download
.Click
Agree and download
option to continue.Save installer.
Once download is complete, browse to the download directory and right click the installer and chose
Run as administrator
.Note
If you receive a message from
User Access Control
, click yes to the messageChose the appropriate language in the “Installer Language” dialogue box.
Click
Next
in theWelcome
dialogue box.Click
I Agree
to the softwareEULA
.Click
Install
to theChoose Install Location
dialogue box.Choose to
Create a Desktop Shortcut
in the “Completing the Teradici PCoIP Client Setup”. Click “Finish” to complete the install process.From the desktop select the PCoIP Icon enter the IP address of the VDI desktop to connect to in the Hostname field and click Continue. (You are connecting directly to a desktop.
Click the
Connect Insecurely
option for the verify your connection dialogue box. (3rd party certification and verification process can be set-up in the future)Enter a
Username and Password
and clickLogin
to complete the connection process.Log into the virtual machine.
Verify PCoIP Ultra GPU optimization is enabled by verifying that there is a purple pixel in the bottom lest most corner of the screen.
Open Device Manager and confirm that the display adapter is now a vGPU display.
Open Display adapters in Device Manager.
Right click the desktop and select NVIDIA Control Panel.
Select System Information on the bottom left. Confirm the DirectX, graphics card, and driver versions and select Close when done.
If you plan to use this VM as your Gold Master Image, release the DHCP address before logging out and shutting down. Open a command prompt and enter ipconfig /release.
You will immediately lose connectivity to the VM. Use the vSphere Web Client to shut down the Guest OS.
A vGPU enabled virtual machine is now confirmed and verified to work with Teradici Cloud Access Manager Plus software.