man(8)

💖 Xdummy — from the man(8) girlies 💖

okay bestie, buckle up, because this one is a whole journey 🎀

✨ NAME ✨

Xdummy — a hack to run Xorg or XFree86 X server with the "dummy" video driver. that's it, that's the name, it's giving chaos but make it ✨functional✨

✨ SYNOPSIS ✨

Xdummy <Xdummy-args> <Xserver-args>

✨ DESCRIPTION ✨

okay so. Xdummy is a hack that lets you run a stock Xorg(1) or XFree86(1) X server with the "dummy" (RAM-only framebuffer) video driver, and the way it does that means it AVOIDS all the cursed stuff: the Linux VT switching, opening device files in /dev, keyboard and mouse conflicts, and every other problem that normally comes with using "dummy". no cap.

in other words, it's trying to make Xorg/XFree86 with the "dummy" device driver act way more like Xvfb(1). bestie glow-up fr fr 💅

the primary motivation for the Xdummy script is to give x11vnc a virtual X server, but with more features than Xvfb (or Xvnc) — though honestly you could use it for other reasons too (e.g. better automated testing than with Xvfb). and one thing that is lowkey iconic: the dummy server supports RANDR dynamic resizing while Xvfb does not. slay.

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

to pull this off, 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). but listen — 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. do that. please. 🫶

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. (yes that's the original wording, we don't edit, we preserve 🌸)

---

✨ 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. (gaslight gatekeep getuid ✨)

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. nope. not happening. 💅

• :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. iykyk 💜

• -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. main character responsibility energy 😤

• -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 number of settings are tweaked besides Driver.
• -xf86config file — same vibe as -config, the XFree86-flavored spelling.

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. 😭 (no thoughts, just vibes, and the vibes are fragile)

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.

---

okay that's the whole page bestie, you ate it up 💅✨ this was version 1.0, dated 19 Mar 2019, from the man(8) manual — Xdummy man page, love her, protect her, run her as non-root first 🎀💖🦋