xauth(1X) xauth(1X)NAME xauth - manages X authority files SYNOPSIS xauth [-f auth-file] [-vqib] [command arg...] DESCRIPTION xauth edits and displays the authorization information used in connecting to the X server. In particular, xauth extracts authorization records from one machine and merges them on another, such as when using remote logins or when granting access to other users. You can enter commands interactively on the xauth command line, as described below, or you can use a script. Note that xauth does not contact the X server. Options The xauth command accepts these options, which can be given individually, such as -q -i, or may be combined, such as -qi. -b Causes xauth to break any authority file locks be- fore proceeding. You should use this option to clean up stale locks only. -f auth-file Specifies the name of the authority file to use. By default, xauth uses the file specified by the XAUTHORITY environment variable or by the .Xauthority file in the user's home directory. -i Causes xauth to ignore any authority file locks. Normally, xauth refuses to read or edit an authority file that has been locked by another client applica- tion, such as xdm or another xauth. -q Indicates that xauth should operate quietly and not print status messages. This is the default if an xauth command is given on the command line or if the standard output is not directed to a terminal. -v Causes xauth to operate verbosely and print status messages indicating the results of various opera- tions, such as how many records have been read or written. This is the default if xauth is reading commands from its standard input and its standard output is directed to a terminal. Commands The xauth command line recognizes the following commands to manipulate authority files: November, 1990 1
xauth(1X) xauth(1X)add display protocol hexkey Adds an authorization entry to the authorization file for the indicated display using the given pro- tocol and key data. The data is specified as an even-length string of hexadecimal digits, each pair representing one octet. The first digit gives the most significant 4 bits of the octet and the second digit gives the least significant 4 bits. A proto- col name consisting of a single period is treated as an abbreviation for MIT-MAGIC-COOKIE-1. exit Causes xauth to write out the authority file, if al- lowed and if any modifications have been made, and then causes xauth to terminate. xauth treats an end-of-file as an implicit exit command. help [string] Prints on the standard output a description of all commands that begin with the given string. If you do not specify string, xauth prints a description of all commands. info Prints on the standard output information describing the authorization file, whether any changes have been made, and the source of the xauth commands be- ing read. [n]extract file display... Writes authorization entries for each of the speci- fied displays to file. If you specify the nextract command, the entries are written in a numeric format suitable for nonbinary transmission, such as secure electronic mail. You can use the merge and nmerge commands to read back entries. If file is a single dash, the entries are written to the standard out- put. [n]list [display] ... Prints authorization entries for each of the speci- fied displays (or all displays if no displays are named) on the standard output. If you specify the nlist command, xauth prints the entries in the numeric format used by the nextract command; other- wise, they are printed in a textual format. Key data is always displayed in the hexadecimal format given in the description of the add command. [n]merge [file] ... Reads authorization entries from the specified files and merges them into the authorization database, su- perceding any matching existing entries. If you specify the nmerge command, xauth uses the numeric 2 November, 1990
xauth(1X) xauth(1X)format used by the nextract command. If file is a single dash, xauth reads the standard input if it hasn't been read before. quit Causes xauth to exit without writing out the author- ity file, ignoring any modifications. You can also quit by pressing the interrupt character. remove display... Removes from the authority file authorization en- tries that match the specified displays. source file Causes xauth to treat the specified file as a script containing xauth commands to execute. xauth ignores blank lines and lines that begin with a number sign (#). If file is a single dash, xauth reads the standard input if it hasn't been read before. ? Prints on the standard output a short list of all valid commands. Display names Display names for the add, [n]extract, [n]list, [n]merge, and remove commands use the same format as the DISPLAY en- vironment variable and the X Toolkit -display display command-line argument. See X(1X) for details. Display- specific information, such as the screen number, is unneces- sary and is ignored. Same-machine connections, such as local-host sockets, shared memory, and the Internet Protocol hostname localhost, are referred to as hostname/unix:displaynumber so that local entries for dif- ferent machines may be stored in one authority file. Environment variables The xauth command uses the following environment variables: XAUTHORITY Specifies the name of the authority file to use if the -f option isn't used. If this variable is not set, xauth uses the .Xauthority file in the user's home directory. HOME Specifies the user's home directory if XAUTHORITY isn't defined. EXAMPLES The most common use for xauth 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. The following example does this for a system called other: November, 1990 3
xauth(1X) xauth(1X)xauth extract - $DISPLAY | rsh other xauth merge - LIMITATIONS Users that have unsecure networks should take care to use encrypted file-transfer mechanisms to copy authorization en- tries between machines. Similarly, the MIT-MAGIC-COOKIE-1 protocol is not very useful in unsecure environments. Sites that are interested in additional security may need to use encrypted authorization mechanisms such as Kerberos. Spaces are currently not allowed in the protocol name. Quoting could be added. NOTES Copyright 1989, Massachusetts Institute of Technology. See X(1X) for a full statement of rights and permissions. Author: Jim Fulton, MIT X Consortium 4 November, 1990