The xauth(1) program is used to edit and display the
authorization information used in connecting to the X server. This
program is usually to extract authorization records from one
computer and merge them in on another (as is the case when using
remote logins or to grant access to other users). Commands
(described below) can be entered interactively, on the
xauth(1) command line, or in scripts. Note that this program
does not contact the X server.
The following options may be used with xauth(1). They can
be given individually (such as -q-i) or can combined
(such as -qi):
-b
This option indicates that xauth(1) should attempt to
break any authority file locks before proceeding and should only be
used to clean up stale locks.
-fauthfile
This option specifies the name of the authority file to use. By
default, xauth(1) will use the file specified by the
XAUTHORITY environment variable or .Xauthority in the
user's home directory.
-i
This option indicates that xauth(1) should ignore any
authority file locks. Normally, xauth(1) will refuse to read
or edit any authority files that have been locked by other programs
(usually xdm(1) or another xauth(1)).
-q
This option indicates that xauth(1) should operate
quietly and not print unsolicited status messages. This is the
default if an xauth(1) command is given on the command line
or if the standard output is not directed to a terminal.
-v
This option indicates that xauth(1) should operate
verbosely and print status messages indicating the results of
various operations (such as how many records have been read in or
written out). This is the default if xauth(1) is reading
commands from its standard input and its standard output is
directed to a terminal.
The following commands can be used to manipulate authority
files:
adddisplayname protocolname hexkey
An authorization entry for the indicated display using the
given protocol and key data is added to the authorization file. The
data is specified as an even-lengthed string of hexadecimal digits,
each pair representing one octet. The first digit of each pair
gives the most significant four bits of the octet and the second
digit of the pair gives the least significant four bits. For
example, a 32-character hexkey would represent a 128-bit value. A
protocol name consisting of just a single period is treated as an
abbreviation for MIT-MAGIC-COOKIE-1.
[n]extractfilename displayname...
Authorization entries for each of the specified displays are
written to the indicated file. If the nextract command is
used, the entries are written in a numeric format suitable for
non-binary transmission (such as secure electronic mail). The
extracted entries can be read back in using the merge and
nmerge commands. If the file name consists of just a single
dash, the entries will be written to the standard output.
[n]list [displayname...]
Authorization entries for each of the specified displays (or
all if no displays are named) are printed on the standard output.
If the nlist command is used, entries will be shown in the
numeric format used by the nextract command; otherwise, they
are shown in a textual format. Key data is always displayed in the
hexadecimal format given in the description of the add
command.
[n]merge [filename...]
Authorization entries are read from the specified files and are
merged into the authorization database, superceding any matching
existing entries. If the nmerge command is used, the numeric
format given in the description of the extract command is
used. If a file name consists of just a single dash, the standard
input will be read if it has not been read before.
removedisplayname...
Authorization entries matching the specified displays are
removed from the authority file.
sourcefilename
The specified file is treated as a script containing
xauth(1) commands to execute. Blank lines and lines
beginning with a number sign (#) are ignored. A single dash can be
used to indicate the standard input if it has not already been
read.
info
Information describing the authorization file, whether or not
any changes have been made, and from where xauth(1) commands
are being read is printed on the standard output.
exit
If any modifications have been made, the authority file is
written out (if allowed), and the program exits. An end of file is
treated as an implicit exit command.
quit
The program exits, ignoring any modifications. This can also be
accomplished by pressing the interrupt character.
help [string]
A description of all commands that begin with the given string
(or all commands if no string is given) is printed on the standard
output.
?
A short list of the valid commands is printed on the standard
output.
Display names for the add, [n]extract,
[n]list, [n]merge, and remove
commands use the same format as the DISPLAY environment
variable and the common -display command-line argument.
Display-specific information (such as the screen number) is
unnecessary and will be ignored. Same-computer connections (such as
local-host sockets, shared memory, and the Internet Protocol host
name localhost) are referred to as
hostname/unix:displaynumber so that local entries for
different computers can be stored in one authority file.
The most common use for xauth(1) is to extract the entry
for the current display, copy it to another computer, and merge it
into the user's authority file on the remote computer:
This xauth(1) program uses the following environment
variables:
XAUTHORITY
To get the name of the authority file to use if the -f
option isn't used. If this variable is not set, xauth(1)
will use .Xauthority in the user's home directory.
HOME
To get the user's home directory if XAUTHORITY isn't
defined.
Users that have unsecured networks should take care to use
encrypted file transfer mechanisms to copy authorization entries
between computers. Similarly, the MIT-MAGIC-COOKIE-1 protocol is
not very useful in unsecured environments. Sites that are
interested in additional security might need to use encrypted
authorization mechanisms such as Kerberos.
Spaces are currently not allowed in the protocol name. Quoting
could be added for the truly perverse.