1XAUTH(1)                    General Commands Manual                   XAUTH(1)
2
3
4

NAME

6       xauth - X authority file utility
7

SYNOPSIS

9       xauth [ -f authfile ] [ -vqibn ] [ command arg ... ]
10

DESCRIPTION

12       The  xauth program is used to edit and display the authorization infor‐
13       mation used in connecting to the X server.   This  program  is  usually
14       used  to  extract authorization records from one machine and merge them
15       in on another (as is the case when  using  remote  logins  or  granting
16       access  to  other  users).   Commands  (described below) may be entered
17       interactively, on the xauth command line, or  in  scripts.   Note  that
18       this  program  does  not  contact the X server except when the generate
19       command is used.  Normally xauth is not used to  create  the  authority
20       file  entry  in  the  first place; the program that starts the X server
21       (often xdm or startx) does that.
22

OPTIONS

24       The following options may be used with xauth.  They may be given  indi‐
25       vidually (e.g., -q -i) or may combined (e.g., -qi).
26
27       -f authfile
28               This  option  specifies  the name of the authority file to use.
29               By default, xauth will use the file specified by the XAUTHORITY
30               environment  variable  or .Xauthority in the user's home direc‐
31               tory.
32
33       -q      This option indicates that xauth should operate quietly and not
34               print  unsolicited  status messages.  This is the default if an
35               xauth command is given on the command line or if  the  standard
36               output is not directed to a terminal.
37
38       -v      This  option  indicates that xauth should operate verbosely and
39               print status messages indicating the results of various  opera‐
40               tions  (e.g.,  how  many  records  have been read in or written
41               out).  This is the default if xauth is  reading  commands  from
42               its  standard  input  and  its standard output is directed to a
43               terminal.
44
45       -i      This option indicates that xauth should  ignore  any  authority
46               file  locks.   Normally,  xauth will refuse to read or edit any
47               authority files that have been locked by other  programs  (usu‐
48               ally xdm or another xauth).
49
50       -b      This  option  indicates  that xauth should attempt to break any
51               authority file locks before proceeding.  Use this  option  only
52               to clean up stale locks.
53
54       -n      This  option indicates that xauth should not attempt to resolve
55               any hostnames, but should simply always print the host  address
56               as stored in the authority file.
57
58       -V      This option shows the version number of the xauth executable.
59

COMMANDS

