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 the common case: starting a process whose windows should appear on the same X display as the manager GUI.

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 means that, for the common “show the window on the same display as the manager GUI” case, users usually do not need to configure DISPLAY, XAUTHORITY, or cookie copying manually.

However, forward_x11 is only the right tool when the target window should appear on the same X display as the manager GUI.

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.