Using ThinLinc^® with VirtualBox^®/VirtualGL: Installation and Best Practice

Documentation for ThinLinc version 3.2.0

---

---

Preface

This document contains guidelines and best practice information relating to the integration of ThinLinc with VirtualBox and VirtualGL.

Starting with v3.2.0, ThinLinc has support for integration with VirtualBox. This allows users to connect remotely to a personal virtualised machine within the ThinLinc environment, and allows administrators to designate resources and virtual machines amongst users.

ThinLinc users wishing to achieve remote 3D graphics acceleration in a virtualised environment may do so using ThinLinc in combination with VirtualBox and VirtualGL. This allows users to connect remotely to a virtual machine and run accelerated OpenGL applications, with 3D graphics acceleration being processed entirely on the server side.

While this document is intended to ease the installation and configuration of such an environment, it should be considered a technical document and some degree of technical competence is assumed.

Both VirtualBox and VirtualGL are third-party products, and are not directly supported by Cendio AB or its partners.

Host Recommendations

Server (host) hardware requirements depend in large part on the intended use-case; for example, how many concurrent users should be supported, and what kind of software will be run. However, below we offer some guidelines to follow when selecting hardware for use with ThinLinc and VirtualBox.

CPU

The server CPU(s) should support a 64-bit instruction set (x86-64), and provide as many physical cores as possible (at least 4). Note that 'logical' cores presented to the operating system via hyperthreading techniques do not count as physical cores – if possible, hyperthreading should be disabled in the BIOS.

RAM

VirtualBox machines will consume as much RAM as they are given in their configuration, as soon as the machine is started. The major factors in determining the amount of RAM to install in the server are therefore how many machines will be running concurrently, and how much RAM each individual machine requires. Not counting the RAM required by the guest operating system, there should be enough RAM available for each machine to fully consume its quota.

Disk

Normally, ThinLinc will create each user's machine as a 'delta image', which is based on an immutable 'golden image'. These delta images will initially be much smaller than the golden image, however if they are persistent (i.e. not reset to an initial state after each shutdown), they can potentially grow to the full size of the golden image after some time. If you are planning to run persistent machines, it is therefore recommended to have at least as much space in your 'home' partition as is required by the number of users multiplied by the size of the golden image.

Disks should be as fast as possible, and preferably configured as a high-performance RAID array such as RAID 10. If your server supports RAID at the hardware level, this is generally preferable over a software implementation.

GPU

For users who wish to have server-side graphics acceleration within their VirtualBox machine, the server will need to have a graphics card installed. On-board GPUs are generally insufficient for this purpose, and should ideally be disabled in BIOS once a dedicated graphics card is installed.

The card should be high-bandwidth (PCIe x16), have dedicated memory (at least 500MB), support OpenGL, and have fully supported Linux® drivers available. One example of such hardware is the NVIDIA® Quadro® FX series of cards.

Operating System

The server should run a 64-bit Linux distribution which also provides the 32-bit libraries required to run ThinLinc. Tested distributions can be found in the ThinLinc Administrator's Guide, at http://www.cendio.com/resources/docs/tag/requirements_server.html.

Guest Recommendations

'Guest' machines are the virtual machines which the users will connect to, and run inside VirtualBox on the host machine described above. The following recommendations will help you to get the best performance out of your guest machines.

VirtualBox Machine Configuration

• Provide at least 2 virtual CPUs per virtual machine
• Makes sure that the machine has enough RAM (based on expected usage) to prevent swapping
• Use SATA as the preferred (virtual) HDD connector
• If using VirtualGL acceleration, increase the amount of video memory available to the machine, and check 'Enable 3D Acceleration' in the settings
• Normally, you will want your machines to use a bridged network configuration. This will ensure that they are reachable from the outside, via their own IP address.

Guest OS Configuration

The following assumes that Windows is being used as the guest operating system, as this is the most common case:

