Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XAUTH(1)						 XAUTH(1)

       xauth - X authority file utility

       xauth [ -f authfile ] [ -vqib ] [ command arg ... ]

       The  xauth  program is used to edit and display the autho­
       rization 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.

       The following options may be used with xauth.  They may be
       given individually (e.g., -q -i) or  may	 combined  (e.g.,

       -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.

       -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 out­
	       put is not directed to a terminal.

       -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.

       -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

       -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.

X Version 11		   Release 6.6				1

XAUTH(1)						 XAUTH(1)

       The following commands may be used to manipulate authority

       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-

       generate displayname protocolname [trusted|untrusted]
	       [timeout seconds] [group group-id] [data hexdata]

	       This command is similar to add.	The main  differ­
	       ence is that instead of requiring the user to sup­
	       ply the key data, it connects to the server speci­
	       fied  in	 displayname and uses the SECURITY exten­
	       sion in order to get the key data to store in  the
	       authorization  file.  If the server cannot be con­
	       tacted 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 autho­
	       rization file.  A protocol name consisting of just
	       a  single period is treated as an abbreviation for

	       If the trusted option is used, clients  that  con­
	       nect  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  steal­
	       ing  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.

	       The timeout option specifies how long  in  seconds
	       this  authorization  will be valid.  If the autho­
	       rization 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.

X Version 11		   Release 6.6				2

XAUTH(1)						 XAUTH(1)

	       The default timeout is 60 seconds.

	       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.

	       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.

       [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 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 com­
	       mand 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  filename	 consists
	       of  just a single dash, the standard input will be
	       read if it hasn't been read before.

       remove displayname...
	       Authorization entries matching the specified  dis­
	       plays are removed from the authority file.

X Version 11		   Release 6.6				3

XAUTH(1)						 XAUTH(1)

       source filename
	       The specified file is treated as a script contain­
	       ing 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.

       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.

       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 may 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-
       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.

       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:

	       %  xauth extract - $DISPLAY | rsh otherhost xauth merge -

       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
	    %  xauth generate :0 .

X Version 11		   Release 6.6				4

XAUTH(1)						 XAUTH(1)

       This xauth program uses the  following  environment  vari­

	       to  get	the  name of the authority file to use if
	       the -f option isn't used.

       HOME    to get the user's  home	directory  if  XAUTHORITY
	       isn't defined.

	       default	 authority   file   if	XAUTHORITY  isn't

       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 environ­
       ments.  Sites that are interested in  additional	 security
       may need to use encrypted authorization mechanisms such as

       Spaces are currently not allowed	 in  the  protocol  name.
       Quoting could be added for the truly perverse.

       Jim Fulton, MIT X Consortium

X Version 11		   Release 6.6				5


Want to link to this manual page? Use this URL:

home | help