6.3. X11 Connections and Authentication

X11 uses a client/server model. The X server is the process that owns the display, keyboard, and mouse, while GUI applications are X clients that connect to that server and ask it to create windows. This often feels backwards at first: the program that shows a window is the client, and the machine with the screen is the server.

For a concise overview of that model, see the Wikipedia article on the X Window System and the X(7) manual page.

6.3.1. DISPLAY

The most important environment variable is DISPLAY. It tells an X client which X server to connect to.

Typical forms are:

:0 the first local display on the same machine
localhost:10.0 a local TCP endpoint, often created automatically by ssh -X / ssh -Y
somehost:0 or 192.168.1.20:0 a remote X server reached over the network

Conceptually, the value consists of:

a host part
a display number
optionally a screen number after the final . character

The official X(7) manual page documents DISPLAY and also notes that XAUTHORITY defaults to $HOME/.Xauthority when it is not set.

6.3.2. X Authentication and Cookies

Connecting to an X server is not only about reaching the right socket or TCP port. The client also needs to pass X11 authorization checks.

The most common mechanism is cookie-based authentication, especially MIT-MAGIC-COOKIE-1. In that model, the X server knows a secret cookie, and an X client must present the same cookie to be accepted. If the client has the right DISPLAY value but not the right cookie, the connection will still be rejected.

For an overview of the common X authorization mechanisms, see:

6.3.3. xauth and XAUTHORITY

The usual tool for inspecting and copying X authorization cookies is xauth. Its authority database contains the cookies that are valid for one or more displays.

The xauth(1) manual page documents the lookup order:

first use the file named by XAUTHORITY
otherwise use .Xauthority in the user’s home directory

In practice this means:

if XAUTHORITY is set, clients and tools such as xauth usually read that file
if XAUTHORITY is not set, the usual default is $HOME/.Xauthority

This file is commonly created and maintained by the display manager, desktop session startup, or by SSH X11 forwarding support. The same xauth(1) manual page also shows the classic pattern for copying the current display cookie to another machine:

xauth extract - "$DISPLAY" | ssh otherhost xauth merge -

That example illustrates the central point: remote X clients need both the right DISPLAY value and matching authorization data on the remote side.

6.3.4. xhost and Disabling Access Checks

Not every X setup uses cookie copying. Another family of mechanisms is managed via xhost.

The xhost(1) manual page documents these important forms:

xhost + disable access control completely; effectively allow everybody who can reach the server
xhost +hostname allow clients connecting from a specific host
xhost -hostname remove that permission again

xhost + is usually a bad idea on multi-user or networked systems, because it disables access control globally for that display.

More selective access can be granted per host or, on systems that support it, per local user. For example, xhost supports server-interpreted entries such as si:hostname:... and si:localuser:...; see xhost(1) and Xsecurity(7) for details.

Examples:

xhost +si:hostname:build-host
xhost +si:localuser:alice

This is the safer interpretation of “per host” and “per user”: allow only a specific host or a specific local user instead of turning access control off for everybody.

6.3.5. Where Things Usually Go Wrong

When a GUI program does not open a window on the intended display, the problem is usually one of these:

DISPLAY points to the wrong X server
the target X server is reachable, but the client does not have the right cookie in the authority database
the client has a valid cookie, but XAUTHORITY points to the wrong file
the user tried to rely on direct TCP access, but the X server is not listening for remote TCP connections
xhost-based permissions are too restrictive, or were changed on the wrong display

6.3.6. How ln_manager Helps

ln_manager knows about the most important X11 pieces needed for common cases: starting a process whose windows should appear either on the manager process’ own X display or on the display of the GUI session that requested the process start.

For new interactive tools, prefer forward_x11_to_gui unless the manager process’ own display is intentionally the target. It keeps the GUI close to the operator who clicked start: the built-in GTK user, a remote GUI connection, or the authenticated web-UI user with a private VNC-backed display.

If a process uses:

add flags: forward_x11_to_gui

then ln_manager first tries to target the GUI session that triggered the start request. This can be the built-in GTK GUI, a remote GUI connection via ln_manager --connect X:Y, or the browser web UI. If that GUI session is on the process host, ln_manager passes through that session’s DISPLAY and XAUTHORITY values. If it is on another host, ln_manager can create forwarding/tunneling and install the GUI session’s X11 cookie on the process host. If there is no separate GUI session context, this falls back to the same manager-display behavior as forward_x11.

If a process uses:

add flags: forward_x11

then ln_manager will try to:

choose a suitable DISPLAY for that process
provide the needed XAUTHORITY / cookie information
transport the cookie to remote machines when required
establish forwarding/tunneling when needed and possible

This targets the manager process’ own X display. When the manager GUI is local, that is also the visible manager GUI display. With a separate remote GUI session, it is not necessarily the user’s display. Use this flag when the manager display is the intended destination independent of who starts the process.

When the manager has no DISPLAY environment variable, a browser web-UI start of a forward_x11 process can fall back to the authenticated user’s private web X display. This keeps older configs usable with a --without-gui manager. The fallback can be disabled with the instance or process disable_forward_x11_to_gui_fallback flag. For a complete headless browser workflow, including SSH tunnels, SOCKS proxy access, noVNC, and native vncviewer -via usage, see Headless Browser Operation With X Clients.

This means that, for the common “show the window on the manager display” or “show the window on the requesting GUI user’s display” cases, users usually do not need to configure DISPLAY, XAUTHORITY, or cookie copying manually.

However, these flags are only the right tools when the target window should appear on one of those ln_manager-known displays. If the window should appear on some other X server, users need to understand the X11 basics described above and configure the environment and authentication accordingly. In that case, ln_manager can no longer infer the correct display and credentials automatically, because those depend on the external X server that the user wants to target.

See forward_x11 and forward_x11_to_gui for the process flag reference.