61       The following commands may be used to manipulate authority files:
62
63       add displayname protocolname hexkey
64               An  authorization  entry  for  the  indicated display using the
65               given protocol and key data is added to the authorization file.
66               The data is specified as an even-lengthed string of hexadecimal
67               digits, each pair representing one octet.  The first  digit  of
68               each  pair  gives the most significant 4 bits of the octet, and
69               the second digit of the pair  gives  the  least  significant  4
70               bits.   For  example,  a  32 character hexkey would represent a
71               128-bit value.  A protocol name consisting  of  just  a  single
72               period is treated as an abbreviation for MIT-MAGIC-COOKIE-1.
73
74
75       generate displayname protocolname [trusted|untrusted]
76               [timeout seconds] [group group-id] [data hexdata]
77
78               This  command  is  similar to add.  The main difference is that
79               instead of requiring the user to supply the key data,  it  con‐
80               nects to the server specified in displayname and uses the SECU‐
81               RITY extension in order to get the key data  to  store  in  the
82               authorization file.  If the server cannot be contacted or if it
83               does not support the SECURITY  extension,  the  command  fails.
84               Otherwise,  an  authorization  entry  for the indicated display
85               using the given protocol is added to the authorization file.  A
86               protocol  name consisting of just a single period is treated as
87               an abbreviation for MIT-MAGIC-COOKIE-1.
88
89               If the trusted option is used, clients that connect using  this
90               authorization  will have full run of the display, as usual.  If
91               untrusted is used, clients that connect using  this  authoriza‐
92               tion  will  be considered untrusted and prevented from stealing
93               or tampering with data belonging to trusted clients.   See  the
94               SECURITY  extension  specification  for  full  details  on  the
95               restrictions imposed on  untrusted  clients.   The  default  is
96               untrusted.
97
98               The  timeout  option  specifies how long in seconds this autho‐
99               rization will be valid.  If the  authorization  remains  unused
100               (no  clients  are  connected with it) for longer than this time
101               period,  the  server  purges  the  authorization,  and   future
102               attempts  to connect using it will fail.  Note that the purging
103               done by the server does not delete the authorization entry from
104               the authorization file.  The default timeout is 60 seconds.
105
106               The  group  option specifies the application group that clients
107               connecting with this authorization should belong to.   See  the
108               application  group  extension  specification  for more details.
109               The default is to not belong to an application group.
110
111               The data option specifies data that the server  should  use  to
112               generate  the  authorization.   Note  that this is not the same
113               data that gets written to the authorization file.   The  inter‐
114               pretation  of  this data depends on the authorization protocol.
115               The hexdata is in the same format as the  hexkey  described  in
116               the add command.  The default is to send no data.
117
118
119       [n]extract filename displayname...
120               Authorization  entries  for  each of the specified displays are
121               written to the indicated file.   If  the  nextract  command  is
122               used,  the entries are written in a numeric format suitable for
123               non-binary transmission (such as secure electronic mail).   The
124               extracted  entries  can  be  read  back  in using the merge and
125               nmerge commands.  If the filename consists  of  just  a  single
126               dash, the entries will be written to the standard output.
127
128       [n]list [displayname...]
129               Authorization  entries  for  each of the specified displays (or
130               all if no displays are named) are printed on the standard  out‐
131               put.   If  the  nlist command is used, entries will be shown in
132               the numeric format used by  the  nextract  command;  otherwise,
133               they  are  shown  in a textual format.  Key data is always dis‐
134               played in the hexadecimal format given in  the  description  of
135               the add command.
136
137       [n]merge [filename...]
138               Authorization entries are read from the specified files and are
139               merged into the authorization database, superseding any  match‐
140               ing  existing  entries.  If  the  nmerge  command  is used, the
141               numeric format given in the description of the extract  command
142               is  used.   If  a  filename consists of just a single dash, the
143               standard input will be read if it hasn't been read before.
144
145       remove displayname...
146               Authorization  entries  matching  the  specified  displays  are
147               removed from the authority file.
148
149       source filename
150               The specified file is treated as a script containing xauth com‐
151               mands to execute.  Blank lines and lines beginning with a sharp
152               sign  (#)  are  ignored.  A single dash may be used to indicate
153               the standard input, if it hasn't already been read.
154
155       info    Information describing the authorization file, whether  or  not
156               any  changes  have been made, and from where xauth commands are
157               being read is printed on the standard output.
158
159       exit    If any modifications have been  made,  the  authority  file  is
160               written  out  (if  allowed),  and the program exits.  An end of
161               file is treated as an implicit exit command.
162
163       quit    The program exits, ignoring any modifications.  This  may  also
164               be accomplished by pressing the interrupt character.
165
166       version This command shows the version number of the xauth executable.
167
168       help [string]
169               A  description of all commands that begin with the given string
170               (or all commands if no string is given) is printed on the stan‐
171               dard output.
172
173       ?       A  short  list of the valid commands is printed on the standard
174               output.
175

DISPLAY NAMES

177       Display names for the add, [n]extract, [n]list,  [n]merge,  and  remove
178       commands  use  the  same format as the DISPLAY environment variable and
179       the common -display command line argument.   Display-specific  informa‐
180       tion  (such  as  the screen number) is unnecessary and will be ignored.
181       Same-machine connections (such as local-host  sockets,  shared  memory,
182       and  the Internet Protocol hostname localhost) are referred to as host‐
183       name/unix:displaynumber so that local entries  for  different  machines
184       may be stored in one authority file.
185

EXAMPLE

187       The  most  common use for xauth is to extract the entry for the current
188       display, copy it to another machine,  and  merge  it  into  the  user's
189       authority file on the remote machine:
190
191               %  xauth extract - $DISPLAY | ssh otherhost xauth merge -
192
193       The following command contacts the server :0 to create an authorization
194       using the MIT-MAGIC-COOKIE-1 protocol.  Clients that connect with  this
195       authorization will be untrusted.
196            %  xauth generate :0 .
197

ENVIRONMENT

199       This xauth program uses the following environment variables:
200
201       XAUTHORITY
202               to  get  the name of the authority file to use if the -f option
203               isn't used.
204
205       HOME    to get the user's home directory if XAUTHORITY isn't defined.
206

FILES

208       $HOME/.Xauthority
209               default authority file if XAUTHORITY isn't defined.
210

SEE ALSO

212       X(7), Xsecurity(7), xhost(1), Xserver(1), xdm(1), startx(1), Xau(3).
213

BUGS

215       Users that have unsecure networks should take  care  to  use  encrypted
216       file   transfer   mechanisms  to  copy  authorization  entries  between
217       machines.  Similarly, the MIT-MAGIC-COOKIE-1 protocol is not very  use‐
218       ful  in unsecure environments.  Sites that are interested in additional
219       security may need to use encrypted  authorization  mechanisms  such  as
220       Kerberos.
221
222       Spaces  are  currently not allowed in the protocol name.  Quoting could
223       be added for the truly perverse.
224

AUTHOR

226       Jim Fulton, MIT X Consortium
227
228
229
230X Version 11                       xauth 1.1                          XAUTH(1)
Impressum