nxagent(1)

📦
version 3.5.99.27 · 5 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 nxagent 💖

okay so you wanna know about nxagent — the NX Agent (Xserver), manual section 1. buckle up bestie, this one's a whole journey 🦋

✨ NAME ✨

nxagent — a nested Xserver optimized for remote computing. that's it, that's the name, slay 💅

🌸 SYNOPSIS 🌸

nxagent [options]

🎀 DESCRIPTION 🎀

okay so nxagent is an X server for remote application/desktop access, and it's basically in the same friend group as Xnest or Xephyr. same vibe, different energy ✨

here's the tea: nxagent implements a very efficient compression of the X11 protocol, and that compression is called the NX protocol. no cap.

the NX protocol is what makes your X applications actually usable over high latency and low bandwidth networks, and it still gives you that local, LAN-like usage experience even when you're connecting from completely off-site locations (think cable modem or GSM). it's giving ✨magic✨ honestly.

nxagent can totally be used standalone as a nested X server (with NX protocol disabled) — that works fine — but its real benefits? those show up when you use it over remote connections via the nxcomp compression library. the counterpart application on the other end (i.e. the client) is called nxproxy. they're a duo, iykyk 🫶

when it's used in proxy <-> agent mode, nxagent adds the feature of being suspendible. sessions can be started from one client, suspended, and then resumed from another (or the same) client. iconic behavior, truly 👑

nxagent and nxproxy are utilized by various remote application/desktop frameworks for providing server-side GUI application access from remote client systems.

and currently, nxagent is co-maintained by three of these projects: The Arctica Project, TheQVD, and X2Go. three whole parents, main character energy fr fr 💜

🦋 STARTING THE SERVER 🦋

nxagent should be run in user space. other than the system's local X.org server, nxagent does not require to be run as root. we love a low-maintenance icon 🌈

when it's bundled with a remote application framework, you normally don't have to launch nxagent manually. nxagent startup is usually managed by the underlying framework (e.g. Arctica Session Manager, X2Go Server, etc.). so like... it just happens. gorgeous.

when nxagent starts up (e.g. by typing nxagent -ac :1 in a terminal window), it typically launches in "windowed desktop" mode. on your local X server, a new window appears — and that window is itself an X server. windowception 😭

however, nxagent also supports rootless (or seamless) application mode and a shadow session mode (similar to what VNC does).

Example: you can launch a complete desktop session inside this nested X server right now:

The Debian way...

$ export DISPLAY=:1
$ STARTUP=mate-session /etc/X11/Xsession

The Fedora / Gentoo / openSUSE way...

### FIXME / TODO ###

however, nxagent also supports rootless (or seamless) application mode and a shadow session mode (similar to what VNC does).

💅 OPTIONS 💅

nxagent accepts a range of default X server options as described below. those default options have to be provided via the command line. periodt.

furthermore, nxagent accepts some nx-X11 specific options, described further below.

last but not least, nxagent accepts several more options, the so-called nx/nx options, provided via the $DISPLAY environment variable or the -options command line option. see below for further details. okay? okay. 💖

🔥 STANDARD XSERVER OPTIONS 🔥

  • :displaynumber — the X server runs as the given displaynumber, which by default is 0. if multiple X servers are to run simultaneously on a host, each must have a unique display number. see the DISPLAY NAMES section of the X(__miscmansuffix__) manual page to learn how to specify which display number clients should try to use. ✨
  • -a number — sets pointer acceleration (i.e. the ratio of how much is reported to how much the user actually moved the pointer).
  • -ac — disables host-based access control mechanisms. enables access by any host, and permits any host to modify the access control list.
bestie. use with extreme caution. 😭 this option exists primarily for running test suites remotely.
  • -audit level — sets the audit trail level. the default level is 1, meaning only connection rejections are reported. level 2 additionally reports all successful connections and disconnects. level 4 enables messages from the SECURITY extension, if present, including generation and revocation of authorizations and violations of the security policy. level 0 turns off the audit trail. audit lines are sent as standard error output.
  • -auth authorization-file — specifies a file which contains a collection of authorization records used to authenticate access. see also the xdm(1) and Xsecurity(__miscmansuffix__) manual pages.
  • -bs — disables backing store support on all screens.
  • -br — sets the default root window to solid black (default).
  • -wr — sets the default root window to solid white.
  • -c — turns off key-click.
  • c volume — sets key-click volume (allowable range: 0-100).
  • -cc class — sets the visual class for the root window of color screens. the class numbers are as specified in the X protocol. not obeyed by all servers.
  • -co filename — this used to be the option for specifying the path to the RGB color database file. as the RGB color database is now embedded into the binary, this option has no effect but is kept for compatibility.
deprecated 💀
  • -core — causes the server to generate a core dump on fatal errors.
  • -displayfd fd — specifies a file descriptor in the launching process. rather than specifying a display number, the X server will attempt to listen on successively higher display numbers, and upon finding a free one, will write the port number back on this file descriptor as a newline-terminated string. the -pn option is ignored when using -displayfd.

nxagent specific:

  1. other than in X.org's Xserver, you can use -displayfd in conjunction with an explicit display number. if the explicit display number is not available (i.e., already in use), nxagent tries to figure out the next available display number,

e.g.:

nxagent -displayfd 2 :50
  1. if -displayfd <X> is given with <X> equaling 2 (STDERR), then the display number string written to STDERR is beautified with some human-readable (machine-parseable) text. cute AND useful 🎀
  • -sync — this option tells nxagent to synchronize its window and graphics operations with the real server. this is a useful option for debugging, but it will slow down nxagent's performance considerably. it should not be used unless absolutely necessary.
