xvfb-run(1)

💅 xvfb-run(1) — like, the General Commands Manual entry, but make it make sense ✨

okay so bestie, buckle up 🎀 this one's from the General Commands Manual and it's genuinely iconic once you get what it's doing. no cap.

🌸 NAME 🌸

xvfb-run — runs whatever X client or command you hand it inside a virtual X server environment. that's the whole vibe. 🦋

✨ SYNOPSIS ✨

xvfb-run [ options ] command

💖 DESCRIPTION 💖

so xvfb-run is basically a wrapper for the Xvfb(1x) command, and what it does is take the whole "ugh i have to set up a virtual X server by hand" situation and make it a one-liner. slay. you use it to run commands — usually an X client, or a script that's got a whole list of clients in it — inside a virtual X server environment. 🫶

here's the little routine it does, step by step:

• it sets up an X authority file (or, if you already gave it one with the options, it just uses yours),
• writes a cookie into it (peep xauth(1x) for the lore on that),
• then starts the Xvfb X server as a background process,
• and it remembers the process ID of Xvfb for later, because it's gonna need it. 🔥

then your specified command gets run, using the X display that corresponds to the Xvfb server it just started, plus the X authority file it created earlier. main character energy, honestly.

and when your command exits? it saves that status first, then goes into cleanup mode:

• the Xvfb server gets killed (using that process ID it stored earlier — iykyk),
• the X authority cookie gets removed,
• and the authority file gets deleted (but only if you didn't specify one yourself to use).

then xvfb-run exits with the exit status of your command. periodt. 💅

🚨 important: xvfb-run requires the xauth command to function. like, it genuinely cannot do its thing without it.

🎀 OPTIONS 🎀

• -a, --auto-servernum — tries to get a free server number, starting at 99, or at whatever you passed to --server-num. 🍓
• -e file, --error-file=file — stores output from xauth and Xvfb in file. the default is /dev/null, so by default you're seeing none of that. 🙈
• -f file, --auth-file=file — stores X authentication data in file. by default, a temporary directory called xvfb-run.PID gets created (where PID is the process ID of xvfb-run itself) inside the directory named by the environment variable TMPDIR — or /tmp if that variable is null or unset — and then the tempfile(1) command is used to create a file in that temp directory called Xauthority. 💖
• -h, --help — displays a usage message and exits. the classic. ✨
• -n servernumber, --server-num=servernumber — uses servernumber as the server number (but, like, go look at the -a, --auto-servernum option above first, bestie). the default is 99. 👑
• -l, --listen-tcp — enables TCP port listening in the X server. and honestly? for security reasons (aka avoiding denial-of-service attacks or exploits), TCP port listening is disabled by default. so only turn this on if you know what you're doing. 💀
• -p protocolname, --xauth-protocol=protocolname — uses protocolname as the X authority protocol. the default is ‘.’, which xauth interprets as its own default protocol, which is MIT-MAGIC-COOKIE-1. cute. 🦋
• -s arguments, --server-args=arguments — passes arguments to the Xvfb server. ⚠️ be careful to quote any whitespace characters that show up inside the arguments, so they don't get treated as separators for xvfb-run's own arguments. also, heads up: specifying ‘-nolisten tcp’ in arguments may override the function of xvfb-run's own -l, --listen-tcp option, and specifying the server number (like ‘:1’) may get ignored because of the way the X server parses its argument list. to do that second thing, use the xvfb-run option -n servernumber, --server-num=servernumber instead. the default is ‘-screen 0 1280x1024x24’. 🌈
• -w delay, --wait=delay — ignored, for compatibility with earlier versions. yeah. it's just there. ngl it's giving vestigial. 😭

💜 ENVIRONMENT 💜

• COLUMNS — indicates the width of the terminal device in character cells. this value is used for formatting diagnostic messages. if it's not set, the terminal gets queried using stty(1) to figure out its width. and if that fails? a value of ‘80’ is assumed. 🎀
• TMPDIR — specifies the directory in which to place xvfb-run's temporary directory for storage of the X authority file. only used if the -f or --auth-file options are not specified. 🌸

⭐ OUTPUT FILES ⭐

unless the -f or --auth-file options are specified, a temporary directory and a file within it get created (and, later, deleted) to store the X authority cookies used by the Xvfb server and the client(s) run under it. see tempfile(1). 📁

if -f or --auth-file are used, then the specified X authority file is only written to — it's not created or deleted (though xauth creates an authority file itself if you tell it to use one that doesn't already exist). 🙈

also, an error file with a user-specified name gets created if the -e or --error-file options are specified; see above. ✨

🔥 EXIT STATUS 🔥

xvfb-run uses its exit status as well as output to standard error to communicate diagnostics. and here's the important bit: the exit status of ‘1’ is not used, and should be interpreted as failure of the specified command. 💀

1. 0 — xvfb-run only uses this exit status if the -h, --help option is given. in all other situations, this may be interpreted as success of the specified command. 🎉
2. 2 — no command to run was specified. 😭
3. 3 — the xauth command is not available. 🚨
4. 4 — the temporary directory that was going to be used already exists. and since xvfb-run produces a uniquely named directory, this may indicate an attempt by another process on the system to exploit a temporary file race condition. like, be suspicious. 👀
5. 5 — a problem was encountered while cleaning up the temporary directory. 🧹
6. 6 — a problem was encountered while using getopt(1) to parse the command-line arguments. 😵‍💫

🌈 EXAMPLES 🌈

xvfb-run --auto-servernum --server-num=1 xlogo

runs the xlogo(1x) demonstration client inside the Xvfb X server on the first available server number greater than or equal to 1. ✨

xvfb-run --server-args="-screen 0 1024x768x24" ico -faces

runs the ico(1x) demonstration client (and passes it the -faces argument) inside the Xvfb X server, configured with a root window of 1024 by 768 pixels and a color depth of 24 bits. 🎨

🫶 little note, bestie: the demo X clients used in the examples above will not exit on their own, so you'll have to kill them before xvfb-run will exit. they're clingy like that. 💀

🙈 BUGS 🙈

see the Debian Bug Tracking System ⟨https://bugs.debian.org/xvfb⟩. and if you wish to report a bug in xvfb-run, please use the reportbug(1) command. 🐛

👑 AUTHOR 👑

xvfb-run was written by Branden Robinson and Jeff Licquia with sponsorship from Progeny Linux Systems. respect the OGs. 🫡

🦋 SEE ALSO 🦋

Xvfb(1x), xauth(1x)

---

and that's the whole page, bestie 🎀 this one's courtesy of the Debian Project, dated 2004-11-12 — vintage but still eating, fr fr. go run something in a virtual X server, you've got this 💜✨