.TH xauth "" "" "X Utility"
.PC "Display/edit authorization information"
\fBxauth [\-biqv \-f \fIauthfile\^\fB] [\fIcommand \fB[arguments\^\fB] ]\fR
.PP
.HS
.SH Options:
.IC \fB\-b\fR
Do not break any authority file locks before proceeding
.IC "\fB-f \fIauthfile\fR"
Use the authority file \fIauthfile\fR
.IC \fB\-i\fR
Ignore all locks on authority files
.IC \fB\-q\fR
Quiet:
Do not print unsolicited messages about authority status
.IC \fB\-v\fR
Verbose:
Print a message to indicate the outcome of each operation
.HE
The X utility
.B xauth
lets you display and edit the authorization information with which users
connect to the X server.
It is used most commonly to extract authorization records from
one machine and merge them into the records on another, such as when
using remote logins or granting authorization to other users.
Each
.I command
given below can be entered interactively, entered on
.BR xauth 's
command line, or embedded within a script.
.PP
.B xauth
recognizes the following options:
.IP \fB\-b\fR
Do not break any authority file locks before proceeding.
With this option,
.B xauth
is used only to clean up stale locks.
.IP "\fB-f \fIauthfile\fR"
Use the authority file
.IR authfile .
By default,
.B xauth
uses the authority file named by the environmental variable
.BR XAUTHORITY ,
or the file
.BR $HOME/.Xauthority .
.IP \fB\-i\fR
Ignore all locks on authority files.
Normally,
.B xauth
refuses to read or edit any authority files that have been locked by other
programs.
.IP \fB\-q\fR
Quiet:
Do not print unsolicited messages about authority status.
This is the default if a command is given on
.BR xauth 's
command line or if the standard output is not directed to a terminal.
.IP \fB\-v\fR
Verbose:
Print a message to indicate the outcome of each operation.
This is the default option if
.B xauth
is reading commands from the standard input and its standard output is
directed to a terminal.
.SH Commands
As noted above,
.B xauth
does its work by executing one or more commands.
If
.B xauth
finds no command on its command line, it reads the standard input
and executes all commands it received until it receives the command
.BR exit ,
receives the command
.BR quit ,
or receives EOF (\fB<ctrl-D>\fR under \*(CO).
.PP
.B xauth
recognizes the following commands:
.IP \fB?\fR
Print a summary of all commands.
.IP "\fBadd \fIdisplay protocol hexkey\fR"
Add an authorization entry for
.IR display .
.I protocol
gives the protocol that
.I display
uses.
The
.I protocol
of `.' is an abbreviation for the protocol
.BR MIT-MAGIC-COOKIE-1 .
.I hexkey
gives the key data, in the form of a string of pairs of hexadecimal numerals;
the first numeral gives the most significant four bits and the second the
least significant four bits.
.IP "\fBexit\fR"
Write out the modified authorization file, and exit from
.BR xauth .
EOF is equivalent to this command.
.IP "\fBextract \fIfile display \fB[ ... \fIdisplay\^\fB]\fR"
Write the authorization entries for each
.I display
into
.IR file .
The
.I file
of `-' indicates the standard output.
This command can be used with the
.BR xauth 's
command
.B merge
to copy permissions from one authorization into another.
.IP "\fBhelp [\fIstring\^\fB]\fR"
Print help information about all commands that begin with
.IR string .
If no
.I string
is given, list information about all commands.
.IP "\fBinfo\fR"
Print a summary of information about the authorization file itself.
.IP "\fBlist [\fIdisplay\^\fB [ \fI... display\^\fB] ]\fR"
Print onto the standard output the authorization information for each
.IR display .
If no
.I display
is named, print information about all displays.
Key data are printed in the hexadecimal format used by the
.B add
command, described above.
.IP "\fBmerge [\fIfile \^\fB[ \fI... file\^\fB] ]\fR"
Merge the authorization information from each
.I file
into the authorization file.
The
.I file
`-' indicates the standard input.
.IP "\fBnextract \fIfile display \fB[ ... \fIdisplay\^\fB]\fR"
Same as
.BR extract ,
described above, except that the authorization information is written
in a numeric format
suitable for non-binary transmission (such as secure electronic mail).
.IP "\fBnlist [\fIdisplay\^\fB [ \fI... display\^\fB] ]\fR"
Like the command
.BR list ,
described above, print output in the numeric form output by the command
.BR nextract ,
described above.
.IP "\fBnmerge [\fIfile \^\fB[ \fI... file\^\fB] ]\fR"
Same as merge, except that the information in each
.I file
is in the numeric form output by the command
.B nextract
(described above).
.IP "\fBquit\fR"
Exit from
.BR xauth ,
and do not modify the authorization file.
The interrupt character (\fB<ctrl-C>\fR under \*(CO) is equivalent to this
command.
.IP "\fBremove \fIdisplay \fB[ ... \fIdisplay\^\fB]\fR"
Remove from the authorization file the information for each
.IR display .
.IP "\fBsource \fIfile\^\fR"
Read
.I file
and execute all of the
.B xauth
commands it contains.
.B xauth
ignores all lines within
.I file
that begin with a pound sign `#'.
The
.I file
`-' indicates the standard input.
.SH "Display Names"
Display names used with the
.B xauth
commands
.BR add ,
.BR extract ,
.BR list ,
.BR merge ,
.BR nextract ,
.BR nlist ,
.BR nmerge ,
and
.B remove
use the same format as the environmental variable
.B DISPLAY
and the common command-line argument
.BR \-display .
.B xauth
ignores display-specific information (such as the screen number),
because it is unnecessary.
Same-machine connections (such as local-host sockets,
shared memory, and the Internet Protocol host name \fBlocalhost\fP)
are referred to as \fIhostname\fB/unix:\fIdisplaynumber\fR
so that local entries
for different machines can be stored in one authority file.
.\".SH Example
.\"The following example demonstrates the most common use for
.\".BR xauth ,
.\"which is to extract the entry for the current display,
.\"copy it to another machine,
.\"and merge it into the user's authority file on the remote machine:
.\".DM
.\"	xauth extract - $DISPLAY | rsh other xauth merge -
.\".DE
.SH Environment
.B xauth
reads the following environmental variables:
.IP \fBXAUTHORITY\fR
The name of the authority file to use if the option
.B \-f
is not used.
If this variable is not set,
.B xauth
reads the contents of file
.BR $HOME/.Xauthority .
.IP \fBHOME\fR
The user's home directory if
.B XAUTHORITY
is not defined.
.SH "See Also"
.B
xdm,
X utilities
.R
.SH Notes
.B xauth
does not interact with the X server.
.PP
If your network is not secure, be sure to encrypt the authorization information
before you pass it to another machine.
Likewise, the protocol
.B MIT-MAGIC-COOKIE-1
is not very useful in insecure environments.
Sites that are interested in additional security
should consider using encrypted authorization mechanisms, such as Kerberos.
.PP
Each
.I display
option in the above commands uses the same format as the environmental variable
.BR DISPLAY .
.PP
.II "Fulton, Jim"
.B xauth
was written by Jim Fulton of the MIT X Consortium.
