* Using VirtualGL with setuid/setgid Executables

''vglrun'' can be used to launch either binary executables or shell scripts,
but there are a few things to keep in mind when launching a shell script with
''vglrun''.  When you launch a shell script with ''vglrun'', the VirtualGL
Faker ({file: libvglfaker.so}) and ''dlopen()'' interposer
({file: libdlfaker.so}) will be preloaded into every executable that the script
launches.  Normally this is innocuous, but if the script calls any executables
that have the setuid and/or setgid permission bits set, then the dynamic linker
will refuse to preload the faker libraries into those executables.  One of the
following warnings will be printed for each setuid/setgid executable that the
script tries to launch:

	Linux :: {:}
#Verb: <<---
ERROR: ld.so: object 'libvglfaker.so' from LD_PRELOAD cannot be preloaded: ignored.
---
#Verb: <<---
ERROR: ld.so: object 'libdlfaker.so' from LD_PRELOAD cannot be preloaded: ignored.
---

	Solaris :: {:}
#Verb: <<---
ld.so.1: warning: libvglfaker.so: open failed: No such file in secure directories
---
#Verb: <<---
ld.so.1: warning: libdlfaker.so: open failed: No such file in secure directories
---

These are just warnings, and the setuid/setgid executables will continue to run
(without VirtualGL preloaded into them.)  However, if you want to get rid of
the warnings, an easy way to do so is to simply edit the application script and
make it store the value of the ''LD_PRELOAD'' environment variable until right
before the 3D application executable is launched.  For instance, consider the
following 3D application script:

#Pverb: <<---
#!/bin/sh
__setuid-executable__
__3D-application-executable__
---

You could modify the script as follows:

#Pverb: <<---
#!/bin/sh
LD_PRELOAD_SAVE=$LD_PRELOAD
LD_PRELOAD=
export LD_PRELOAD

__setuid-executable__

LD_PRELOAD=$LD_PRELOAD_SAVE
export LD_PRELOAD

__3D-application-executable__
---

This procedure may be necessary to work around certain other interaction issues
between VirtualGL and the launch scripts of specific 3D applications.  See
[[#Application_Recipes][Application Recipes]] for more details.

If the 3D application that you are intending to run with VirtualGL is itself a
setuid/setgid executable, then further steps are required.  Otherwise, the
3D application will launch without VirtualGL preloaded into it.  Forcing
VirtualGL to be preloaded into setuid/setgid executables has security
ramifications, so please be aware of these before you do it.  By applying one
of the following workarounds, you are essentially telling the operating system
that you trust the security and stability of VirtualGL as much as you
trust the security and stability of the operating system.  While we're
flattered, we're not sure that we're necessarily deserving of that accolade, so
if you are in a security-critical environment, apply the appropriate level of
paranoia here.

{anchor: setuid_linux}
To force VirtualGL to be preloaded into setuid/setgid executables on Linux,
you have to first make sure that the faker libraries are installed in the
system library path (usually {file: /usr/lib}, {file: /usr/lib64},
{file: /usr/lib32}, or {file: /usr/lib/i386-linux-gnu}).  Next, make the faker
libraries setuid executables.  To do this, run the following commands as root:

#Pverb: <<---
chmod u+s /usr/__lib__/libvglfaker.so
chmod u+s /usr/__lib__/libdlfaker.so
---

where __''lib''__ is ''lib'', ''lib64'', ''lib32'', or ''lib/i386-linux-gnu'',
depending on your system.

On Solaris, you can force VirtualGL to be preloaded into setuid/setgid
executables by adding the VirtualGL library directories to the Solaris "secure
path."  Solaris keeps a tight lid on what goes into {file: /usr/lib} and
{file: /lib}, and by default, it will only allow libraries in those paths to be
preloaded into an executable that is setuid and/or setgid.  Generally, 3rd
party packages are forbidden from installing anything into {file: /usr/lib} or
{file: /lib}, but you can use the ''crle'' utility to add other directories to
the operating system's list of secure paths.  In the case of VirtualGL, you
would execute one of the following commands (as root):

	32-bit VirtualGL: :: {:}
	#Verb: <<---
	crle -u -s /opt/VirtualGL/lib32
	---

	64-bit VirtualGL: :: {:}
	#Verb: <<---
	crle -64 -u -s /opt/VirtualGL/lib64
	---