• Install VirtualBox Guest Additions
• If the machine needs to be part of an Active Directory domain, install the WTS Tools package from the ThinLinc server CD. Instructions for doing this can be found at http://www.cendio.com/resources/docs/tag/install_wts_tools.html#id2602488. You will also need to configure the 'tlcloneprep' service; instructions for doing so can be found at http://www.cendio.com/resources/docs/tag/vbox_administration.html#tlcloneprep
• Configure user authentication for those users who require access to VirtualBox machines. Remote Access (RDP) must also be enabled for these users
• Disable complex screensavers and unnecessary theme enhancements
• Disable automatic file system indexing:
  • Go to 'My Computer'
  • Right-click on the C:, and select 'Properties'
  • Uncheck the indexing function in the properties dialogue
• Antivirus programs can periodically consume large amounts of CPU and disk I/O, especially at boot. If you run antivirus on your virtual machines, then check the settings to ensure that operations such as filesystem scans are not run on a regular basis
• After installing any required software, defragment the filesystem of the golden image before exporting
• Make sure that no unnecessary services are being started at boot:
  • Run 'msconfig' from the command line, or by using the 'Run...' dialogue
  • Select the 'Startup' tab
  • Disable unnecessary services
• Disable system protection:
  • Right-click on 'My Computer'
  • Select Properties -> Advanced System Settings -> System Protection
  • Select the C:
  • Click 'Configure...'
  • Under the 'Restore Settings' section, select 'Turn off system protection'

Installation

VirtualGL makes OpenGL hardware acceleration available to clients who are connecting remotely. When installed and configured correctly, this includes applications run from within a VirtualBox virtual machine.

If an application is available for both Windows and Linux, then the preferred approach is to run the application on Linux natively, using VirtualGL to provide acceleration. However, for applications which are only available for Windows, the following method can be used to provide OpenGL acceleration within a VirtualBox machine.

GPU Driver Installation

In order for graphics acceleration to work correctly, you must install a driver which fully supports your GPU. In the case of NVIDIA cards, this normally means installing the proprietary driver provided by NVIDIA, as the default driver 'nouveau' provided by most Linux distributions is insufficient for this task. Some distributions which rely on nouveau must also have the nouveau driver explicitly disabled after installation, to allow the loading of the proprietary version on boot.

If your distribution provides its own NVIDIA driver package, then you may want to install the driver using your distribution's package manager. One advantage of this method is that you don't have to manually re-install the driver after a kernel upgrade, as this will be done automatically for you. However, proprietary NVIDIA drivers provided with distributions are normally a number of versions behind the latest NVIDIA release, so check the driver changelogs carefully to look for any important bug-fixes in later releases, and also that your GPU is fully supported by your distribution's driver version.

Some distributions require that you enable additional repositories in order to install proprietary components. Check your distribution's documentation for more information if you are unsure.

If your distribution does not provide the proprietary NVIDIA driver, or you require a more recent version, the driver may be installed manually. Because the driver modules must be built against the currently running kernel, it is important to remember that the driver must be re-installed after every kernel upgrade. Make sure that your administrator is aware of this before rebooting after a kernel upgrade.

It is recommended that the driver installation is performed locally at the physical terminal, rather than remotely via SSH or similar.

The following steps provide guidelines on how to manually install a driver for an NVIDIA GPU on Linux; for other driver types, consult the relevant vendor documentation.

• Download the latest NVIDIA driver for your architecture. The file should look like 'NVIDIA-Linux-<arch>-<version>.run'
• Change the permissions of the file to be executable, either by using a file manager or running the command 'chmod u+x NVIDIA-Linux-<arch>-<version>.run'
• You will probably need to have a basic build environment available before running the installer, so that the scripts can build the kernel modules for your kernel if no pre-compiled modules can be found. The NVIDIA installer will alert you if anything is missing. These requirements include:
  • Kernel source/headers. These can normally be installed as a package from your distribution's repositories, and must match the version of the kernel you are running. Once installed, the kernel sources should be automatically upgraded with every kernel upgrade.
  • GCC – the GNU Compiler Collection. This should be available as a package from your distribution's repository. Note that the GCC version used to build the NVIDIA kernel modules must match the version used to build the kernel itself. Many distributions provide a version of GCC which is newer than the one used to build the kernel, however older versions are normally available in the repositories by explicitly specifying the version number during installation. If the NVIDIA installer complains about GCC version conflicts, note the version of GCC used to compile your kernel and install this version. With some distributions, you will also need to make sure that /usr/bin/gcc points to the correct version of the GCC binary, so update this symlink if necessary.
