xauth

Start interactive mode with a specific authority file (defaults to ~/.Xauthority)

$ xauth -f [path/to/file]

$ xauth info

$ xauth list

$ xauth add [display_name] [protocol_name] [key]

$ xauth remove [display_name]

$ xauth extract - $DISPLAY

$ cat [path/to/file] | xauth merge -

$ xauth --help

xauth [ options ] [ command [ args ... ] ]

-f filename
    Specifies the authorization file to use instead of the default ~/.Xauthority.

-v
    Enables verbose output, providing more details about xauth operations.

-q
    Suppresses status messages, making the output quieter.

-b
    Automatically backs up the authorization file before modifications.

-i
    Ignores any broken or stale locks on the authorization file.

-s
    Disables file locking. Use with caution as it can lead to file corruption with concurrent access.

-u
    When adding or generating entries, marks them as 'untrusted' for security reasons.

-r
    When adding an entry, removes any existing entry with the same display name first.

-w
    Waits for the authorization file lock to be released, instead of failing immediately.

add displayname protocalname hexkey
    Adds a new authorization entry for the specified display, protocol, and hex key.

remove displayname ...
    Removes one or more authorization entries for the specified display names.

extract filename displayname ...
    Extracts authorization entries for specified displays into a new file.

merge filename ...
    Merges authorization entries from one or more files into the current authorization file.

list [displayname ...]
    Lists authorization entries. If display names are provided, only lists those; otherwise, lists all.

generate displayname [protocolname]
    Generates a new authorization entry with a fresh magic cookie. Can be used with options like timeout, trusted, or untrusted.

info
    Displays information about the current authorization file, such as its path and permissions.

xauth is a utility for editing and displaying the authorization records used by X applications to connect to an X server. These records are typically stored in the user's .Xauthority file, usually located in the home directory. Each entry in this file contains essential information such as the display name, the authorization protocol (e.g., MIT-MAGIC-COOKIE-1), and a secret key or 'magic cookie'.

The primary function of xauth is to provide a secure mechanism for X clients to prove their identity and obtain permission to access a specific X display. It allows users to add, remove, list, extract, and merge authorization entries. This is particularly crucial for remote X connections, such as those facilitated by SSH X forwarding (ssh -X or ssh -Y), where ssh automatically leverages xauth to manage temporary authorization cookies. Without correct and valid authorization, X applications will be denied access to the display, resulting in connection errors.

The .Xauthority file contains sensitive authorization credentials; its permissions must be strictly managed (readable/writable only by the owner) to prevent unauthorized access to your X display. Incorrect file permissions or corrupted entries can lead to X application connection failures. Using the -s option (no locking) is generally unsafe as it can lead to data corruption if multiple processes attempt to modify the file concurrently. xauth itself does not encrypt the contents of the authorization file.

The .Xauthority file is the default location where xauth stores X authorization credentials. It's a binary file containing records, each associating a display name (e.g., 'localhost:0', 'unix:0'), an authorization protocol (e.g., MIT-MAGIC-COOKIE-1), and the actual secret key (the 'magic cookie'). This file must be kept private and secure, typically with 0600 permissions, as anyone with read access to this file could potentially connect to your X display.

Listing entries: xauth list displays all current authorization entries.

Transferring cookies: xauth extract - $DISPLAY | ssh remote_host xauth merge - securely transfers the current display's authorization cookie to a remote host, enabling X applications on the remote host to connect back to your local display.

SSH X Forwarding: When you use ssh -X or ssh -Y, SSH automatically generates a temporary authorization cookie on the remote host and uses xauth to add it to the remote user's .Xauthority file, enabling secure X forwarding.

Generating new cookies: xauth generate :1 . trusted can be used to create a new trusted authorization cookie for a specific display, which can be useful for configuring display managers or other services.

xauth is a long-standing utility within the X Window System, having been a core component since early X11 releases (e.g., X11R4). Its development has focused on providing a robust and secure method for managing authorization credentials for X clients, evolving alongside the security needs of networked X applications. It plays a critical role in the secure operation of X displays, particularly in multi-user or networked environments, by ensuring only authorized clients can connect.

X(7), xhost(1), ssh(1), mcookie(1)