Provided by: x11vnc_0.9.16-9_amd64 bug

NAME

       Xdummy - A hack to run Xorg or XFree86 X server with the "dummy" video driver

SYNOPSIS

           Xdummy <Xdummy-args> <Xserver-args>

DESCRIPTION

           A hack to run a stock Xorg(1) or XFree86(1) X server with the "dummy"
           (RAM-only framebuffer) video driver such that it AVOIDS the Linux VT
           switching, opening device files in /dev, keyboard and mouse conflicts,
           and other problems associated with the normal use of "dummy".

           In other words, it tries to make Xorg/XFree86 with the "dummy"
           device driver act more like Xvfb(1).

           The primary motivation for the Xdummy script is to provide a virtual X
           server for x11vnc but with more features than Xvfb (or Xvnc); however
           it could be used for other reasons (e.g. better automated testing
           than with Xvfb.)  One nice thing is the dummy server supports RANDR
           dynamic resizing while Xvfb does not.

           So, for example, x11vnc+Xdummy terminal services are a little better
           than x11vnc+Xvfb.

           To achieve this, while running the real Xserver Xdummy intercepts
           system and library calls via the LD_PRELOAD method and modifies
           the behavior to make it work correctly (e.g. avoid the VT stuff.)
           LD_PRELOAD tricks are usually "clever hacks" and so might not work
           in all situations or break when something changes.

           WARNING: Take care in using Xdummy, although it never has it is
           possible that it could damage hardware.  One can use the -prconf
           option to have it print out the xorg.conf config that it would use
           and then inspect it carefully before actually using it.

           This program no longer needs to be run as root as of 12/2009.
           However, if there are problems for certain situations (usually older
           servers) it may perform better if run as root (use the -root option.)
           When running as root remember the previous paragraph and that Xdummy
           comes without any warranty.

           gcc/cc and other build tools are required for this script to be able
           to compile the LD_PRELOAD shared object.  Be sure they are installed
           on the system.  See -install and -uninstall described below.

           Your Linux distribution may not install the dummy driver by default,
           e.g:

               /usr/lib/xorg/modules/drivers/dummy_drv.so

           some have it in a package named xserver-xorg-video-dummy you that
           need to install.

OPTIONS

           Xdummy-args:

           -install    Compile the LD_PRELOAD shared object and install it
                   next to the Xdummy script file as:

                     /usr/bin/Xdummy.so

                   When that file exists it is used as the LD_PRELOAD
                   shared object without recompiling.  Otherwise,
                   each time Xdummy is run the LD_PRELOAD shared
                   object is compiled as a file in /tmp (or -tmpdir)

                   If you set the environment variable
                   INTERPOSE_GETUID=1 when building, then when
                   Xdummy is run as an ordinary user, the shared
                   object will interpose getuid() calls and pretend
                   to be root.  Otherwise it doesn't pretend to
                   be root.

                   You can also set the CFLAGS environment variable
                   to anything else you want on the compile cmdline.

           -uninstall    Remove the file:

                     /usr/bin/Xdummy.so

                   The LD_PRELOAD shared object will then be compiled
                   each time this program is run.

           The X server is not started under -install, -uninstall, or -prconf.

           :N      The DISPLAY (e.g. :15) is often the first
                   argument.  It is passed to the real X server and
                   also used by the Xdummy script as an identifier.

           -geom geom1[,geom2...]    Take the geometry (e.g. 1024x768) or list
                   of geometries and insert them into the Screen
                   section of the tweaked X server config file.
                   Use this to have a different geometry than the
                   one(s) in the system config file.

                   The option -geometry can be used instead of -geom;
                   x11vnc calls Xdummy and Xvfb this way.

           -nomodelines    When you specify -geom/-geometry, Xdummy will
                   create Modelines for each geometry and put them
                   in the Monitor section.  If you do not want this
                   then supply -nomodelines.

           -depth n    Use pixel color depth n (e.g. 8, 16, or 24). This
                   makes sure the X config file has a Screen.Display
                   subsection of this depth.  Note this option is
                   ALSO passed to the X server.

           -DEPTH n    Same as -depth, except not passed to X server.

           -tmpdir dir    Specify a temporary directory, owned by you and
                   only writable by you.  This is used in place of
                   /tmp/Xdummy.$USER/..  to place the Xdummy.so
                   shared object, tweaked config files, etc.

           -nonroot    Run in non-root mode (working 12/2009, now default)

           -root   Run as root (may still be needed in some
                   environments.)  Same as XDUMMY_RUN_AS_ROOT=1.

           -nosudo Do not try to use sudo(1) when re-running as root,
                   use su(1) instead.

           -xserver path    Specify the path to the Xserver to use.  Default
                   is to try "Xorg" first and then "XFree86".  If
                   those are not in $PATH, it tries these locations:
                       /usr/bin/Xorg
                       /usr/X11R6/bin/Xorg
                       /usr/X11R6/bin/XFree86

           -n      Do not run the command to start the X server,
                   just show the command that Xdummy would run.
                   The LD_PRELOAD shared object will be built,
                   if needed.  Also note any XDUMMY* environment
                   variables that need to be set.

           -prconf Print, to stdout, the tweaked Xorg/XFree86
                   config file (-config and -xf86config server
                   options, respectively.)  The Xserver is not
                   started.

           -notweak    Do not tweak (modify) the Xorg/XFree86 config file
                   (system or server command line) at all.  The -geom
                   and similar config file modifications are ignored.

                   It is up to you to make sure it is a working
                   config file (e.g. "dummy" driver, etc.)
                   Perhaps you want to use a file based on the
                   -prconf output.

           -debug  Extra debugging output.

           -strace strace(1) the Xserver process (for troubleshooting.)
           -ltrace ltrace(1) instead of strace (can be slow.)

           -h, -help    Print out this help.

           Xserver-args:

           Most of the Xorg and XFree86 options will work and are simply
           passed along if you supply them.  Important ones that may be
           supplied if missing:

           :N      X Display number for server to use.

           vtNN    Linux virtual terminal (VT) to use (a VT is currently
                   still used, just not switched to and from.)

           -config file        Driver "dummy" tweaked config file, a
           -xf86config file    number of settings are tweaked besides Driver.

           If -config/-xf86config is not given, the system one
           (e.g. /etc/X11/xorg.conf) is used.  If the system one cannot be
           found, a built-in one is used.    Any settings in the config file
           that are not consistent with "dummy" mode will be overwritten
           (unless -notweak is specified.)

           Use -config xdummy-builtin to force usage of the builtin config.

           If "file" is only a basename (e.g. "xorg.dummy.conf") with no /'s,
           then no tweaking of it is done: the X server will look for that
           basename via its normal search algorithm.  If the found file does
           not refer to the "dummy" driver, etc, then the X server will fail.

