Penguin
Recent Changes
Annotated edit history of xauth(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 JohnMcPherson 1 !!NAME
2
3 xauth - X authority file utility
4
5 !!SYNOPSIS
6
7 __xauth__ [[ __-f__ __''authfile''__ ] [[ __-vqib__ ] [[ __''command''__ __''arg''__ __''...''__ ]
8
9 !!DESCRIPTION
10
11 The __''xauth''__ program is used to edit and display the authorization information used in connecting to the X server. This program is usually used to extract authorization records from one machine and merge them in on another (as is the case when using remote logins or granting access to other users). Commands (described below) may be entered interactively, on the __''xauth''__ command line, or in scripts. Note that this program does __not__ contact the X server except when the generate command is used. Normally __''xauth''__ is not used to create the authority file entry in the first place; __''xdm''__ does that.
12
13 !!OPTIONS
14
15 The following options may be used with __''xauth''__. They may be given individually (e.g., __''-q''__ __''-i''__) or may combined (e.g., __''-qi''__).
16
17 ;__-f__ __''authfile''__: This option specifies the name of the authority file to use. By default, __''xauth''__ will use the file specified by the XAUTHORITY environment variable or __''.Xauthority''__ in the user's home directory.
18
19
20 ;__-q__: This option indicates that __''xauth''__ should operate quietly and not print unsolicited status messages. This is the default if an __''xauth''__ command is is given on the command line or if the standard output is not directed to a terminal.
21
22
23 ;__-v__: This option indicates that __''xauth''__ should operate verbosely and print status messages indicating the results of various operations (e.g., how many records have been read in or written out). This is the default if __''xauth''__ is reading commands from its standard input and its standard output is directed to a terminal.
24
25
26 ;__-i__: This option indicates that __''xauth''__ should ignore any authority file locks. Normally, __''xauth''__ will refuse to read or edit any authority files that have been locked by other programs (usually __''xdm''__ or another __''xauth''__).
27
28
29 ;__-b__: This option indicates that __''xauth''__ should attempt to break any authority file locks before proceeding. Use this option only to clean up stale locks.
30
31 !!COMMANDS
32
33 The following commands may be used to manipulate authority files:
34
35 ;__add__ __''displayname''__ __''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 4 bits of the octet, and the second digit of the pair gives the least significant 4 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''__.
36
37
38 ;__generate__ __''displayname''__ __''protocolname''__ [[__trusted|untrusted__] [[__timeout__ __''seconds''__] [[__group__ __''group-id''__] [[__data__ __''hexdata''__]: This command is similar to add. The main difference is that instead of requiring the user to supply the key data, it connects to the server specified in __''displayname''__ and uses the SECURITY extension in order to get the key data to store in the authorization file. If the server cannot be contacted or if it does not support the SECURITY extension, the command fails. Otherwise, an authorization entry for the indicated display using the given protocol is added to the authorization file. A protocol name consisting of just a single period is treated as an abbreviation for __''MIT-MAGIC-COOKIE-1''__.
39
40 ;:If the __trusted__ option is used, clients that connect using this authorization will have full run of the display, as usual. If __untrusted__ is used, clients that connect using this authorization will be considered untrusted and prevented from stealing or tampering with data belonging to trusted clients. See the SECURITY extension specification for full details on the restrictions imposed on untrusted clients. The default is __untrusted__.
41
42 ;: The __timeout__ option specifies how long in seconds this authorization will be valid. If the authorization remains unused (no clients are connected with it) for longer than this time period, the server purges the authorization, and future attempts to connect using it will fail. Note that the purging done by the server does __not__ delete the authorization entry from the authorization file. The default timeout is 60 seconds.
43
44
45 ;: The __group__ option specifies the application group that clients connecting with this authorization should belong to. See the application group extension specification for more details. The default is to not belong to an application group.
46
47
48 ;:The __data__ option specifies data that the server should use to generate the authorization. Note that this is __not__ the same data that gets written to the authorization file. The interpretation of this data depends on the authorization protocol. The __''hexdata''__ is in the same format as the __''hexkey''__ described in the add command. The default is to send no data.
49
50
51 ;__[[n]extract__ __''filename''__ __''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 filename consists of just a single dash, the entries will be written to the standard output.
52
53 ;__[[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.
54
55 ;__[[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 filename consists of just a single dash, the standard input will be read if it hasn't been read before.
56
57 ;__remove__ __''displayname''__...: Authorization entries matching the specified displays are removed from the authority file.
58
59
60 ;__source__ __''filename''__: The specified file is treated as a script containing __''xauth''__ commands to execute. Blank lines and lines beginning with a sharp sign (#) are ignored. A single dash may be used to indicate the standard input, if it hasn't already been read.
61
62
63 ;__info__: Information describing the authorization file, whether or not any changes have been made, and from where __''xauth''__ commands are being read is printed on the standard output.
64
65
66 ;__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.
67
68
69 ;__quit__: The program exits, ignoring any modifications. This may also be accomplished by pressing the interrupt character.
70
71 ;__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.
72
73
74 ;__?__: A short list of the valid commands is printed on the standard output.
75
76
77 !!DISPLAY NAMES
78
79 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- 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 different machines may be stored in one authority file.
80
81 !!EXAMPLE
82
83 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:
84
85 % xauth extract - $DISPLAY | rsh otherhost xauth merge -
86
87
88 The following command contacts the server :0 to create an authorization using the MIT-MAGIC-COOKIE-1 protocol. Clients that connect with this authorization will be untrusted.
89 % xauth generate :0 .
90
91
92 !!ENVIRONMENT
93
94 This __''xauth''__ program uses the following environment variables:
95
96 ;__XAUTHORITY__: to get the name of the authority file to use if the __''-f''__ option isn't used.
97
98
99 ;__HOME__: to get the user's home directory if XAUTHORITY isn't defined.
100
101
102 !!FILES
103
104 ;__''$HOME/.Xauthority''__: default authority file if XAUTHORITY isn't defined.
105
106
107 !!BUGS
108
109 Users that have unsecure networks should take care to use encrypted file transfer mechanisms to copy authorization entries 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.
110
111 Spaces are currently not allowed in the protocol name. Quoting could be added for the truly perverse.
112
113 !!AUTHOR
114
115 Jim Fulton, MIT X Consortium
116
117
118
119 !!X Version 11 Release 6.5 xauth(1)
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.