.. _user_guide/x11-server-access: 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 `_. 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. 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: * `Wikipedia: X Window System authorization `_ * `Xsecurity(7) `_ 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: .. code-block:: bash 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. 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: .. code-block:: bash 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. 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 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 :ref:`process/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: .. code-block:: lnc 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 :ref:`process/forward_x11`. If a process uses: .. code-block:: lnc 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 :ref:`ln_manager_webui/headless-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 :ref:`process/forward_x11` and :ref:`process/forward_x11_to_gui` for the process flag reference.