granicus.if.org Git - linux-pam/blob - modules/pam_xauth/pam_xauth.8.xml

   1 <?xml version="1.0" encoding='UTF-8'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4
   5 <refentry id="pam_xauth">
   6
   7   <refmeta>
   8     <refentrytitle>pam_xauth</refentrytitle>
   9     <manvolnum>8</manvolnum>
  10     <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_xauth-name">
  14     <refname>pam_xauth</refname>
  15     <refpurpose>PAM module to forward xauth keys between users</refpurpose>
  16   </refnamediv>
  17
  18   <refsynopsisdiv>
  19     <cmdsynopsis id="pam_xauth-cmdsynopsis">
  20       <command>pam_xauth.so</command>
  21       <arg choice="opt">
  22         debug
  23       </arg>
  24       <arg choice="opt">
  25         xauthpath=<replaceable>/path/to/xauth</replaceable>
  26       </arg>
  27       <arg choice="opt">
  28         systemuser=<replaceable>UID</replaceable>
  29       </arg>
  30       <arg choice="opt">
  31         targetuser=<replaceable>UID</replaceable>
  32       </arg>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1 id="pam_xauth-description">
  37     <title>DESCRIPTION</title>
  38     <para>
  39       The pam_xauth PAM module is designed to forward xauth keys
  40       (sometimes referred to as "cookies") between users.
  41     </para>
  42     <para>
  43       Without pam_xauth, when xauth is enabled and a user uses the
  44        <citerefentry>
  45         <refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
  46       </citerefentry> command to assume another user's priviledges,
  47       that user is no longer able to access the original user's X display
  48       because the new user does not have the key needed to access the
  49       display. pam_xauth solves the problem by forwarding the key from
  50       the user running su (the source user) to the user whose identity the
  51       source user is assuming (the target user) when the session is created,
  52       and destroying the key when the session is torn down.
  53     </para>
  54     <para>
  55       This means, for example, that when you run
  56        <citerefentry>
  57         <refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
  58       </citerefentry> from an xterm sesssion, you will be able to run
  59       X programs without explicitly dealing with the
  60       <citerefentry>
  61         <refentrytitle>xauth</refentrytitle><manvolnum>1</manvolnum>
  62       </citerefentry> xauth command or ~/.Xauthority files.
  63     </para>
  64     <para>
  65       pam_xauth will only forward keys if xauth can list a key connected
  66       to the $DISPLAY environment variable.
  67     </para>
  68     <para>
  69       Primitive access control is provided by
  70       <filename>~/.xauth/export</filename> in the invoking user's home
  71       directory and <filename>~/.xauth/import</filename> in the target
  72       user's home directory.
  73     </para>
  74     <para>
  75       If a user has a <filename>~/.xauth/import</filename> file, the user
  76       will only receive cookies from users listed in the file. If there is
  77       no <filename>~/.xauth/import</filename> file, the user will accept
  78       cookies from any other user.
  79     </para>
  80     <para>
  81       If a user has a <filename>.xauth/export</filename> file, the user will
  82       only forward cookies to users listed in the file. If there is no
  83       <filename>~/.xauth/export</filename> file, and the invoking user is
  84       not <emphasis remap='B'>root</emphasis>, the user will forward cookies
  85       to any other user. If there is no <filename>~/.xauth/export</filename>
  86       file, and the invoking user is <emphasis remap='B'>root</emphasis>,
  87       the user will <emphasis remap='I'>not</emphasis> forward cookies to
  88       other users.
  89     </para>
  90     <para>
  91       Both the import and export files support wildcards (such as
  92       <emphasis remap='I'>*</emphasis>). Both the import and export files
  93       can be empty, signifying that no users are allowed.
  94     </para>
  95   </refsect1>
  96
  97   <refsect1 id="pam_xauth-options">
  98     <title>OPTIONS</title>
  99     <variablelist>
 100       <varlistentry>
 101         <term>
 102           <option>debug</option>
 103         </term>
 104         <listitem>
 105           <para>
 106             Print debug information.
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term>
 112           <option>xauthpath=<replaceable>/path/to/xauth</replaceable></option>
 113         </term>
 114         <listitem>
 115           <para>
 116             Specify the path the xauth program (it is expected in
 117             <filename>/usr/X11R6/bin/xauth</filename>,
 118             <filename>/usr/bin/xauth</filename>, or
 119             <filename>/usr/bin/X11/xauth</filename> by default).
 120           </para>
 121         </listitem>
 122       </varlistentry>
 123       <varlistentry>
 124         <term>
 125           <option>systemuser=<replaceable>UID</replaceable></option>
 126         </term>
 127         <listitem>
 128           <para>
 129             Specify the highest UID which will be assumed to belong to a
 130             "system" user. pam_xauth will refuse to forward credentials to
 131             users with UID less than or equal to this number, except for
 132             root and the "targetuser", if specified.
 133           </para>
 134         </listitem>
 135       </varlistentry>
 136       <varlistentry>
 137         <term>
 138           <option>targetuser=<replaceable>UID</replaceable></option>
 139         </term>
 140         <listitem>
 141           <para>
 142             Specify  a single target UID which is exempt from the
 143             systemuser check.
 144           </para>
 145         </listitem>
 146       </varlistentry>
 147     </variablelist>
 148   </refsect1>
 149
 150   <refsect1 id="pam_xauth-services">
 151     <title>MODULE SERVICES PROVIDED</title>
 152     <para>
 153       Only the <emphasis remap='B'>session</emphasis> service is supported.
 154     </para>
 155   </refsect1>
 156
 157   <refsect1 id='pam_xauth-return_values'>
 158     <title>RETURN VALUES</title>
 159     <variablelist>
 160       <varlistentry>
 161         <term>PAM_BUF_ERR</term>
 162         <listitem>
 163            <para>
 164              Memory buffer error.
 165           </para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term>PAM_PERM_DENIED</term>
 171         <listitem>
 172           <para>
 173             Permission denied by import/export file.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term>PAM_SESSION_ERR</term>
 180         <listitem>
 181           <para>
 182             Cannot determine user name, UID or access users home directory.
 183           </para>
 184         </listitem>
 185       </varlistentry>
 186
 187       <varlistentry>
 188         <term>PAM_SUCCESS</term>
 189         <listitem>
 190           <para>
 191             Success.
 192           </para>
 193         </listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term>PAM_USER_UNKNOWN</term>
 198         <listitem>
 199           <para>
 200             User not known.
 201           </para>
 202         </listitem>
 203       </varlistentry>
 204
 205     </variablelist>
 206   </refsect1>
 207
 208   <refsect1 id='pam_xauth-examples'>
 209     <title>EXAMPLES</title>
 210     <para>
 211       Add the following line to <filename>/etc/pam.d/su</filename> to
 212       forward xauth keys between users when calling su:
 213       <programlisting>
 214 session  optional  pam_xauth.so
 215       </programlisting>
 216     </para>
 217   </refsect1>
 218
 219   <refsect1 id="pam_xauth-implementation">
 220     <title>IMPLEMENTATION DETAILS</title>
 221     <para>
 222       pam_xauth will work <emphasis remap='I'>only</emphasis> if it is
 223       used from a setuid application in which the
 224       <function>getuid</function>() call returns the id of the user
 225       running the application, and for which PAM can supply the name
 226       of the account that the user is attempting to assume. The typical
 227       application of this type is
 228       <citerefentry>
 229        <refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
 230       </citerefentry>.
 231       The application must call both <function>pam_open_session</function>()
 232       and <function>pam_close_session</function>() with the ruid set to the
 233       uid of the calling user and the euid set to root, and must have
 234       provided as the PAM_USER item the name of the target user.
 235     </para>
 236     <para>
 237       pam_xauth calls
 238       <citerefentry>
 239        <refentrytitle>xauth</refentrytitle><manvolnum>1</manvolnum>
 240       </citerefentry> the source user to extract the key for $DISPLAY,
 241       then calls xauth as the target user to merge the key into the a
 242       temporary database and later remove the database.
 243     </para>
 244     <para>
 245       pam_xauth cannot be told to not remove the keys when the session
 246       is closed.
 247     </para>
 248   </refsect1>
 249
 250   <refsect1 id="pam_lastlog-files">
 251     <title>FILES</title>
 252     <variablelist>
 253       <varlistentry>
 254         <term><filename>~/.xauth/import</filename></term>
 255         <listitem>
 256           <para>XXX</para>
 257         </listitem>
 258       </varlistentry>
 259       <varlistentry>
 260         <term><filename>~/.xauth/export</filename></term>
 261         <listitem>
 262           <para>XXX</para>
 263         </listitem>
 264       </varlistentry>
 265     </variablelist>
 266   </refsect1>
 267
 268
 269   <refsect1 id='pam_xauth-see_also'>
 270     <title>SEE ALSO</title>
 271     <para>
 272       <citerefentry>
 273         <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
 274       </citerefentry>,
 275       <citerefentry>
 276         <refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
 277       </citerefentry>,
 278       <citerefentry>
 279         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 280       </citerefentry>
 281     </para>
 282   </refsect1>
 283
 284   <refsect1 id='pam_xauth-author'>
 285     <title>AUTHOR</title>
 286       <para>
 287         pam_xauth was written by Nalin Dahyabhai &lt;nalin@redhat.com&gt;,
 288         based on original version by
 289         Michael K. Johnson &lt;johnsonm@redhat.com&gt;.
 290       </para>
 291   </refsect1>
 292
 293 </refentry>