• The NVIDIA installer requires that no X server is running during installation. For most distributions, this can be achieved by switching to a runlevel with no graphical interface; for example, by running 'init 3' as root at the command line.
• At this point it should be possible to complete the driver installation by running the executable binary as root, e.g. './NVIDIA-Linux-<arch>-<version>.run'.
• If your distribution uses the nouveau driver by default, the NVIDIA installer will attempt to blacklist this module to prevent it from loading at boot. However, this will not work for all distributions. If you find that the nouveau kernel module is still loading at boot, and therefore preventing the proprietary NVIDIA driver from loading, you can explicitly disable nouveau by adding a kernel parameter to your bootloader configuration:
  • Most modern distributions use GRUB as the bootloader, the configuration file for which can normally be found at /boot/grub/grub.conf or /boot/grub/menu.lst.
  • Edit this file, and under the relevant stanza for your running kernel, append 'rdblacklist=nouveau' to the line which begins with 'kernel'. This will prevent nouveau from loading at boot.
  • Note that for some distributions (e.g. Ubuntu), upgrading the kernel will not migrate custom kernel parameters to the new kernel. In this case, you should look for the line beginning with '#kopt=' in the GRUB configuration file, and add the kernel parameter there instead.
• If you intend to run the server without a screen connected, or if your screen does not support DDC (Display Data Channel) protocols, the NVIDIA kernel module may refuse to load as no screens can be found. This error will be logged in the Xorg log file, normally at /var/log/Xorg.0.log. If this is the case, you may need to add the following option line to the relevant 'Device' section of your /etc/X11/xorg.conf file; 'Option “ConnectedMonitor” “DFP”'.
• Reboot, and confirm that the NVIDIA proprietary driver is loaded and working correctly:
  • Check the Xorg log file for any warnings or error messages
  • Running 'lsmod | grep nouveau' at the command line should indicate that the nouveau module is not being loaded
  • Running 'lsmod | grep nvidia' at the command line should indicate that the NVIDIA module is loaded
  • Running 'glxinfo | grep direct' should output 'direct rendering: Yes'
  • Running 'glxgears' from the desktop should be smooth and provide a high framerate

VirtualGL Installation

Installation of VirtualGL, with links to the relevant sections of VirtualGL online documentation, is described more fully in the ThinLinc Administrator's Guide (TAG) at http://www.cendio.com/resources/docs/tag/virtualgl.html. This section will briefly outline the process for installing VirtualGL on Linux; for more detailed information, consult the link above.

The following instructions use a YUM-based distribution as an example. For other distributions, use the corresponding package manager.

• Download the latest version of VirtualGL from http://www.virtualgl.org/Downloads/VirtualGL
• Install the RPM package using your package manager, e.g. 'yum install ./VirtualGL-<version>.rpm'. This should resolve and download any dependencies.
• After installation, run vglserver_config. This is usually located at '/opt/VirtualGL/bin/vglserver_config'. Answer the questions as follows:
  • Select '1' for 'Configure server for use with VirtualGL in GLX mode'
  • Select 'n' when asked if you want to restrict X server access to the vglusers group
  • Select 'n' when asked if you want to restrict framebuffer access to the vglusers group
  • Select 'n' when asked if you want to disable the XTEST extension
  • Select 'X' at the final question to exit the configuration
• Restart the display manager
• To force VirtualGL to be preloaded into setgid/setuid executables on Linux, certain VirtualGL libraries must be made setuid. This is required for use with ThinLinc, and instructions on how to do this can be found at http://www.virtualgl.org/vgldoc/2_2_1/#setuid_linux.

