Skip to content

Commit

Permalink
Doc: Clarify security risks of GLX + EGL back ends
Browse files Browse the repository at this point in the history 
(+ parentheses police)
  • Loading branch information
@dcommander
dcommander committed Jul 11, 2024
1 parent f10a08e commit 80e62ed
Show file tree
Hide file tree
Showing 7 changed files with 97 additions and 82 deletions.
26 changes: 13 additions & 13 deletions doc/advancedconfig.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ previous method:
the X server is on a different machine and assume that the 3D rendering
commands will be sent over the network. Thus, VirtualGL normally forces all
contexts to be direct in order to prevent severe readback performance
degradation with such applications (even on modern GPUs, and even when the
degradation with such applications. (Even on modern GPUs, and even when the
connection to the 3D X server is local, ''glReadPixels()'' can perform very
slowly if an indirect OpenGL context is used.)
{nl}{nl}
Expand Down Expand Up @@ -243,7 +243,7 @@ previous method:
order for pixel buffer objects (PBOs) to behave correctly. Since displaying
to an X proxy typically requires VirtualGL to read back the framebuffer in
BGRA format, enabling ''VGL_FORCEALPHA'' might be necessary in order to use
PBO readback mode with the aforementioned GPUs (as of this writing, nVidia
PBO readback mode with the aforementioned GPUs. (As of this writing, nVidia
GeForce adapters are known to require this.) See the
[[#VGL_READBACK][''VGL_READBACK'']] option for further information.

Expand Down Expand Up @@ -321,20 +321,20 @@ previous method:
VirtualGL cannot usually get away with ignoring ''glFlush()''. However, some
3D applications call ''glFlush()'' so often that VirtualGL cannot get away
with reading back/transporting a frame every time ''glFlush()'' is called,
either (see [[#VGL_SPOILLAST][''VGL_SPOILLAST'']] for more information on how
VirtualGL tries to handle this, under normal circumstances.)
either. (See [[#VGL_SPOILLAST][''VGL_SPOILLAST'']] for more information on
how VirtualGL tries to handle this, under normal circumstances.)
{nl}{nl}
Some 3D applications use ''glFlush()'' very liberally and intend for it to be
an intermediate rather than a final synchronization command. Such
applications will call ''glFinish()'' after a sequence of ''glFlush()''
calls, so for those applications, using ''glFlush()'' as a frame trigger is a
waste of resources and can sometimes create visual artifacts (for instance,
if the application clears the front buffer with a particular color, calls
''glFlush()'', then clears it again with another color. We wouldn't mention
it if it hadn't happened before.) For such applications, setting
''VGL_GLFLUSHTRIGGER'' to ''0'' should make them display properly with
VirtualGL. See [[#Application_Recipes][Application Recipes]] for a list of
3D applications that are known to require this.
waste of resources and can sometimes create visual artifacts. (For instance,
this can happen if the application clears the front buffer with a particular
color, calls ''glFlush()'', then clears it again with another color. We
wouldn't mention it if it hadn't happened before.) For such applications,
setting ''VGL_GLFLUSHTRIGGER'' to ''0'' should make them display properly
with VirtualGL. See [[#Application_Recipes][Application Recipes]] for a list
of 3D applications that are known to require this.

| Environment Variable | {pcode: VGL_GLLIB = __{l}__ } |
| Summary | __''{l}''__ = the location of an alternate OpenGL library |
Expand Down Expand Up @@ -649,8 +649,8 @@ previous method:
should be turned off when running benchmarks or other non-interactive 3D
applications. Turning off frame spoiling will force every frame rendered on
the server to be transported, and thus the frame rate reported by OpenGL
benchmarks will accurately reflect the end-to-end performance of VirtualGL
(though, in X proxy environments, this may still not accurately reflect the
benchmarks will accurately reflect the end-to-end performance of VirtualGL.
(However, in X proxy environments, this may still not accurately reflect the
frame rate seen by the user. See {ref prefix="Section ": Frame_Spoiling}.)
Disabling frame spoiling also prevents non-interactive 3D applications from
wasting graphics resources by rendering frames that will never be seen.
Expand Down
2 changes: 1 addition & 1 deletion doc/advancedopengl.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ into a single image (a "stereogram"), and thus it can be used with any image
transport. However, unlike anaglyphic stereo, passive stereo must be used
with specific display hardware, such as a 3D TV or monitor, that decodes the
left and right eye images from the stereogram and sends them separately to a
pair of 3D glasses (typically, this is accomplished by way of polarization.)
pair of 3D glasses. (Typically, this is accomplished by way of polarization.)

VirtualGL supports three methods of encoding stereograms:

Expand Down
4 changes: 2 additions & 2 deletions doc/configdialog.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,8 +128,8 @@ parameters in VirtualGL. Changes are communicated immediately to VirtualGL.
You can set the ''VGL_GUI'' environment variable to change the key sequence
used to pop up the VirtualGL Configuration dialog. If the default of
''ctrl-shift-f9'' is not suitable, then set ''VGL_GUI'' to any combination of
''ctrl'', ''shift'', ''alt'', and one of ''f1'', ''f2'', \.\.\., ''f12''
(these are not case sensitive.) For example:
''ctrl'', ''shift'', ''alt'', and one of ''f1'', ''f2'', \.\.\., ''f12''.
(These are not case sensitive.) For example:

#Verb: <<---
export VGL_GUI=ctrl-f9
Expand Down
98 changes: 53 additions & 45 deletions doc/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta name="language" content="en">
<meta name="date" content="2023-12-03T18:32:23">
<meta name="date" content="2024-07-11T12:35:22">
<meta name="generator" content="deplate.rb 0.8.5">
<title>User&rsquo;s Guide for VirtualGL 3.0.3</title>
<link rel="start" href="index.html" title="Frontpage">
Expand Down Expand Up @@ -953,16 +953,20 @@ <h2 id="hd006002">6.2&nbsp;GLX Back End: Granting Access to the 3D X Server</h2>
<p>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 <code>xauth</code>, one can obtain
&ldquo;untrusted&rdquo; 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 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.)</p>
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&rsquo;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 <code>xauth</code>, one can obtain &ldquo;untrusted&rdquo; 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.)</p>

<p>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
Expand Down Expand Up @@ -1026,8 +1030,8 @@ <h2 id="hd006002">6.2&nbsp;GLX Back End: Granting Access to the 3D X Server</h2>
<dl class="Description">
<dt class="Description-3 Description">Yes</dt>
<dd class="Description-3 Description">
Only users in the <code>vglusers</code> group can use the GLX back end
(the configuration script will create the <code>vglusers</code> group if
Only users in the <code>vglusers</code> group can use the GLX back end.
(The configuration script will create the <code>vglusers</code> group if
it doesn&rsquo;t already exist.) This is the most secure option, since
it prevents any users outside of the <code>vglusers</code> group from
accessing (and thus exploiting) the 3D X server.
Expand All @@ -1053,7 +1057,7 @@ <h2 id="hd006002">6.2&nbsp;GLX Back End: Granting Access to the 3D X Server</h2>
<dt class="Description-3 Description">Yes</dt>
<dd class="Description-3 Description">
Only users in the <code>vglusers</code> group can run OpenGL
applications on the VirtualGL server (the configuration script will
applications on the VirtualGL server. (The configuration script will
create the <code>vglusers</code> group if it doesn&rsquo;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
Expand Down Expand Up @@ -1182,7 +1186,7 @@ <h3 id="hd006002001">6.2.1&nbsp;Sanity Check</h3>

<p>You should also examine the output of the <code>glxinfo</code> 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 <code>P</code> in
and has Pbuffer support. (The latter is indicated by a <code>P</code> in
the last column.) Example:</p>

<pre class="verbatim">
Expand Down Expand Up @@ -1237,11 +1241,14 @@ <h2 id="hd006003">6.3&nbsp;EGL Back End: Granting Access to the GPU(s)</h2>
<dt class="Description-3 Description">Yes</dt>
<dd class="Description-3 Description">
Only users in the <code>vglusers</code> group can run OpenGL
applications on the VirtualGL server (the configuration script will
applications on the VirtualGL server. (The configuration script will
create the <code>vglusers</code> group if it doesn&rsquo;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.
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.
</dd>
<dt class="Description-3 Description">No</dt>
<dd class="Description-3 Description">
Expand Down Expand Up @@ -1325,8 +1332,8 @@ <h2 id="hd006006">6.6&nbsp;Un-Configuring the Server</h2>
VirtualGL from accessing a GPU in that manner. Additionally, this
option will re-enable the <code>XTEST</code> 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.)</p>
default. (By default, only root or the user that is currently logged
into the application server locally can access the framebuffer devices.)</p>

<p>After selecting Option 2, you must restart the display manager before
the changes will take effect.</p>
Expand Down Expand Up @@ -1465,8 +1472,8 @@ <h3 id="hd008001001">8.1.1&nbsp;Procedure</h3>
</dd>
<dt class="Description-3 Description">Cygwin clients</dt>
<dd class="Description-3 Description">
Start a new xterm if one isn&rsquo;t already started (right-click on the
Cygwin/X taskbar icon, then select
Start a new xterm if one isn&rsquo;t already started. (Right-click on
the Cygwin/X taskbar icon, then select
<strong class="filename">Applications&ndash;&gt;xterm</strong>.)
</dd>
</dl>
Expand Down Expand Up @@ -2367,8 +2374,8 @@ <h3 id="hd0016001003">16.1.3&nbsp;Passive Stereo</h3>
be used with any image transport. However, unlike anaglyphic stereo,
passive stereo must be used with specific display hardware, such as a 3D
TV or monitor, that decodes the left and right eye images from the
stereogram and sends them separately to a pair of 3D glasses (typically,
this is accomplished by way of polarization.)</p>
stereogram and sends them separately to a pair of 3D glasses.
(Typically, this is accomplished by way of polarization.)</p>

<p>VirtualGL supports three methods of encoding stereograms:</p>

Expand Down Expand Up @@ -2452,7 +2459,7 @@ <h2 id="hd0017001">17.1&nbsp;VirtualGL&rsquo;s Built-In Profiling System</h2>

<p>The easiest way to uncover bottlenecks in VirtualGL&rsquo;s image
pipeline is to set the <code>VGL_PROFILE</code> environment variable to
<code>1</code> on both server and client (passing an argument of
<code>1</code> on both server and client. (Passing an argument of
<code>+pr</code> to <code>vglrun</code> on the server has the same
effect.) This will cause VirtualGL to measure and report the throughput
of various stages in the pipeline. For example, here are some
Expand Down Expand Up @@ -2889,7 +2896,7 @@ <h1 id="hd0018"><a name="file018"></a>18&nbsp;The VirtualGL Configuration Dialog
default of <code>ctrl-shift-f9</code> is not suitable, then set
<code>VGL_GUI</code> to any combination of <code>ctrl</code>,
<code>shift</code>, <code>alt</code>, and one of <code>f1</code>,
<code>f2</code>, ..., <code>f12</code> (these are not case sensitive.)
<code>f2</code>, ..., <code>f12</code>. (These are not case sensitive.)
For example:</p>

<pre class="verbatim">
Expand Down Expand Up @@ -2982,15 +2989,16 @@ <h2 id="hd0019001">19.1&nbsp;Faker Settings</h2>
they detect that the X server is on a different machine and assume that
the 3D rendering commands will be sent over the network. Thus,
VirtualGL normally forces all contexts to be direct in order to prevent
severe readback performance degradation with such applications (even on
modern GPUs, and even when the connection to the 3D X server is local,
<code>glReadPixels()</code> can perform very slowly if an indirect
OpenGL context is used.) <br /><br /> However, some 3D applications
intentionally try to create indirect contexts so that these contexts can
be shared, and those applications may not work properly when the
contexts are forced to be direct. For such applications, setting
<code>VGL_ALLOWINDIRECT</code> to <code>1</code> will cause VirtualGL to
honor the application&rsquo;s request for an indirect OpenGL context.
severe readback performance degradation with such applications. (Even
on modern GPUs, and even when the connection to the 3D X server is
local, <code>glReadPixels()</code> can perform very slowly if an
indirect OpenGL context is used.) <br /><br /> However, some 3D
applications intentionally try to create indirect contexts so that these
contexts can be shared, and those applications may not work properly
when the contexts are forced to be direct. For such applications,
setting <code>VGL_ALLOWINDIRECT</code> to <code>1</code> will cause
VirtualGL to honor the application&rsquo;s request for an indirect
OpenGL context.
<div class="important"><p class="important">
EGL does not support indirect OpenGL contexts, so this option requires the GLX back end.
</p></div>
Expand Down Expand Up @@ -3381,7 +3389,7 @@ <h2 id="hd0019001">19.1&nbsp;Faker Settings</h2>
correctly. Since displaying to an X proxy typically requires VirtualGL
to read back the framebuffer in BGRA format, enabling
<code>VGL_FORCEALPHA</code> might be necessary in order to use PBO
readback mode with the aforementioned GPUs (as of this writing, nVidia
readback mode with the aforementioned GPUs. (As of this writing, nVidia
GeForce adapters are known to require this.) See the
<a href="#VGL_READBACK"><code>VGL_READBACK</code></a><a name="idx0029"></a>
option for further information.
Expand Down Expand Up @@ -3529,7 +3537,7 @@ <h2 id="hd0019001">19.1&nbsp;Faker Settings</h2>
<code>glFlush()</code>. However, some 3D applications call
<code>glFlush()</code> so often that VirtualGL cannot get away with
reading back/transporting a frame every time <code>glFlush()</code> is
called, either (see
called, either. (See
<a href="#VGL_SPOILLAST"><code>VGL_SPOILLAST</code></a><a name="idx0030"></a>
for more information on how VirtualGL tries to handle this, under normal
circumstances.) <br /><br /> Some 3D applications use
Expand All @@ -3538,12 +3546,12 @@ <h2 id="hd0019001">19.1&nbsp;Faker Settings</h2>
applications will call <code>glFinish()</code> after a sequence of
<code>glFlush()</code> calls, so for those applications, using
<code>glFlush()</code> as a frame trigger is a waste of resources and
can sometimes create visual artifacts (for instance, if the application
clears the front buffer with a particular color, calls
<code>glFlush()</code>, then clears it again with another color. We
wouldn&rsquo;t mention it if it hadn&rsquo;t happened before.) For such
applications, setting <code>VGL_GLFLUSHTRIGGER</code> to <code>0</code>
should make them display properly with VirtualGL. See
can sometimes create visual artifacts. (For instance, this can happen
if the application clears the front buffer with a particular color,
calls <code>glFlush()</code>, then clears it again with another color.
We wouldn&rsquo;t mention it if it hadn&rsquo;t happened before.) For
such applications, setting <code>VGL_GLFLUSHTRIGGER</code> to
<code>0</code> should make them display properly with VirtualGL. See
<a href="#Application_Recipes">Application
Recipes</a><a name="idx0031"></a> for a list of 3D applications that are
known to require this.
Expand Down Expand Up @@ -4179,9 +4187,9 @@ <h2 id="hd0019001">19.1&nbsp;Faker Settings</h2>
benchmarks or other non-interactive 3D applications. Turning off frame
spoiling will force every frame rendered on the server to be
transported, and thus the frame rate reported by OpenGL benchmarks will
accurately reflect the end-to-end performance of VirtualGL (though, in X
proxy environments, this may still not accurately reflect the frame rate
seen by the user. See Section
accurately reflect the end-to-end performance of VirtualGL. (However, in
X proxy environments, this may still not accurately reflect the frame
rate seen by the user. See Section
<a href="#Frame_Spoiling" class="ref">17.2</a>.) Disabling frame
spoiling also prevents non-interactive 3D applications from wasting
graphics resources by rendering frames that will never be seen.
Expand Down
4 changes: 2 additions & 2 deletions doc/perfmeasurement.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
** VirtualGL's Built-In Profiling System

The easiest way to uncover bottlenecks in VirtualGL's image pipeline is to
set the ''VGL_PROFILE'' environment variable to ''1'' on both server and client
(passing an argument of ''+pr'' to ''vglrun'' on the server has the same
set the ''VGL_PROFILE'' environment variable to ''1'' on both server and
client. (Passing an argument of ''+pr'' to ''vglrun'' on the server has the same
effect.) This will cause VirtualGL to measure and report the throughput of
various stages in the pipeline. For example, here are some measurements from a
dual Pentium 4 server communicating with a Pentium III client on a 100-megabit
Expand Down
Loading

0 comments on commit 80e62ed

Please sign in to comment.