X11TRACE(1)

📦 version 1.3.1, in fedora 43, fedora 44

👑 X11TRACE(1) 👑 — ok bestie, let's spy on some X11 traffic 💅

Welcome to the manual page for x11trace, and yes, the manual name is literally X11TRACE, we're doing this properly. Grab a snack, this one's a banger. 🍓

✨ NAME ✨

x11trace — trace communication between X11 client and server 🦋

🎀 SYNOPSIS 🎀

x11trace [ options ] [ -s | -k ] [ [ -W ] [ -- ] command args ... ]

💖 DESCRIPTION 💖

Okay so picture this: x11trace fakes an X server and forwards all the connections to a real X server, and while it's doing all that it shows you the communication between clients in (well, theoretically) human readable form. It's giving wiretap but make it ✨debugging✨.

If you give it a command, x11trace runs that named command with $DISPLAY set to the faked X server. And if that command exits before any connections are even made, x11trace exits immediately too — unless you specified -W. Rude? Maybe. Correct? Yes. 😌

💅 OPTIONS 💅

  • -I directory — go look into directory for protocol description files. (i.e. the directory where the .proto files can be found, iykyk.)
  • -s | --stopwhendone (default) — terminate when all forwarded clients have disconnected. (Or, if a program was run, once the program has finished and all connections are closed.) The classic "we're done here" energy. 🫶
  • -k | --keeprunning — if all clients disconnected, just wait for new ones to connect. Main character energy, refusing to leave the party. 👑
  • -W | --waitforclient — do not stop when the started program terminates before any connection was made. (Might be necessary if the program forks to background, bestie. That's the whole point.)
  • -d name | --display name — forward connections to the X server specified by name instead of the one specified by the environment variable DISPLAY.
  • -D name | --fakedisplay name — fake display name instead of $FAKEDISPLAY or :9 respectively.
  • -f filename | --authfile filename — add an -f filename to the arguments for all calls to xauth, to get the authentication tokens of the X server to connect to.
  • -F filename | --newauthfile filename — add an -f filename to the arguments for all calls to xauth, to save the authentication tokens to connect to the faked X server.
  • -c | --copyauthentication (default) — copy the authentication tokens for the X server to connect to, so that clients connecting to our fake server will use them.

The commands run are roughly equivalent to:

xauth add $FAKEDISPLAY . `xauth list $DISPLAY | awk '$2=="MIT-MAGIC-COOKIE-1" {print $3}'`
Not that only MIT-MAGIC-COOKIE-1 tokens are copied, as x11trace does not yet support to change the authentication tokens so that XDM-AUTHORIZATION-1 would be possible. 💀
  • -n | --nocopyauthentication — do not call xauth and do fiddle with authentication tokens, but leave that to the user to handle. You got this, you're so capable. 🫡
  • -e | --denyextensions — modify all server replies to say there are no extensions available. (As x11trace does supports only a small number of extensions anyway and calls all extended requests "unknown" and all replies to such requests "unexpected".) It's giving "no thoughts, head empty" but for extensions. 🙈
  • -w | --readwritedebug — print how many bytes are read and/or written, and when. Numbers girlies rise. 🔥
  • -m count | --maxklistlength count — print only the first count many elements of all lists. Trimming the fat, periodt.
  • -i | --interactive — only sent requests from the client to the server after interactive confirmation. Confirmation is given by pressing enter, or a number followed by enter, via stdin. This can give funny results when multiple clients are tunneled. 😭
  • -o | --outfile filename — dump output into filename instead of stdout.
  • -b | --buffered — do not write every line on its own, but wait until buffers are full. Speeds up things a little bit when outputting to a file. Not very useful at all together with -i. Just so you know.
  • --timestamps — print a timestamp before each line.
Note that the time a packet is printed is between the time a packet is received and the time a packet is sent, but it gives no other information than that. Lowkey important, don't overthink it.
  • --relative-timestamps — print a timestamp relative to the beginning of the connection before each line.
Note that the time a packet is printed is between the time a packet is received and the time a packet is sent, but it gives no other information than that. Same disclaimer, bestie.
  • --monotonic-timestamps — print a CLOCK_MONOTONIC (see clock_gettime(3)) timestamp each time a package is printed. This is likely to be the uptime of your system.
Note that the time a packet is printed is between the time a packet is received and the time a packet is sent, but it gives no other information than that. Yes, again. It's a whole thing. 💜
  • --print-offsets — print offsets of all fields (useful to debug nested lists in protocol descriptions). Nested lists could never, but here we are. 🪆
  • --print-counts — print counts (useful to debug lists in protocol descriptions).

🌈 ENVIRONMENT VARIABLES 🌈

  • DISPLAY — without --display, the content of this variable is used to determine the server to connect to. (And without -n given to xauth, to get the authentication tokens for this display.)
  • FAKEDISPLAY — without --fakedisplay, the content of this variable is used to determine how to listen for clients. (And without -n given to xauth, to set the authentication tokens for this display.) If neither is given, x11trace will try :9. Bestie's backup plan. 🧚
  • XAUTHORITY — without -n and without -f or -F, your xauth program will most likely look into this variable for the file to get/save the authentication tokens from/into. If this is not set, it will most likely use $HOME/.Xauthority.

😭 REPORTING BUGS 😭

Report bugs to <brlink@debian.org> or the Debian BTS. We're not mad, we're just disappointed. (No we're not, we love feedback.) 🫶

👀 SEE ALSO 👀

xauth(1), x(7x),

Copyright © 2005 Bernhard R. Link

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Read it and weep (respectfully). 💅

And that's the whole page, bestie — this was x11trace, dated 26 June 2009, and you absolutely ate that reading comprehension. Now go trace something. 💖✨

📦 where this page comes from