pam_xauth(8)      System Administrator's Manual      pam_xauth(8)

NAME
       pam_xauth - forward xauth keys between users

SYNOPSIS
       session optional /lib/security/pam_xauth.so arguments

DESCRIPTION
       pam_xauth.so  is designed to forward xauth keys (sometimes
       referred to as "cookies") between users.

       Without pam_xauth, when xauth is enabled and a  user  uses
       the  su command to assume superuser priviledges, that user
       is not able to run X commands as root without somehow giv-
       ing  root  access  to the xauth key used for the current X
       session.  pam_xauth solves the problem by  forwarding  the
       key from the user running su (the source user) to the user
       whose identity the source user  is  assuming  (the  target
       user)  when the session is created, and destroying the key
       when the session is torn down.

       This means, for example, that when  you  run  su  from  an
       xterm sesssion, you will be able to run X programs without
       explicitly dealing with the xauth command or ~/.Xauthority
       files.

       By default, pam_xauth will only forward keys when the root
       user is the target user.  Source users can add  the  names
       of other users that they trust as target users in the file
       ~/.xauth/export; once they have done so, even root is  not
       trusted  unless it is listed in ~/.xauth/export.  The spe-
       cial username * matches every user, but  neither  globbing
       nor  regexp  matching  is  done.  If ~/.xauth/export is an
       empty file, pam_xauth will never forward any of the user's
       xauth keys anywhere.

       Similarly,   pam_xauth   looks   at   the   target  user's
       ~/.xauth/import file if the target user  wants  to  accept
       xauth keys from the source user.  Users who do not wish to
       have their ~/.Xauthority files mangled when they are  tar-
       get  users  can  create the empty file ~/.xauth/import and
       pam_xauth will do nothing  to  them--neither  import  keys
       into them nor remove keys from them.

       pam_xauth  will  only forward keys if xauth can list a key
       connected to the $DISPLAY environment variable.

       If a source user opens multiple  sessions  from  a  single
       display to a single target user, the xauth key exported to
       the target will not be destroyed  in  the  target's  xauth
       database  until  the  source user closes the last session.
       The reference counts are kept in  the  file  ~/.xauth/ref-
       count/targetname/keyname and if the file has not been mod-
       ified in a long time, pam_xauth will print a warning  sug-
       gesting  that  the user delete the file, on the assumption
       that su sessions should not last very long, normally.

EXAMPLES
       While pam_xauth will create the .xauth directory the first
       time  it  is  run,  if you want to set it up before it has
       ever run, you can do it yourself like so:
       $ mkdir ~/.xauth
       $ chmod 700 ~/.xauth
       The rest of these exmaples assume that the ~/.xauth direc-
       tory exists.

       A user does not want to export any xauth keys, even to the
       root account:
       $ touch ~/.xauth/export

       A system administrator often needs to su  to  his/her  own
       account  while working from other people's accounts to fix
       their  problems.   He/she  does  not  want  his/her  xauth
       database polluted with extra keys:
       $ touch ~/.xauth/import

       A user often helps his/her friends with their accounts and
       wants X to work when  he  has  used  su  to  assume  their
       accounts, no matter who the user is:
       $ echo '*' > ~/.xauth/export

       Frank trusts Bill and the root user, but no one else, with
       his xauth keys:
       $ echo 'root
       bill' > ~/.xauth/export

ARGUMENTS
       debug  Turns on debugging messages sent to  syslog.   Most
              debugging  messages  are sent as AUTHPRIV messages,
              which means that on most systems they will show  up
              in /var/log/secure.

       logpub Makes  none of the syslogged messages be sent AUTH-
              PRIV.  This is dangerous on a multi-user system but
              can  make  debugging  much  simpler because all the
              logging is in one place.  Normally only  used  with
              the debug argument.

       warndays=days
              Tell  pam_xauth  how  old a refcount file should be
              before it starts complaining.   The  default  is  7
              days.

       warnhours=hours
              Like warndays, but specified in hours.

       systemuser=numericuserid
              Treat  all  users  with  ids  less than or equal to
              numericuserid but greater than 0 (that is;  except-
              ing the root user) as system users, and do not for-
              ward keys to them or from them.   Set  systemuser=0
              to  disable this checking entirely.  The default is
              499.

       xauthpath=/usr/X11R6/bin/xauth
              Specify the path the xauth program (the default  is
              /usr/X11R6/bin/xauth).

IMPLEMENTATION DETAILS
       pam_xauth  will  work  only  if  it  is used from a setuid
       application in which the getuid() call returns the  id  of
       the  user  running the application (alternatively, it will
       work if the getlogin() call works, but that is out of con-
       trol of many of the target applications, like su), and for
       which PAM can supply the name of the account that the user
       is  attempting to assume.  The typical application of this
       type is su.  The application must call both  pam_open_ses-
       sion() and pam_close_session() with the ruid set to the id
       of the calling user and the euid set  to  root,  and  must
       have  provided as the PAM_USER item the name of the target
       user.

       pam_xauth calls xauth as  the  source  user  to  find  the
       canonical  key name and extract the key for $DISPLAY, then
       calls xauth as the target user to merge the key  into  the
       target user's database and later remove the key.

       pam_xauth  cannot  be told not to remove the keys when the
       session is closed.  If, for example, you wish for the root
       account to collect all possible keys and never remove them
       from the database, you should disable pam_xauth key import
       by creating an empty ~root/.xauth/import file, then set up
       root's .profile (or whatever) to do something like this:
       if [ -n "$DISPLAY" -a -n "$LOGNAME" -a "$LOGNAME" != root ]
       then
           su -c $LOGNAME xauth -iq nextract - "$DISPLAY" | \
               xauth nmerge -
       fi

FILES
       ~/.xauth/export
       ~/.xauth/import
       ~/.xauth/refcount/ and all file  and  subdirectories  con-
       tained therein

SEE ALSO
       /usr/doc/pam*/html/index.html

BUGS
       Let's  hope  not,  but if you find any, please report them
       via the "Bug Track" link at http://developer.redhat.com/

AUTHOR
       Michael K. Johnson <johnsonm@redhat.com>

Red Hat Software            1999/4/10                           1