ngl it's giving "i'll be here a while" 😭
  • -full — this option tells nxagent to utilize full regeneration of real server objects and reopen a new connection to the real server each time nxagent regenerates. the sample server implementation regenerates all objects in the server when the last client of this server terminates. when this happens, nxagent by default maintains the same top-level window and the same real server connection in each new generation. if the user selects full regeneration, even the top-level window and the connection to the real server will be regenerated for each server generation.
  • -class string — this option specifies the default visual class of the nested server. it is similar to the -cc option from the set of standard options except that it will accept a string rather than a number for the visual class specification. the string must be one of the following six values: StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor. if both the -class and -cc options are specified, the last instance of either option takes precedence. the class of the default visual of the nested server need not be the same as the class of the default visual of the real server, but it must be supported by the real server. use xdpyinfo(__appmansuffix__) to obtain a list of supported visual classes on the real server before starting nxagent. if the user chooses a static class, all the colors in the default color map will be preallocated. if the user chooses a dynamic class, colors in the default color map will be available to individual clients for allocation.
  • -deferglyphs whichfonts — specifies the types of fonts for which the server should attempt to use deferred glyph loading. whichfonts can be all (all fonts), none (no fonts), or 16 (16 bit fonts only).
  • -depth int — this option specifies the default visual depth of the nested server. the depth of the default visual of the nested server need not be the same as the depth of the default visual of the real server, but it must be supported by the real server. use xdpyinfo(__appmansuffix__) to obtain a list of supported visual depths on the real server before starting nxagent.
  • -geometry WxH+X+Y — this option specifies the geometry parameters for the top-level nxagent window. see "GEOMETRY SPECIFICATIONS" in X(__miscmansuffix__) for a discusson of this option's syntax. this window corresponds to the root window of the nested server. the width W and height H specified with this option will be the maximum width and height of each top-level nxagent window. nxagent will allow the user to make any top-level window smaller, but it will not actually change the size of the nested server root window. if this option is not specified, nxagent will choose W and H to be 3/4ths the dimensions of the root window of the real server. for further values accepted see the documentation of geometry=<string> below.
  • -dpi resolution — sets the resolution for all screens, in dots per inch. if this option is not specified nxagent will assume 96. there's also -autodpi which will clone the real server's dpi.
