Safely copy X11 credentials with xauth

xauth lets you copy the X11 authority record for your display to another machine and merge it into the remote account, secret intact. You will inspect the authority file first, do the copy over SSH, then see how to test changes in a temporary file and undo a merge. The usual workflow takes about ten minutes if SSH already works.

Security boundary: An authority record contains a secret that can allow an X client to authenticate to a display. Do not paste the output of xauth list into chat, tickets or shell history. Use encrypted SSH transport and keep the record on hosts that should be able to access the display.

1. Check the installed xauth and its authority file

This guide uses the installed X.Org xauth 1.1.2, provided here by Debian package version 1:1.1.2-1build1. Check your executable and version first:

$ command -v xauth
/usr/bin/xauth
$ xauth -V
1.1.2

Unless you pass -f, xauth uses the file named by XAUTHORITY, or $HOME/.Xauthority when that variable is unset. Confirm which file your session selects without printing its cookie data:

$ xauth info
Authority file:       /home/you/.Xauthority
File new:             no
File locked:          no
Number of entries:    1
Changes honored:      yes
Changes made:         no

The number of entries and the exact path will differ. If the file does not exist, xauth reports that fact. Do not add sudo just to silence it: root's authority file is normally not the one used by your desktop session.

Checkpoint: identify the display

Read the current display name before extracting anything. It is commonly set by the desktop or SSH session:

$ printf '%s\n' "$DISPLAY"
:0

An empty value means there is no current X display in this shell. Stop here and run the command from the session that owns the display, or supply a known display name explicitly after checking the target setup. Do not guess a display and copy an unrelated credential.

2. Inspect one record without changing it

Use list with the display name when you need to confirm that a matching record exists. The key is shown in hexadecimal, so treat this as sensitive output:

$ xauth list "$DISPLAY"
workstation/unix:0  MIT-MAGIC-COOKIE-1  0123456789abcdef0123456789abcdef

Hostnames can be resolved when records are printed. Add -n when you need the stored host address rather than a resolved name. The output is for checking, not for routine transfer. In scripts, prefer a pipeline that sends the record directly to SSH.

3. Extract the current record and merge it remotely

Run the following as your normal user. Replace remote.example with the SSH host and leave $DISPLAY expanded on the local side:

$ xauth extract - "$DISPLAY" | ssh remote.example xauth merge -

extract - writes the selected binary authority records to standard output. The pipe sends them through the encrypted SSH connection, and merge - reads them from standard input on the remote host. A matching remote record is replaced. If the SSH account is not the account that will run the X client, stop and correct the account rather than using sudo; authority files are per-user credentials.

There may be no output on success because command-line xauth runs quietly. Check the SSH and xauth exit statuses:

$ set -o pipefail
$ xauth extract - "$DISPLAY" | ssh remote.example xauth merge -
$ printf 'pipeline status: %s\n' "$?"
pipeline status: 0

On systems whose shell does not support pipefail, check SSH separately with a temporary extract file, or use a shell that does. A zero status means the pipeline completed; it does not prove that the remote X client can reach the right display.

4. Verify the remote record without exposing it in normal logs

Ask the remote xauth to report its database details. This does not print the cookie:

$ ssh remote.example xauth info
Authority file:       /home/you/.Xauthority
File new:             no
File locked:          no
Number of entries:    1
Changes honored:      yes
Changes made:         no

For a targeted check, the remote display name must match the record you copied. Avoid adding list to a shared CI log or an issue command because it prints the secret. If an X client still cannot connect, check the remote DISPLAY, the server's network reachability and whether the display is actually accepting connections. xauth edits the authority file; it does not contact the X server for ordinary commands.

5. Test edits in an isolated authority file

Use -f when learning the command, comparing records or preparing a change. This keeps the real session file untouched:

$ workdir=$(mktemp -d)
$ xauth -f "$workdir/authority" add testhost/unix:7 . 0123456789abcdef0123456789abcdef
$ xauth -f "$workdir/authority" list
testhost/unix:7  MIT-MAGIC-COOKIE-1  0123456789abcdef0123456789abcdef

A single dot is shorthand for MIT-MAGIC-COOKIE-1. The example key is deliberately synthetic. Do not use a made-up key to troubleshoot a real display, and do not place a real key in a command that will be saved in shell history.

To make a reversible export, extract the selected record to a file with a restrictive umask:

$ umask 077
$ xauth extract "$workdir/record" testhost/unix:7
$ xauth -f "$workdir/authority" remove testhost/unix:7
$ xauth -f "$workdir/authority" merge "$workdir/record"

The last two commands demonstrate undo for that isolated database: removing the record changes the database, and merging the saved record restores it. For a real authority file, take an appropriately protected backup before removing or replacing entries. Do not use -b casually. It breaks authority-file locks and is intended only for locks known to be stale, not for bypassing another live xauth or display manager.

6. Diagnose common failures

Done means