VirtualBox Installation

If your distribution provides VirtualBox in its repositories, then this is usually the preferred method of installation. Note that ThinLinc requires VirtualBox version 4.0.4 or greater, so check which version your distribution provides before installing. In most cases you will want to install the Open Source Edition (OSE) of VirtualBox – check the VirtualBox documentation and licensing agreement if you are unsure which edition best fits your requirements.

If your distribution does not provide a suitable version of VirtualBox, then you can download and install it manually. More information on VirtualBox installation and configuration can be found in the TAG and VirtualBox documentation, however the following guidelines may be followed after VirtualBox installation is complete:

• It is recommended to create a special user to be used for administering virtual machines. In this document we will assume that the user 'vboxadmin' has been created for this purpose
• Log in as 'vboxadmin', and start VirtualBox by running the command 'VirtualBox'. This will create a folder in the home directory for vboxadmin which contains virtual machines and their configurations
• Create a new virtual machine, following the guidelines mentioned in section 3.1 above. This machine will become the 'golden image' for the users' machines
• Install the guest operating system, following the guidelines mentioned in section 3.2 above. Install any applications required by the users.
• When your machine is ready, shut it down and close VirtualBox, making sure to remove any unneeded installation media from the virtual machine.

ThinLinc Installation

If you haven't installed the ThinLinc server already at this point, you should do so now. Instructions for doing so can be found in the ThinLinc Administrator's Guide at http://www.cendio.com/resources/docs/tag/installation.html.

Once ThinLinc is installed on the server, connect to the server as 'vboxadmin' using the ThinLinc client and open a terminal window on the desktop. Run the following command as vboxadmin:

vglrun VirtualBox --startvm <golden_image_name> --fullscreen

Where <golden_image_name> is the name of the machine you created above. This should present you with a virtual machine desktop which you can use to test the performance of OpenGL applications, and check that 3D acceleration is working as it should from within your VirtualBox machine.

Configuration

Exporting the Golden Image

In order for the golden image in vboxadmin's home directory to be available to ThinLinc, it needs to be exported. This will create a copy of the original machine, and store it in a pre-defined location; by default, /opt/vboxdata. This copy will then be used as the base image for all user machines. Any changes to the image can then be made by modifying the virtual machine in the home directory of vboxadmin, and re-exporting the machine once the changes are complete.

To export the golden image, log in as vboxadmin and run the command 'tl-export-virtualbox <golden_image_name>'. More information on exporting machines can be

found at the following URL:

http://www.cendio.com/resources/docs/tag/virtualbox_configuration.html#virtualbox_export

ThinLinc Configuration

VirtualBox configuration options in ThinLinc are specified in the file /opt/thinlinc/etc/conf.d/vdi-user.hconf. Typically, the default values in this file should be sufficient, however if you want your users' machines to remain persistent (i.e. not reset to an initial state after shutdown), or you require single sign-on for machines which are members of an Active Directory domain, you may need to adjust the configuration. See

http://www.cendio.com/resources/docs/tag/thinlinc_configuration.html#vdi_virtualbox for details on each of the configuration options.

In order for VirtualBox machines to show up in the profile selector, they must be configured in /opt/thinlinc/etc/conf.d/profiles.hconf. This configuration file comes with an example VirtualBox stanza by default, under the heading [/profiles/vbox1]. Find this stanza within the file, and modify the cmdline and testcmd parameters so that the example machine name of 'vm1' is replaced by the name of your exported golden image, referenced as <golden_image_name> above.

Logging into ThinLinc should now present you with a 'VirtualBox VDI Machine' profile which, when selected, launches your own personal copy of the golden image you created, complete with OpenGL accelerated 3D graphics.

Appendix

ThinLinc® is a registered trademark of Cendio AB.

VirtualBox® is a registered trademark of Oracle Corporation.

Linux® is a registered trademark of Linus Torvalds.

NVIDIA® and Quadro® are registered trademarks of NVIDIA.