EXAMPLES:

           Xdummy -install

           Xdummy :1

           Xdummy -debug :1

           Xdummy -tmpdir ~/mytmp :1 -nolisten tcp

       startx example:

           startx -e bash -- Xdummy :2 -depth 16

           (if startx needs to be run as root, you can su(1) to a normal
           user in the bash shell and then launch ~/.xinitrc or ~/.xsession,
           gnome-session, startkde, startxfce4, etc.)

       xdm example:

           xdm -config /usr/local/dummy/xdm-config -nodaemon

           where the xdm-config file has line:

                DisplayManager.servers:         /usr/local/dummy/Xservers

           and /usr/local/dummy/Xservers has lines:

                :1 local /usr/local/dummy/Xdummy :1 -debug
                :2 local /usr/local/dummy/Xdummy :2 -debug

               (-debug is optional)

       gdm/kdm example:

           TBD.

       Root permission and x11vnc:

           Update: as of 12/2009 this program no longer must be run as root.
           So try it as non-root before running it as root and/or the
           following schemes.

           In some circumstances X server program may need to be run as root.
           If so, one could run x11vnc as root with -unixpw (it switches
           to the user that logs in) and that may be OK, some other ideas:

           - add this to sudo via visudo:

               ALL ALL = NOPASSWD: /usr/local/bin/Xdummy

           - use this little suid wrapper: /*
        * xdummy.c
        *
          cc -o ./xdummy xdummy.c
          sudo cp ./xdummy /usr/local/bin/xdummy
          sudo chown root:root /usr/local/bin/xdummy
          sudo chmod u+s /usr/local/bin/xdummy
        *
        */ #include <unistd.h> #include <stdlib.h> #include <sys/types.h> #include <stdio.h>

       int main (int argc, char *argv[]) {
           extern char **environ;
           char str[100];
           sprintf(str, "XDUMMY_UID=%d", (int) getuid());
           putenv(str);
           setuid(0);
           setgid(0);
           execv("/usr/local/bin/Xdummy", argv);
           exit(1);
           return 1; }

NOTES

           The Xorg/XFree86 "dummy" driver is currently undocumented.  It works
           well in this mode, but it is evidently not intended for end-users.
           So it could be removed or broken at any time.

           If the display Xserver-arg (e.g. :1) is not given, or ":" is given
           that indicates Xdummy should try to find a free one (based on
           tcp ports.)

           If the display virtual terminal, VT, (e.g. vt9) is not given that
           indicates Xdummy should try to find a free one (or guess a high one.)

           This program is not completely secure WRT files in /tmp (but it tries
           to a good degree.)  Better is to use the -tmpdir option to supply a
           directory only writable by you.  Even better is to get rid of users
           on the local machine you do not trust :-)

           Set XDUMMY_SET_XV=1 to turn on debugging output for this script.