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

** Granting Access to the 3D X Server

VirtualGL requires access to a GPU in the application server so that it can
create off-screen pixel buffers (Pbuffers) and redirect the 3D rendering from
X windows into these Pbuffers.  Unfortunately, accessing a GPU on Linux and
Unix systems requires going through an X server.  On such systems, 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 (the X server attached to the GPU(s).  Refer to
the figures in {ref prefix="Chapter ": Overview}.)

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.
Using ''xauth'', one can obtain "untrusted" X authentication keys that prevent
such exploits, but unfortunately, those untrusted keys also disallow access to
the 3D hardware.  Thus, it is necessary to grant full, trusted access to the 3D
X server for any users that will need to run VirtualGL.  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.

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

	#. Shut down the display manager:

		Ubuntu Linux servers running GDM :: {:}
			#Verb: <<---
			/etc/init.d/gdm stop
			---

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

		SuSE Linux servers :: {:}
			#Verb: <<---
			/etc/init.d/xdm stop
			---

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

		Red Hat/Fedora Linux servers with systemd :: {:}
			#Verb: <<---
			systemctl stop gdm.service
			---

		Linux servers running MDM :: {:}
			#Verb: <<---
			/etc/init.d/mdm stop
			---

		Solaris 10 servers running GDM :: {:}
			#Verb: <<---
			svcadm disable gdm2-login
			---

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

		Solaris servers running dtlogin :: {:}
			#Verb: <<---
			/etc/init.d/dtlogin stop
			---

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

		FreeBSD servers running KDM :: {:}
			#Verb: <<---
			/usr/local/kde4/etc/rc.d/kdm4 stop
			---

	#. 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 in GLX mode''.)

	#. {:}

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

		Yes :: Only users in the ''vglusers'' group can use VirtualGL (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 :: VirtualGL 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.

		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 X server or framebuffer device access to the
		''vglusers'' group, then edit ''/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:

		Ubuntu Linux servers running GDM :: {:}
			#Verb: <<---
			/etc/init.d/gdm start
			---

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

		SuSE Linux servers :: {:}
			#Verb: <<---
			/etc/init.d/xdm start
			---

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

		Red Hat/Fedora Linux servers with systemd :: {:}
			#Verb: <<---
			systemctl start gdm.service
			---

		Linux servers running MDM :: {:}
			#Verb: <<---
			/etc/init.d/mdm start
			---

		Solaris 10 servers running GDM :: {:}
			#Verb: <<---
			svcadm enable gdm2-login
			---

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

		Solaris servers running dtlogin :: {:}
			#Verb: <<---
			/etc/init.d/dtlogin start
			---

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

		FreeBSD servers running KDM :: {:}
			#Verb: <<---
			/usr/local/kde4/etc/rc.d/kdm4 start
			---

*** Sanity Check
#OPT: noList! plain!

To verify that the application server is ready to run VirtualGL, 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
	---

	!!! NOTE: ''xauth'' and ''xdpyinfo'' are in ''/usr/openwin/bin'' on Solaris
	systems.

	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
''xdpyinfo'' to verify that ''XTEST'' does not show up in the list of
extensions.

You should also examine the output of ''glxinfo'' 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 3D
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.

** Using VirtualGL with Multiple GPUs

VirtualGL can redirect the OpenGL commands from a 3D application to any GPU
in the server machine.  In order for this to work, 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 the GPUs to be individually addressed 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 they can
be individually addressed by setting ''VGL_DISPLAY'' to (or invoking
''vglrun -d'' with) '':0.0'', '':1.0'', '':2.0'', etc.

** SSH Server Configuration

The application server's SSH daemon should have the ''X11Forwarding'' option
enabled and the ''UseLogin'' option disabled.  This is configured in
''sshd_config'', which is usually located under ''/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 in GLX mode'') will remove any shared access to
the 3D X server and thus prevent VirtualGL from accessing the 3D hardware 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.)

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

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