modules/pam_exec/pam_exec.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_exec">
   6
   7   <refmeta>
   8     <refentrytitle>pam_exec</refentrytitle>
   9     <manvolnum>8</manvolnum>
  10     <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_exec-name">
  14     <refname>pam_exec</refname>
  15     <refpurpose>PAM module which calls an external command</refpurpose>
  16   </refnamediv>
  17
  18   <refsynopsisdiv>
  19     <cmdsynopsis id="pam_exec-cmdsynopsis">
  20       <command>pam_exec.so</command>
  21       <arg choice="opt">
  22         debug
  23       </arg>
  24       <arg choice="opt">
  25          expose_authtok
  26       </arg>
  27       <arg choice="opt">
  28         seteuid
  29       </arg>
  30       <arg choice="opt">
  31         quiet
  32       </arg>
  33       <arg choice="opt">
  34         log=<replaceable>file</replaceable>
  35       </arg>
  36       <arg choice="plain">
  37        <replaceable>command</replaceable>
  38       </arg>
  39       <arg choice="opt">
  40         <replaceable>...</replaceable>
  41       </arg>
  42     </cmdsynopsis>
  43   </refsynopsisdiv>
  44
  45   <refsect1 id="pam_exec-description">
  46
  47     <title>DESCRIPTION</title>
  48
  49     <para>
  50       pam_exec is a PAM module that can be used to run
  51       an external command.
  52     </para>
  53
  54     <para>
  55      The child's environment is set to the current PAM environment list, as
  56      returned by
  57      <citerefentry>
  58         <refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
  59      </citerefentry>
  60      In addition, the following PAM items are
  61      exported as environment variables: <emphasis>PAM_RHOST</emphasis>,
  62      <emphasis>PAM_RUSER</emphasis>, <emphasis>PAM_SERVICE</emphasis>,
  63      <emphasis>PAM_TTY</emphasis>, <emphasis>PAM_USER</emphasis> and
  64      <emphasis>PAM_TYPE</emphasis>, which contains one of the module
  65      types: <option>account</option>, <option>auth</option>,
  66      <option>password</option>, <option>open_session</option> and
  67      <option>close_session</option>.
  68     </para>
  69
  70     <para>
  71       Commands called by pam_exec need to be aware of that the user
  72       can have controll over the environment.
  73     </para>
  74
  75   </refsect1>
  76
  77   <refsect1 id="pam_exec-options">
  78
  79     <title>OPTIONS</title>
  80     <para>
  81       <variablelist>
  82
  83         <varlistentry>
  84           <term>
  85             <option>debug</option>
  86           </term>
  87           <listitem>
  88             <para>
  89               Print debug information.
  90             </para>
  91           </listitem>
  92         </varlistentry>
  93
  94         <varlistentry>
  95           <term>
  96             <option>expose_authtok</option>
  97           </term>
  98           <listitem>
  99             <para>
 100               During authentication the calling command can read
 101               the password from <citerefentry>
 102               <refentrytitle>stdin</refentrytitle><manvolnum>3</manvolnum>
 103               </citerefentry>.
 104             </para>
 105           </listitem>
 106         </varlistentry>
 107
 108         <varlistentry>
 109           <term>
 110             <option>log=<replaceable>file</replaceable></option>
 111           </term>
 112           <listitem>
 113             <para>
 114               The output of the command is appended to
 115               <filename>file</filename>
 116             </para>
 117           </listitem>
 118         </varlistentry>
 119
 120         <varlistentry>
 121           <term>
 122             <option>quiet</option>
 123           </term>
 124           <listitem>
 125             <para>
 126               Per default pam_exec.so will echo the exit status of the
 127               external command if it fails.
 128               Specifying this option will suppress the message.
 129             </para>
 130           </listitem>
 131         </varlistentry>
 132
 133         <varlistentry>
 134           <term>
 135             <option>seteuid</option>
 136           </term>
 137           <listitem>
 138             <para>
 139               Per default pam_exec.so will execute the external command
 140               with the real user ID of the calling process.
 141               Specifying this option means the command is run
 142               with the effective user ID.
 143             </para>
 144           </listitem>
 145         </varlistentry>
 146
 147       </variablelist>
 148
 149     </para>
 150   </refsect1>
 151
 152   <refsect1 id="pam_exec-types">
 153     <title>MODULE TYPES PROVIDED</title>
 154     <para>
 155       All module types (<option>auth</option>, <option>account</option>,
 156       <option>password</option> and <option>session</option>) are provided.
 157     </para>
 158   </refsect1>
 159
 160   <refsect1 id='pam_exec-return_values'>
 161     <title>RETURN VALUES</title>
 162     <para>
 163       <variablelist>
 164
 165         <varlistentry>
 166           <term>PAM_SUCCESS</term>
 167           <listitem>
 168             <para>
 169               The external command was run successfully.
 170             </para>
 171           </listitem>
 172         </varlistentry>
 173
 174         <varlistentry>
 175           <term>PAM_SERVICE_ERR</term>
 176           <listitem>
 177             <para>
 178               No argument or a wrong number of arguments were given.
 179             </para>
 180           </listitem>
 181         </varlistentry>
 182
 183         <varlistentry>
 184           <term>PAM_SYSTEM_ERR</term>
 185           <listitem>
 186             <para>
 187               A system error occurred or the command to execute failed.
 188             </para>
 189           </listitem>
 190         </varlistentry>
 191
 192         <varlistentry>
 193           <term>PAM_IGNORE</term>
 194           <listitem>
 195             <para>
 196               <function>pam_setcred</function> was called, which
 197               does not execute the command.
 198             </para>
 199           </listitem>
 200         </varlistentry>
 201
 202       </variablelist>
 203     </para>
 204   </refsect1>
 205
 206   <refsect1 id='pam_exec-examples'>
 207     <title>EXAMPLES</title>
 208     <para>
 209       Add the following line to <filename>/etc/pam.d/passwd</filename> to
 210       rebuild the NIS database after each local password change:
 211       <programlisting>
 212         password optional pam_exec.so seteuid /usr/bin/make -C /var/yp
 213       </programlisting>
 214
 215       This will execute the command
 216       <programlisting>make -C /var/yp</programlisting>
 217        with effective user ID.
 218     </para>
 219   </refsect1>
 220
 221   <refsect1 id='pam_exec-see_also'>
 222     <title>SEE ALSO</title>
 223     <para>
 224       <citerefentry>
 225         <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
 226       </citerefentry>,
 227       <citerefentry>
 228         <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
 229       </citerefentry>,
 230       <citerefentry>
 231         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 232       </citerefentry>
 233     </para>
 234   </refsect1>
 235
 236   <refsect1 id='pam_exec-author'>
 237     <title>AUTHOR</title>
 238       <para>
 239         pam_exec was written by Thorsten Kukuk &lt;kukuk@thkukuk.de&gt;.
 240       </para>
 241   </refsect1>
 242
 243 </refentry>