heads up bestie: the resolution specified via -dpi is a per session setting. it cannot be changed on reconnect! this means that clients may look "wrong" when reconnecting a session that had been started with a different dpi than the current real xserver. 🙈
  • dpms — enables DPMS (display power management services), where supported. the default state is platform and configuration specific.
  • -dpms — disables DPMS (display power management services). the default state is platform and configuration specific.
  • -f volume — sets feep (bell) volume (allowable range: 0-100).
  • -fc cursorFont — sets default cursor font.
  • -fn font — sets the default font.
  • -fp fontPath — sets where the server goes hunting for fonts. It's a comma separated list of directories, and the X server scours them for font databases. The full tea and the default list live in the FONTS section of this page. 🎀
  • -help — prints a usage message. that's it, that's the whole job 💅
  • -I — makes every remaining command line argument get ignored. just like, gone. 👑
  • -maxbigreqsize size — sets the maximum big request to size MB.
  • -name string — names the top-level nxagent window string. default is the program name.
  • -nolisten trans-type — disables a transport type. like, TCP/IP connections get shut down with -nolisten tcp. you can throw this one multiple times to disable different transport types, no cap.
  • -noreset — stops a server reset from happening when the last client connection closes. this one overrides an earlier -terminate command line option.
  • -p minutes — sets the screen-saver pattern cycle time, in minutes.
  • -pn — lets the server keep running even if it can't establish all of its well-known sockets (those are the connection points for clients) — as long as it gets at least one. this one is set by default ✨
  • -nopn — makes the server exit if it fails to establish all of its well-known sockets (connection points for clients). so, the opposite vibe.
  • -r — turns off auto-repeat.
  • r — turns on auto-repeat. (no dash bestie, it's literally just r 😭)
  • -s minutes — sets the screen-saver timeout time, in minutes.
  • -su — disables save under support on all screens.
  • -t number — sets the pointer acceleration threshold in pixels, i.e. after how many pixels the pointer acceleration should kick in.
  • -terminate — makes the server terminate at server reset instead of just continuing to run. overrides an earlier -noreset command line option.
  • -to seconds — sets the default connection timeout in seconds.
  • -tst — disables all testing extensions.
  • v — sets video-off screen-saver preference.
  • -v — sets video-on screen-saver preference.
  • -wm — forces the default backing-store of all windows to be WhenMapped. it's basically a backdoor way of getting backing-store to apply to all windows. so even though all mapped windows will have backing store, the backing store attribute value reported by the server for a window will be the last value established by a client. if it has never been set by a client, the server reports the default value, NotUseful. this behavior is required by the X protocol, which lets the server exceed the client's backing store expectations but doesn't give it a way to tell the client that it's doing so. 😌
  • [+-]xinerama — enables (+) or disables (-) XINERAMA provided via the PanoramiX extension. this is set to off by default.
  • [+-]rrxinerama — enables (+) or disables (-) XINERAMA provided via the RandR extension. by default this feature is enabled. to disable XINERAMA completely, make sure you use both options (-xinerama and -rrxinerama) on the command line. both. don't skip one. 🫶

🌈 SERVER DEPENDENT OPTIONS 🌈

nxagent also accepts these non-standard options, bestie:

  • -logo — turns on the X Window System logo display in the screen-saver. there is currently no way to change this from a client.
  • nologo — turns off the X Window System logo display in the screen-saver. again, there is currently no way to change this from a client.
  • -render default|mono|gray|color — sets the color allocation policy that the render extension will use:
    • default — selects the default policy defined for the display depth of the X server.
    • mono — don't use any color cell.
    • gray — use a gray map of 13 color cells for the X render extension.
    • color — use a color cube of at most 4*4*4 colors (that is 64 color cells).
  • -dumbSched — disables smart scheduling on platforms that support the smart scheduler.
  • -schedInterval interval — sets the smart scheduler's scheduling interval to interval milliseconds.

💖 NXAGENT SPECIFIC OPTIONS 💖

the nx-X11 system adds these command line arguments, and honestly? iconic. 👑

  • -forcenx — force use of NX protocol messages, assuming communication through nxproxy.
  • -id string — the session id.
  • -autograb — enable autograb mode on nxagent startup. the autograb feature can be toggled via nxagent keystrokes.
  • -textclipboard — force text-only clipboard nxagent startup. see option file option textclipboard=<bool> for an explanation.
  • -nxrealwindowprop — set property NX_REAL_WINDOW for each X11 client inside nxagent, providing the window XID of the corresponding window object on the X server that nxagent runs on.
  • -reportwids — explicitly tells nxagent to report its externally exposed X11 window IDs to the session log (in machine readable form), so that external parsers can obtain that information from there.
  • -reportprivatewids — explicitly tells nxagent to report X11 window IDs of internally created window objects to the session log (in machine readable form), so external parsers can obtain that information from there. heads up tho: this creates a lot of output and may affect performance. 💀
  • -timeout int — auto-disconnect timeout in seconds (minimum allowed: 60). default is 0 (no timeout).
  • -norootlessexit — don't exit if there are no clients in rootless mode.
  • -autodpi — detect the real server's DPI and set it in the agent session; the -dpi cmdline option overrides -autodpi. note that using -autodpi will also adapt the DPI on reconnect, which will cause newly started clients to respect the new DPI while clients that had been started before the reconnect still use the old DPI. this may lead to applications looking "weird". 🙈
  • -nomagicpixel — disable magic pixel support at session startup; can be re-enabled via nx/nx option on session resumption.
  • -norender — disable the use of the render extension.
  • -nocomposite/-composite — disable/enable the use of the composite extension (default is disabled).
  • -nopersistent — disable disconnection/reconnection to the X display on SIGHUP. non-persistent sessions will terminate on SIGHUP.
  • -noshmem — disable use of shared memory extension.
  • -shmem — enable use of shared memory extension (default).
  • -noshpix — disable use of shared pixmaps.
  • -shpix — enable use of shared pixmaps (default).
  • -noignore — don't ignore pointer and keyboard configuration changes mandated by clients. so as a result, configuration commands like disabling the keyboard bell (xset -b) will also affect the real X server. 😮
  • -nokbreset — don't reset the keyboard device if the session is resumed.
  • -noxkblock — this is only relevant if you also specify -keyboard=query. in that case nxagent will lock the keyboard settings and clients will get an error when trying to change keyboard settings via XKEYBOARD. with -noxkblock the lock is not applied and clients are allowed to change the keyboard settings through XKEYBOARD.
  • -tile WxH — maximum size of the tile used when sending an image to the remote display (minimum allowed: 32x32). the default depends on the link type: 64x64 for modem and isdn, 4096x4096 for all other link types.
  • -irlimit — maximum image data rate to the encoder input in kB/s. the default is no limit.
  • -D — enable desktop mode (default).
  • -R — enable rootless mode.
  • -S — enable shadow mode.
  • -B — enable proxy binding mode.
  • -keystrokefile — define path to a keyboard shortcut definitions file. default is ~/.nx/keystrokes.cfg and /etc/nxagent/keystroke.cfg (first existing file is taken). if nxagent is run as x2goagent the defaults are ~/.x2go/keystrokes.cfg and /etc/x2go/keystrokes.cfg. any keystrokes nxagent knows about that are not defined in this file are ignored. (only) if no file is found, built-in defaults are used. the keystroke file can be re-read by a keystroke (ctrl-alt-k by default). see README.keystrokes and README.keystrokes.debug for all keystrokes nxagent knows. at startup the active keystrokes are printed to the session output.
  • -version — show version information and exit.
  • -options filepath|string — path to an options file containing nx/nx options (see below). instead of a path, the options can be specified directly on the commandline by prefixing the options strings with nx/nx, which is mostly useful for testing/debugging.

okay so besides the command line options, nxagent can also be configured at session startup and at runtime (i.e. when resuming a suspended session) by these so-called nx/nx options. the options file is read on startup. it can be modified during runtime (but it must stay at the same path). on re-connect the modified file is then read and the changed options are applied. ✨

as nx/nx options, all options supported by nxcomp (see the nxproxy man page) and all nxagent nx/nx options (see below) can be used. when launching an nxcomp based nxagent session (i.e. proxy <-> agent), you will normally set the $DISPLAY variable like this:

$ export DISPLAY=nx/nx,listen=<proxy-port>,options=<options.file>:<nx-display-port>
$ nxagent <command-line-options> :<nx-display-port>

the value for <nx-display-port> is some value of a not-yet-used X11 display (e.g. :50). 🦋

using an options file is recommended, but you can also put available nx/nx options (see below) into the DISPLAY variable directly. note that the $DISPLAY variable field is of limited length.

as <proxy-port> you can pick an arbitrary (unused) TCP port or Unix socket file path. this is the port/socket that you have to connect to with the nxproxy application.

the right hand side of an option (the part following the = character) can include URL encoded characters. it is required to URL encode at least , (as %2D) and = (as %3D) to avoid wrong parsing of the options string. 🌸

available nxagent options (as an addition to nx/nx options supported by nxcomp already):

  • options=<string> — read your options from a file, bestie</p> 🎀 this text file can hold one loooong line stuffed with comma-separated nx/nx options. Set it and forget it.
  • rootless=<bool> — kicks off nxagent in rootless mode, matches the -R you'd pass on the command line. It's a no-op when resuming (default: 0, disabled) 🙈
  • geometry=<string> — the desktop geometry for starting or resuming a session. no-op in rootless mode (default: 66% of the underlying X server geometry). You can either drop a standard X geometry string (WxH+X+Y) or say allscreens for a window that covers every available screen, or onescreen for a window covering just one screen. And for historical reasons fullscreen is also accepted as a synonym for allscreens. 💅
  • fullscreen=<int> — start or resume in fullscreen mode (default: 0, off). Say 1 for a fullscreen window covering all available screens, or 2 for a fullscreen window covering only the first screen. 🌈
  • resize=<bool> — sets resizing support (default: 1, enabled) ✨
  • keyboard=<string> or kbtype=<string> — the keyboard config, and it takes one of these forms:
query|clone|<model>/<layout>|rmlvo/<rules>#<model>#<layout>#<variant>#<options>
  • query — use the default XKB keyboard layout (see below) and only let clients query the settings while blocking any changes. This one is especially helpful for setups where you need to set/modify the actual keyboard layout using core X protocol functions (e.g. via xmodmap). It's used for MacOS X clients to handle some keyboard problems that are special for that platform. > Heads up though: in this case XKEYBOARD will always report the default layout, which will most likely not match the settings you're actually experiencing. 💀
  • clone — ask the real X server for its keyboard settings using XKEYBOARD protocol functions and clone them. This is the recommended setting. For compatibility reasons it is not the default. 😭
  • <model>/<layout> — use the given model and layout. A value of null/null is equivalent to clone. You can't modify keyboard rules, variant or options this way — instead preset values are used: these are base for rules and empty strings for variant and options.
  • rmlvo/<rules>#<model>#<layout>#<variant>#<options> — configure the keyboard according to the rmlvo (Rules+Model+Layout+Variant+Options) description given after the / and separated by #. This can be used to fully pass the keyboard configuration of nxagent right after the start. Example: rmlvo/base#pc105#de,us#nodeadkeys#lv3:rwin_switch 🦋

If keyboard is omitted, the internal defaults of nxagent will be used (rules: base, layout: us, model: pc102, empty variant and options).

  • keyconv=<string> — set keycode conversion mode. Options are:
auto|on|off

By default (auto) nxagent will activate keycode conversion if it detects an evdev XKEYBOARD setup on the nxproxy side (the standard on Linux systems nowadays). Keycode conversion means certain keycodes are mapped to make the keyboard appear as a pc105 model. Using off suppresses this conversion, and with on it gets forced. ✨

  • clipboard=<string> — pick your clipboard vibe:
both|client|server|none
  • both — allow clipboard data exchange both from nxagent to the real X server and vice-versa. This is the default.
  • client — limit clipboard data exchange to work only one direction: from the real X server to nxagent. Clipboard will still work inside nxagent. This setting effectively prevents data leakage from the nxagent session to the outside. 🔒
  • server — limit clipboard data exchange to work only one direction: from nxagent to the real X server.
  • none — disable any clipboard data exchange entirely. Clipboard will still work inside the nxagent and on the real X server, but no data exchange will be possible. 💀
  • textclipboard=<bool> — enable (set to 1) or disable (set to 0) text-only clipboard. Text-only clipboard is the old (<= 3.5.99.26) clipboard behaviour where you could only copy and paste text strings (no graphics, no rich text, ...). Using this mode has been seen as a security feature since it effectively prevents transferring dangerous binary data, e.g. manipulated graphics by accident. On the other hand it's also less comfortable. (default: disabled) 🍓
  • streaming=<bool> — enable (set to 1) or disable (set to 0) streaming support for images. Not fully implemented yet and thus non-functional. (default: disabled) 🙈
  • backingstore=<bool> — disable (set to 0) or enforce (set to 1) backing store support (default: enforced). > In rootless mode backingstore is always disabled.
  • composite=<bool> — enable (set to 1) or disable (set to 0) Composite support in nxagent (default: enabled) 💖
  • xinerama=<bool> — enable (set to 1) or disable (set to 0) XINERAMA support in nxagent (default: enabled)
  • shmem=<bool> — enable/disable using shared memory. Accepted values: 1 (enable, default), 0 (disable)
  • shpix=<bool> — enable/disable shared pixmaps support. Accepted values: 1 (enable, default), 0 (disable)
  • client=<string> — type of connecting operating system (supported: linux, windows, solaris and macosx)
  • clients=<string> — filename where to log output of the nxagent's clients. This is ignored if no session id has been provided — in that case it points to stderr. Default: <sessiondir>/clients.
  • shadow=<string> — define the display that should be shadowed 👀
  • shadowuid=<int> — unique identifier for the shadow session
  • shadowmode=<bool> — full access (set to 1) or viewing-only (set to 0, default)
  • state=<string> — filename where to store the state of the nxagent (for easier interoperation with software like x2go). Default: sessiondir/state.
  • defer=<int> — defer image updates (enabled for all connection types except LAN), accepts values 0, 1 and 2.

The default value can be set via the command line (-defer). The value provided as an nx/nx option is set when resuming a session, so it overrides the command line default. 🔁

The default depends on the link type (see man nxproxy).

Each defer level adds the following rules to the previous ones:

  • 0 — Eager encoding. Default for link speed lan and local.
  • 1 — No data is put or copied on pixmaps, marking them always as corrupted and synchronizing them on demand, i.e. when a copy area to a window is requested, the source is synchronized before copying it. Default for link speed wan.
  • 2 — The put images over the windows are skipped, marking the destination as corrupted. The same happens for copy area and composite operations, spreading the corrupted regions of involved drawables. Default for link speed adsl, isdn and modem.
  • tile=<string> — set the maximum tile size in pixels (<W>x<H>) for bitmap data sent over the wire.

The default value can be set via the command line (-tile). The value provided as an nx/nx option is set when resuming a session, so it overrides the command line default. 🎀

  • menu=<bool> — support pulldown menu in nxagent session (only available on proxy <-> agent remote sessions) (default: 1, enabled)
  • magicpixel=<bool> — enable/disable magic pixel support in fullscreen mode (default: 1, enabled) ✨
  • copysize=<int> — maximum number of bytes that can be pasted from an NX session into an external application. Default is unlimited.
  • autodpi=<bool> — enable/disable deriving session DPI automatically from the real server (default: 0, disabled); only takes effect on session startups, and gets ignored when reconnecting to a suspended session.
  • sleep=<int> — delay X server operations when suspended (provided in milliseconds). Set to 0 to keep the nxagent session fully functional when suspended (e.g. useful when mirroring an nxagent session via VNC). Graphic intensive applications will be affected by this more than others. The default is 50ms. 😴
  • tolerancechecks=<string> — the pixmap format vibe check:
strict|safe|risky|bypass
  • strict — means the number of internal and external pixmap formats must match exactly, and every internal pixmap format must be available in the external pixmap format array. This is the default.
  • safe — means the number of pixmap formats might diverge, but all internal pixmap formats must also be included in the external pixmap formats array. This is recommended, because it allows clients with more pixmap formats to still connect, but not lose functionality.
  • risky — means the internal pixmap formats array is allowed to be smaller than the external pixmap formats array, but at least one pixmap format must be included in both. This is potentially unsafe. 💀
  • bypass — means all of these checks are essentially deactivated. This is a very bad idea. 🙈
  • autograb=<bool> — enable or disable autograb (default: 0, disabled). Can be toggled during a session via keystroke. 💅

If you want to use nxagent as a replacement for Xnest or Xephyr, you can pass options like this:

$ echo nx/nx,fullscreen=1$DISPLAY >/tmp/opt
$ nxagent <command-line-options> -options /tmp/opt :<nx-display-port>

🌸 XDMCP OPTIONS 🌸

okay so bestie, if your X server supports XDMCP, these are the options you get. and if you're like "what even is XDMCP", it's the X Display Manager Control Protocol — go read the spec if you want the full lore, this is just the ✨vibes✨ version. 💅

  • -query hostname — turns XDMCP ON and yeets Query packets over to the hostname you picked. 💌
  • -broadcast — XDMCP ON, and it broadcasts BroadcastQuery packets out to the whole network. whoever answers first wins the session, no takebacks. 🎀
  • -multicast [address [hop count]] — XDMCP ON, and it multicasts BroadcastQuery packets out into the network. first display manager to respond gets chosen for the session, periodt.
    • if you give it an address, the multicast goes to that address.
    • if you don't give it an address, the multicast goes to the default XDMCP IPv6 multicast group.
    • if you give it a hop count, that's used as the maximum hop count for the multicast.
    • and if you don't give a hop count? it's capped at a maximum of 1 hop, specifically so the multicast can't get routed beyond your local network. keeping it local, iykyk. 🏠
  • -indirect hostname — XDMCP ON, and it sends IndirectQuery packets to the hostname you named.
  • -port port-number — uses the port-number you specify for XDMCP packets instead of the default one.
⚠️ ngl this one has a RULE: you must put it before any -query, -broadcast, -multicast, or -indirect options. order matters, bestie, don't test it.
  • -from local-address — tells it which local address to connect from. lowkey a lifesaver if the connecting host has multiple network interfaces and you need to pick one. the local-address can be written in any form that your host platform's gethostbyname(3) implementation will accept. 🫶
  • -once — makes the server terminate (not reset, terminate) when the XDMCP session ends. dramatic exit, slay. 💀
  • -class display-class — XDMCP has this extra display qualifier that it uses during resource lookup for display-specific options. this option sets that value. the default is "MIT-Unspecified" — and the manpage itself says that's "(not a very useful value)" so like. do with that what you will. 🙈
  • -cookie xdm-auth-bits — when you're testing XDM-AUTHENTICATION-1, there's a private key shared between the server and the manager, and this option sets the value of that private data. (and yes, it's "not that it is very private, being on the command line!" — the original said it, not me 😭)
  • -displayID display-id — yet another XDMCP-specific value. this one lets the display manager identify each display so it can locate the shared key. 🔑

🧚 XKEYBOARD OPTIONS 🧚

so X servers that support the XKEYBOARD extension (aka "XKB", the cooler nickname) accept all of these. 💖

🚨 important one: all layout files you specify on the command line have to live in the XKB base directory or a subdirectory of it, and you have to specify them as the relative path from the XKB base directory. the default XKB base directory is /usr/share/X11/xkb.
  • [+-]kb — + enables, - disables the XKEYBOARD extension. that simple, no cap. ✨
  • [+-]accessx [ timeout [ timeout_mask [ feedback [ options_mask ] ] ] ] — + enables, - disables AccessX key sequences. look at all those optional nested args, it's giving very customizable. 🌈
  • -xkbdir directory — sets the base directory for keyboard layout files.
⚠️ heads up: this option is NOT available for setuid X servers — meaning when the X server's real and effective uids are different. no can do, bestie. 🙅
  • -ardelay milliseconds — sets the autorepeat delay. that's the length of time, in milliseconds, that a key has to be held down before autorepeat even kicks in. ⏱️
  • -arinterval milliseconds — sets the autorepeat interval: the length of time, in milliseconds, that should pass between each autorepeat-generated keystroke. 🎹
  • -xkbmap filename — loads the keyboard description in filename when the server starts up. main character entrance energy. 👑

🔒 SECURITY EXTENSION OPTIONS 🔒

okay so if your X server supports the SECURITY extension, it accepts one more option, and bestie, it's kind of a big deal:

  • -sp filename — makes the server attempt to read and interpret filename as a security policy file, using the format described below. The file gets read at server startup, and then reread at each server reset. 💅

🎀 the security policy file syntax 🎀

Notation first, because the grammar below is giving very much formal-language energy: * means zero or more occurrences of the preceding element, and + means one or more occurrences. And when you see <foo/bar>, just ignore the text after the / — it's only there to tell apart different instances of <foo> in the next section. iykyk 🦋

<policy file> ::= <version line> <other line>*

<version line> ::= <string/v> '\n'

<other line > ::= <comment> | <access rule> | <site policy> | <blank line>

<comment> ::= # <not newline>* '\n'

<blank line> ::= <space> '\n'

<site policy> ::= sitepolicy <string/sp> '\n'

<access rule> ::= property <property/ar> <window> <perms> '\n'

<property> ::= <string>

<window> ::= any | root | <required property>

<required property> ::= <property/rp> | <property with value>

<property with value> ::= <property/rpv> = <string/rv>

<perms> ::= [ <operation> | <action> | <space> ]*

<operation> ::= r | w | d

<action> ::= a | i | e

<string> ::= <dbl quoted string> | <single quoted string> | <unquoted string>

<dbl quoted string> ::= <space> " <not dqoute>* " <space>

<single quoted string> ::= <space> ' <not squote>* ' <space>

<unquoted string> ::= <space> <not space>+ <space>

<space> ::= [ ' ' | '\t' ]*

Character sets, because of course there are character sets:

<not newline> ::= any character except '\n'
<not dqoute>  ::= any character except "
<not squote>  ::= any character except '
<not space>   ::= any character except those in <space>

💖 the semantics, aka what it all actually MEANS 💖

  • <version line> — the very first line in the file, and it specifies the file format version. If the server doesn't recognize the version <string/v>, it ignores the rest of the file 😭 (so get this one right, fr fr). The version string for the file format described right here is "version-1".
  • Once you're past the <version line>, any lines that don't match the syntax above are just ignored. no drama.
  • <comment> lines are ignored. 💀
  • <sitepolicy> lines are currently ignored. They're intended to specify the site policies used by the XC-QUERY-SECURITY-1 authorization method.
  • <access rule> lines specify how the server should react to untrusted client requests that affect the X Window property named <property/ar>. The rest of this section describes how an <access rule> gets interpreted. 👑

So for an <access rule> to apply to a given instance of <property/ar>, <property/ar> has to be on a window that's in the set of windows specified by <window>. If <window> is any, the rule applies to <property/ar> on any window. If <window> is root, the rule applies to <property/ar> only on root windows.

If <window> is <required property>, here's how it goes down:

  • If <required property> is a <property/rp>, the rule applies when the window also has that <property/rp>, regardless of its value. ✨
  • If <required property> is a <property with value>, then <property/rpv> must also have the value specified by <string/rv>. In this case the property must have type STRING and format 8, and should contain one or more null-terminated strings. If any of the strings match <string/rv>, the rule applies.

The definition of string matching is a simple case-sensitive string comparison, with one elaboration: the occurrence of the character '*' in <string/rv> is a wildcard meaning "any string." A <string/rv> can contain multiple wildcards anywhere in the string. For example, "x*" matches strings that begin with x, "*x" matches strings that end with x, "*x*" matches strings containing x, and "x*y*" matches strings that start with x and subsequently contain y. slay 🌸

There may be multiple <access rule> lines for a given <property/ar>. The rules are tested in the order that they appear in the file, and the first rule that applies is the one that's used. no takebacks.

<perms> specify the operations that untrusted clients may attempt, plus the actions the server should take in response to those operations.

<operation> can be r (read), w (write), or d (delete). The following table shows how X Protocol property requests map to these operations in The Open Group server implementation:

GetProperty    r, or r and d if delete = True
ChangeProperty w
RotateProperties    r and w
DeleteProperty d
ListProperties none, untrusted clients can always list all properties

<action> can be a (allow), i (ignore), or e (error).

  • a (allow) means execute the request as if it had been issued by a trusted client. main character energy honestly.
  • i (ignore) means treat the request as a no-op. In the case of GetProperty, ignore means return an empty property value if the property exists, regardless of its actual value. 🫥
  • e (error) means do not execute the request and return a BadAtom error with the atom set to the property name.
Error is the default action for all properties, including those not listed in the security policy file. 👀

An <action> applies to all <operation>s that follow it, until the next <action> is encountered. So like, irwad means ignore read and write, allow delete. periodt.

GetProperty and RotateProperties may do multiple operations (r and d, or r and w). If different actions apply to the operations, the most severe action is applied to the whole request — there is no partial request execution, bestie. The severity ordering is: allow < ignore < error. So if the <perms> for a property are ired (ignore read, error delete), and an untrusted client attempts GetProperty on that property with delete = True, an error is returned, but the property value is not. Similarly, if any of the properties in a RotateProperties don't allow both read and write, an error is returned without changing any property values. 😭

🍓 example security policy file 🍓

Here it is, the moment you've all been waiting for:

version-1

# Allow reading of application resources, but not writing.
property RESOURCE_MANAGER     root      ar iw
property SCREEN_RESOURCES     root      ar iw

# Ignore attempts to use cut buffers.  Giving errors causes apps to crash,
# and allowing access may give away too much information.
property CUT_BUFFER0          root      irw
property CUT_BUFFER1          root      irw
property CUT_BUFFER2          root      irw
property CUT_BUFFER3          root      irw
property CUT_BUFFER4          root      irw
property CUT_BUFFER5          root      irw
property CUT_BUFFER6          root      irw
property CUT_BUFFER7          root      irw

# If you are using Motif, you probably want these.
property _MOTIF_DEFAULT_BINDINGS        rootar iw
property _MOTIF_DRAG_WINDOW   root      ar iw
property _MOTIF_DRAG_TARGETS  any       ar iw
property _MOTIF_DRAG_ATOMS    any       ar iw
property _MOTIF_DRAG_ATOM_PAIRS         anyar iw

# The next two rules let xwininfo -tree work when untrusted.
property WM_NAME              any       ar

# Allow read of WM_CLASS, but only for windows with WM_NAME.
# This might be more restrictive than necessary, but demonstrates
# the <required property> facility, and is also an attempt to
# say "top level windows only."
property WM_CLASS             WM_NAME   ar

# These next three let xlsclients work untrusted.  Think carefully
# before including these; giving away the client machine name and command
# may be exposing too much.
property WM_STATE             WM_NAME   ar
property WM_CLIENT_MACHINE    WM_NAME   ar
property WM_COMMAND           WM_NAME   ar

# To let untrusted clients use the standard colormaps created by
# xstdcmap, include these lines.
property RGB_DEFAULT_MAP      root      ar
property RGB_BEST_MAP         root      ar
property RGB_RED_MAP          root      ar
property RGB_GREEN_MAP        root      ar
property RGB_BLUE_MAP         root      ar
property RGB_GRAY_MAP         root      ar

# To let untrusted clients use the color management database created
# by xcmsdb, include these lines.
property XDCCC_LINEAR_RGB_CORRECTION    rootar
property XDCCC_LINEAR_RGB_MATRICES      rootar
property XDCCC_GRAY_SCREENWHITEPOINT    rootar
property XDCCC_GRAY_CORRECTION          rootar

# To let untrusted clients use the overlay visuals that many vendors
# support, include this line.
property SERVER_OVERLAY_VISUALS         rootar

# Dumb examples to show other capabilities.

# oddball property names and explicit specification of error conditions
property "property with spaces"         'property with "'aw er ed

# Allow deletion of Woo-Hoo if window also has property OhBoy with value
# ending in "son".  Reads and writes will cause an error.
property Woo-Hoo              OhBoy = "*son"ad

🌐 NETWORK CONNECTIONS 🌐

The X server supports client connections via a platform-dependent subset of the following transport types: TCPIP, Unix Domain sockets, and several varieties of SVR4 local connections. To learn how to specify which transport type clients should try to use, go peek at the DISPLAY NAMES section of the X(__miscmansuffix__) manual page. 🦋✨

🔐 GRANTING ACCESS 🔐

okay so bestie, listen — the X server ships with a platform-dependent subset of these authorization protocols, and that's the whole guest list:

  • MIT-MAGIC-COOKIE-1
  • XDM-AUTHORIZATION-1
  • XDM-AUTHORIZATION-2
  • SUN-DES-1
  • MIT-KERBEROS-5

how any of these actually work? that's not this page's business, go read Xsecurity(__miscmansuffix__) for the deets 💅

so the auth data these protocols need gets handed to the server in a private file, and you point at it with the -auth command line option. every time the server is about to accept its first connection after a reset (or like, when it's booting up), it reads that file. and here's the plot twist 👀 — if the file has any authorization records in it, then the local host is not automatically allowed in anymore. nope. only clients that send one of the authorization records from that file in their connection setup info get through. gatekeeping, but make it secure 🚪✨

  • wanna know the binary format of that file? Xau manual page, go off.
  • wanna maintain it and distribute its contents to remote hosts? xauth(1), that's your girl.

🏠 host-based access control, the other flavor

the X server also keeps a host-based access control list for deciding whether to accept connections from clients on a particular machine. and if no other authorization mechanism is in play, this list starts out with:

  1. the host the server is running on, and
  2. any machines listed in the file /etc/Xn.hosts

…where n is the display number of the server. yes, that n is a placeholder, don't @ me 😭

each line of that file should have either:

  • an Internet hostname (e.g. expo.lcs.mit.edu), or
  • a complete name in the format family:name, as described in the xhost(1) manual page
⚠️ and like, no leading or trailing spaces on any lines. none. zero. the vibes must be immaculate.

for example:

joesworkstation
corporate.company.com
star::
inet:bigcpu
local:

users can add or remove hosts from this list and enable or disable access control using the xhost command, from the same machine as the server. simple as 🫶

🔥 the xfwp situation (iykyk)

if the X FireWall Proxy (xfwp) is being used without a sitepolicy, then host-based authorization must be turned on for clients to be able to connect to the X server via the xfwp. let me say that again for the people in the back 📢

if xfwp is run without a configuration file and thus no sitepolicy is defined, and if xfwp is using an X server where xhost + has been run to turn off host-based authorization checks — then when a client tries to connect to this X server via xfwp, the X server will deny the connection. awkward 💀

see xfwp(1) for more info about this proxy.

😬 real talk about X protocol permissions

the X protocol intrinsically does not have any notion of window operation permissions, and it places no restrictions on what a client can do. like… if a program can connect to a display, it has full run of the screen. that's it. that's the whole security model. 😭

X servers that support the SECURITY extension fare better, because clients can be designated untrusted via the authorization they use to connect — see the xauth(1) manual page for details. restrictions get imposed on untrusted clients that curtail the mischief they can do. see the SECURITY extension specification for a complete list of these restrictions. 💅

and for sites that have better authentication and authorization systems? they might wish to make use of the hooks in the libraries and the server to provide additional security models. build ur own, bestie 🎀

🚨 SIGNALS 🚨

the X server attaches special meaning to the following signals:

  • SIGHUP — this signal makes the server close all existing connections, free all resources, and restore all defaults. it's sent by the display manager whenever the main user's main application (usually an xterm or a window manager) exits, to force the server to clean up and prepare for the next user. spring cleaning era 🧹✨
  • SIGTERM — this signal makes the server exit cleanly. no drama, just closure 🦋
  • SIGUSR1 — okay this one is used quite differently from either of the above. when the server starts, it checks to see if it has inherited SIGUSR1 as SIG_IGN instead of the usual SIG_DFL. if that's the case, the server sends a SIGUSR1 to its parent process after it has set up the various connection schemes. Xdm uses this feature to recognize when connecting to the server is possible. it's giving ✨telepathy✨

🔤 FONTS 🔤

the X server can obtain fonts from directories and/or from font servers. the list of directories and font servers the X server uses when trying to open a font is controlled by the font path.

the default font path is __default_font_path__ .

the font path can be set with the -fp option, or by xset(1) after the server has started. your call, bestie 💅

📁 FILES 📁

  • /etc/Xn.hosts — Initial access control list for display number n
  • /usr/share/fonts/X11/misc, /usr/share/fonts/X11/75dpi, /usr/share/fonts/X11/100dpi — Bitmap font directories
  • /usr/share/fonts/X11/Type1 — Outline font directories
  • /usr/share/nx/rgb — Color database
  • /tmp/.X11-unix/Xn — Unix domain socket for display number n
  • /tmp/rcXn — Kerberos 5 replay cache for display number n

👀 SEE ALSO 👀

Protocols: X Window System Protocol, NX Compression Protocol, The X Font Service Protocol, X Display Manager Control Protocol

Fonts: bdftopcf(1), mkfontdir(1), mkfontscale(1), xfs(1), xlsfonts(1), xfontsel(1), xfd(1), X Logical Font Description Conventions

Security: Xsecurity(__miscmansuffix__), xauth(1), Xau(1), xdm(1), xhost(1), xfwp(1), Security Extension Specification

Starting the server: xdm(1), xinit(1)

Controlling the server once started: xset(1), xsetroot(1), xhost(1)

Server-specific man pages: Xdec(1), XmacII(1), Xsun(1), Xnest(1), Xvfb(1), XFree86(1), XDarwin(1).

Server internal documentation: Definition of the Porting Layer for the X v11 Sample Server

👑 AUTHORS 👑

the first sample X server was originally written by Susan Angebranndt, Raymond Drewry, Philip Karlton, and Todd Newman, from Digital Equipment Corporation, with support from a large cast. it has since been extensively rewritten by Keith Packard and Bob Scheifler, from MIT. Dave Wiggins took over post-R5 and made substantial improvements. legends only, no cap 🫶

the first implementation of nx-X11 (version 1.x up to 3.5.x) was written by NoMachine (maintained until 2011).

the current implementation of nx-X11 is maintained by various projects, amongst others The Arctica Project, TheQVD (Qindel Group) and X2Go.

this manual page was written by Per Hansen <spamhans@yahoo.de>, and modified by Marcelo Boveto Shima <marceloshima@gmail.com> and Mike Gabriel <mike.gabriel@das-netzwerkteam.de>. in 2016, the original Xserver.man page shipped with nx-X11 was merged into the nxagent man page and received a major update by Mike Gabriel <mike.gabriel@das-netzwerkteam.de>. iconic behavior tbh 💖

and that's the whole page, bestie!! this is Version 3.5.99.27, dated Jun 2023, and it's the nxagent(1) manual page. you made it to the end, main character energy fr fr 🌈⭐💅 go touch some grass (or like, don't, run nxagent instead) 🦋✨

📦 where this page comes from