* Configuring a Linux or Unix Machine as a VirtualGL Server
{anchor: Unix_Config}

** Initial System Configuration

Before configuring VirtualGL, you should first ensure that:

1. The appropriate GPU drivers have been installed on the machine.  With few
exceptions, you should install the drivers supplied by your GPU vendor rather
than the drivers supplied by your O/S distribution.  See
{ref prefix="Section ": Linux_Requirements}.

If you intend to configure the machine for use with the GLX back end, then you
should also ensure that:

1. The 3D X server has been configured to use the GPU drivers you installed
above.

2. The machine has an appropriate display manager (such as GDM, KDM, or
LightDM) installed and has been configured to start the display manager and 3D
X server at boot time.  This is the default with most modern Linux and Unix
distributions.

	!!! On Wayland-enabled Linux machines running GDM, configuring the machine
	for use with the GLX back end will disable the ability to log in locally with
	a Wayland session.  In general, logging in locally once the machine has been
	configured for use with the GLX back end is discouraged, as this could
	disrupt VirtualGL's connection to the 3D X server and thus cause OpenGL
	applications running with VirtualGL to abort or freeze.

3. Accelerated OpenGL is working properly in the 3D X server.
	* If the 3D X server is not headless, then this can be verified by logging
	into the X server locally and running ''glxinfo''.
	* If the 3D X server is headless, then proceed with the instructions below,
	and the [[#Sanity_Check][Sanity Check]] section will provide you with an
	opportunity to verify that the 3D X server is using accelerated OpenGL.

More specific instructions are unfortunately outside of the scope of this
guide, since they will vary from system to system.

** GLX Back End: Granting Access to the 3D X Server

VirtualGL requires access to a GPU in the application server so that it can
create off-screen buffers and redirect the 3D rendering from X windows into
these buffers.  When using the GLX back end, accessing a GPU requires going
through an X server attached to that GPU (the 3D X server), so the only way to
share the application server's GPU(s) among multiple users is to grant those
users access to the 3D X server.

It is important to understand the security risks associated with this.  Once a
user has access to the 3D X server, there is nothing that would prevent the
user from logging keystrokes or reading back images from that X server.  A user
with 3D X server and framebuffer device access can also read back the contents
of an off-screen buffer created by another user, provided that the off-screen
buffer's drawable ID is known and provided that the GPU driver uses DRI2
(example: nVidia proprietary drivers) rather than DRI3 (example: Mesa-based
drivers.)  Using ''xauth'', one can obtain "untrusted" X authentication keys
that prevent such exploits, but unfortunately, those untrusted keys also
disallow access to the GPU.  Thus, it is necessary to grant full, trusted
access to the 3D X server for any users that will need to use the GLX back end.
Unless you fully trust the users to whom you are granting this access, then
you should avoid logging in locally to the 3D X server (particularly as root)
unless absolutely necessary.  (Logging in locally to the 3D X server is
discouraged anyhow, for reasons explained in the previous section.)

This section will explain how to configure a VirtualGL server such that
selected users can use the GLX back end, even if the server is sitting at the
login prompt.

	#. Shut down the display manager.  Examples:

		Red Hat/Fedora/SuSE Linux servers :: {:}
			#Verb: <<---
			init 3
			---

		Ubuntu Linux servers running LightDM :: {:}
			#Verb: <<---
			service lightdm stop
			---

		FreeBSD servers running GDM :: {:}
			#Verb: <<---
			/usr/local/etc/rc.d/gdm stop
			---

		Solaris 11/OpenSolaris servers running GDM :: {:}
			#Verb: <<---
			svcadm disable gdm
			---

	#. Log in as root from the text console (or remotely using SSH.)

	#. Run

		#Verb: <<---
		/opt/VirtualGL/bin/vglserver_config
		---

	#. Select option 1 (''Configure server for use with VirtualGL (GLX + EGL back
		ends)''.)

	#. {:}

		#Verb: <<---
		Restrict 3D X server access to vglusers group (recommended)?
		[Y/n]
		---

		Yes :: Only users in the ''vglusers'' group can use the GLX back end.  (The
			configuration script will create the ''vglusers'' group if it doesn't
			already exist.)  This is the most secure option, since it prevents any
			users outside of the ''vglusers'' group from accessing (and thus
			exploiting) the 3D X server.

		No :: The GLX back end can be used by any user that successfully logs into
			the VirtualGL server.  The 3D X server can also be accessed (and
			potentially exploited) by any user who is logged into the VirtualGL
			server.  If you choose this option, it is recommended that you also
			disable the ''XTEST'' extension (see below.)

	#. {:}

		#Verb: <<---
		Restrict framebuffer device access to vglusers group (recommended)?
		[Y/n]
		---

		Yes :: Only users in the ''vglusers'' group can run OpenGL applications on
			the VirtualGL server.  (The configuration script will create the
			''vglusers'' group if it doesn't already exist.)  This limits the
			possibility that an unauthorized user could snoop the 3D framebuffer
			device(s) and thus see (or alter) the output of a 3D application that is
			being used with VirtualGL.

		!!! If you are using a recent release of GDM, then the ''gdm'' account must
		be added to the ''vglusers'' group.

		No :: Any authenticated user can run OpenGL applications on the VirtualGL
			server.  If it is necessary for users outside of the ''vglusers'' group
			to log in locally to this server and run OpenGL applications, then this
			option must be selected.

	#. {:}

		#Verb: <<---
		Disable XTEST extension (recommended)?
		[Y/n]
		---

		Yes :: Disabling ''XTEST'' will not prevent a user from logging keystrokes
			or reading images from the 3D X server, but if a user has access to the
			3D X server, disabling ''XTEST'' will prevent them from inserting
			keystrokes or mouse events and thus hijacking local X sessions on that X
			server.

		!!! If you are using GDM 2.14 through 2.20, it will be necessary to run
		''gdmsetup'' and manually add an argument of ''-tst'' to the X server
		command line to disable ''XTEST'' for the first time.  After this,
		''vglserver_config'' should be able to disable and enable ''XTEST''
		properly.

		!!! GDM 2.22 and later no longer provide a means of editing the X server
		command line, so disabling ''XTEST'' will not work.  The only known
		alternative as of this writing is to use a different display manager.

		No :: x11vnc and ''x0vncserver'' both require ''XTEST'', so if you need to
			attach a VNC server to the 3D X server, then it is necessary to answer
			"No" (and thus leave ''XTEST'' enabled.)

	#. If you chose to restrict 3D X server or framebuffer device access to the
		''vglusers'' group, then edit {file: /etc/group} and add ''root'' to the
		''vglusers'' group.  If you choose, you can also add additional users to
		the group at this time.  Note that any user you add to ''vglusers'' must
		log out and back in again before their new group permissions will take
		effect.

	#. Restart the display manager:

		Red Hat/Fedora/SuSE Linux servers :: {:}
			#Verb: <<---
			init 5
			---

		Ubuntu Linux servers running LightDM :: {:}
			#Verb: <<---
			service lightdm start
			---

		FreeBSD servers running GDM :: {:}
			#Verb: <<---
			/usr/local/etc/rc.d/gdm start
			---

		Solaris 11/OpenSolaris servers running GDM :: {:}
			#Verb: <<---
			svcadm enable gdm
			---

*** Sanity Check
{anchor: Sanity_Check}
#OPT: noList! plain!

To verify that the application server is ready to be used with the GLX back
end, log out of the server, log back into the server using SSH, and execute the
following commands in the SSH session:

	If you restricted 3D X server access to ''vglusers'' :: {:}
	#Verb <<---
	xauth merge /etc/opt/VirtualGL/vgl_xauth_key
	xdpyinfo -display :0
	/opt/VirtualGL/bin/glxinfo -display :0 -c
	---

	If you did not restrict 3D X server access :: {:}
	#Verb <<---
	xdpyinfo -display :0
	/opt/VirtualGL/bin/glxinfo -display :0 -c
	---

Both commands should output a list of visuals and should complete with no
errors.  If you chose to disable the ''XTEST'' extension, then check the output
of the ''xdpyinfo'' command to verify that ''XTEST'' does not show up in the
list of extensions.

You should also examine the output of the ''glxinfo'' command to ensure that at
least one of the visuals is 24-bit or 32-bit TrueColor and has Pbuffer support.
(The latter is indicated by a ''P'' in the last column.)  Example:

	#Verb <<---
	    visual  x   bf lv rg d st  colorbuffer  ax dp st accumbuffer  ms  cav  drw
	  id dep cl sp  sz l  ci b ro  r  g  b  a F bf th cl  r  g  b  a ns b eat  typ
	------------------------------------------------------------------------------
	0x151 24 tc  0  32  0 r  y  .  8  8  8  0 .  4 24  8 16 16 16 16  0 0 None PXW
	---

If none of the visuals has Pbuffer support, then this is most likely because
there is no 3D acceleration, which is most likely because the correct GPU
drivers are not installed (or are misconfigured.)  Lack of 3D acceleration is
also typically indicated by the word ''Mesa'' in the client GLX vendor string
and/or the OpenGL vendor string, and the words ''Software Rasterizer'' in the
OpenGL renderer string.

** EGL Back End: Granting Access to the GPU(s)

When using the EGL back end, the only way to share the application server's
GPU(s) among multiple users is to grant those users access to the device(s)
associated with the GPU(s).

This section will explain how to configure a VirtualGL server such that
selected users can use the EGL back end.

	#. Log in as root from the text console (or remotely using SSH.)

	#. Run

		#Verb: <<---
		/opt/VirtualGL/bin/vglserver_config
		---

	#. Select option 2 (''Configure server for use with VirtualGL (EGL back end
		only)''.)

	#. {:}

		#Verb: <<---
		Restrict framebuffer device access to vglusers group (recommended)?
		[Y/n]
		---

		Yes :: Only users in the ''vglusers'' group can run OpenGL applications on
			the VirtualGL server.  (The configuration script will create the
			''vglusers'' group if it doesn't already exist.)  This limits the
			possibility that an unauthorized user could snoop the 3D framebuffer
			device(s) and thus see (or alter) the output of a 3D application that is
			being used with VirtualGL.  Note, however, that such an exploit should
			not normally be possible with the EGL back end, since it redirects 3D
			rendering into renderbuffer objects that are not accessible by other
			processes.

		No :: Any authenticated user can run OpenGL applications on the VirtualGL
			server.  If it is necessary for users outside of the ''vglusers'' group
			to log in locally to this server and run OpenGL applications, then this
			option must be selected.

	#. If you chose to restrict framebuffer device access to the ''vglusers''
		group, then edit {file: /etc/group} and add ''root'' to the ''vglusers''
		group.  If you choose, you can also add additional users to the group at
		this time.  Note that any user you add to ''vglusers'' must log out and
		back in again before their new group permissions will take effect.

*** Sanity Check
{anchor: Sanity_Check_EGL}
#OPT: noList! plain!

To verify that the application server is ready to be used with the EGL back
end, log out of the server, log back into the server using SSH, and execute the
following command in the SSH session:

	#Verb <<---
	/opt/VirtualGL/bin/eglinfo egl0
	---

This command should output a list of EGL configs and should complete with no
errors.

** Using VirtualGL with Multiple GPUs

VirtualGL can redirect the OpenGL commands from a 3D application to any GPU in
the VirtualGL server.  In order for this to work with the GLX back end,
however, all of the GPUs must be attached to different screens on the same X
server or to different X servers.  Attaching them to different screens is the
easiest and most common approach, and this allows a specific GPU to be selected
by setting ''VGL_DISPLAY'' to (or invoking ''vglrun -d'' with) '':0.0'',
'':0.1'', '':0.2'', etc.  If the GPUs are attached to different X servers, then
a specific GPU can be selected by setting ''VGL_DISPLAY'' to (or invoking
''vglrun -d'' with) '':0.0'', '':1.0'', '':2.0'', etc.

Setting ''VGL_DISPLAY'' to (or invoking ''vglrun -d'' with) a DRI device path
(''/dev/dri/card0'', ''/dev/dri/card1'', ''/dev/dri/card2'', etc.) or an EGL
device ID (''egl0'', ''egl1'', ''egl2'', etc.) enables the EGL back end and
selects the specified GPU.  See {ref prefix="Section ": VGL_DISPLAY} for more
details.

** SSH Server Configuration

If you intend to use the VGL Transport, then the application server's SSH
daemon should have the ''X11Forwarding'' option enabled and the ''UseLogin''
option disabled.  This is configured in {file: sshd_config}, which is usually
located under {file: /etc/ssh}.

** Un-Configuring the Server

You can use the ''vglserver_config'' script to restore the security settings
that were in place before VirtualGL was installed.  Option 2 (''Unconfigure
server for use with VirtualGL (GLX + EGL back ends)'') will remove any shared
access to the 3D X server and thus prevent VirtualGL from accessing a GPU in
that manner.  Additionally, this option will re-enable the ''XTEST'' extension
on the 3D X server and will restore the framebuffer device permissions to their
default.  (By default, only root or the user that is currently logged into the
application server locally can access the framebuffer devices.)

After selecting Option 2, you must restart the display manager before the
changes will take effect.

Option 4 (''Unconfigure server for use with VirtualGL (EGL back end only)'')
will restore the framebuffer device permissions to their default.

	!!! Unconfiguring the server does not remove the ''vglusers'' group.
