modules/pam_listfile/pam_listfile.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_listfile">
   6
   7   <refmeta>
   8     <refentrytitle>pam_listfile</refentrytitle>
   9     <manvolnum>8</manvolnum>
  10     <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_listfile-name">
  14     <refname>pam_listfile</refname>
  15     <refpurpose>deny or allow services based on an arbitrary file</refpurpose>
  16   </refnamediv>
  17
  18   <refsynopsisdiv>
  19     <cmdsynopsis id="pam_listfile-cmdsynopsis">
  20       <command>pam_listfile.so</command>
  21       <arg choice="plain">
  22         item=[tty|user|rhost|ruser|group|shell]
  23       </arg>
  24       <arg choice="plain">
  25         sense=[allow|deny]
  26       </arg>
  27       <arg choice="plain">
  28         file=<replaceable>/path/filename</replaceable>
  29       </arg>
  30       <arg choice="plain">
  31         onerr=[succeed|fail]
  32       </arg>
  33       <arg choice="opt">
  34         apply=[<replaceable>user</replaceable>|<replaceable>@group</replaceable>]
  35       </arg>
  36       <arg choice="opt">
  37         quiet
  38       </arg>
  39     </cmdsynopsis>
  40   </refsynopsisdiv>
  41
  42   <refsect1 id="pam_listfile-description">
  43
  44     <title>DESCRIPTION</title>
  45
  46     <para>
  47       pam_listfile is a PAM module which provides a way to deny or
  48       allow services based on an arbitrary file.
  49     </para>
  50     <para>
  51       The module gets the <option>item</option> of the type specified --
  52       <emphasis>user</emphasis> specifies the username,
  53       <emphasis>PAM_USER</emphasis>; tty specifies the name of the terminal
  54       over which the request has been made, <emphasis>PAM_TTY</emphasis>;
  55       rhost specifies the name of the remote host (if any) from which the
  56       request was made, <emphasis>PAM_RHOST</emphasis>; and ruser specifies
  57       the name of the remote user (if available) who made the request,
  58       <emphasis>PAM_RUSER</emphasis> -- and looks for an instance of that
  59       item in the <option>file=<replaceable>filename</replaceable></option>.
  60       <filename>filename</filename> contains one line per item listed. If
  61       the item is found, then if
  62       <option>sense=<replaceable>allow</replaceable></option>,
  63       <emphasis>PAM_SUCCESS</emphasis> is returned, causing the authorization
  64       request to succeed; else if
  65       <option>sense=<replaceable>deny</replaceable></option>,
  66       <emphasis>PAM_AUTH_ERR</emphasis> is returned, causing the authorization
  67       request to fail.
  68     </para>
  69     <para>
  70       If an error is encountered (for instance, if
  71       <filename>filename</filename> does not exist, or a poorly-constructed
  72       argument is encountered), then if <emphasis>onerr=succeed</emphasis>,
  73       <emphasis>PAM_SUCCESS</emphasis> is returned, otherwise if
  74       <emphasis>onerr=fail</emphasis>, <emphasis>PAM_AUTH_ERR</emphasis> or
  75       <emphasis>PAM_SERVICE_ERR</emphasis> (as appropriate) will be returned.
  76     </para>
  77     <para>
  78       An additional argument, <option>apply=</option>, can be used
  79       to restrict the application of the above to a specific user
  80       (<option>apply=<replaceable>username</replaceable></option>)
  81       or a given group
  82       (<option>apply=<replaceable>@groupname</replaceable></option>).
  83       This added restriction is only meaningful when used with the
  84       <emphasis>tty</emphasis>, <emphasis>rhost</emphasis> and
  85       <emphasis>shell</emphasis> items.
  86     </para>
  87     <para>
  88       Besides this last one, all arguments should be specified; do not
  89       count on any default behavior.
  90     </para>
  91     <para>
  92       No credentials are awarded by this module.
  93     </para>
  94   </refsect1>
  95
  96   <refsect1 id="pam_listfile-options">
  97
  98     <title>OPTIONS</title>
  99     <para>
 100       <variablelist>
 101
 102         <varlistentry>
 103           <term>
 104             <option>item=[tty|user|rhost|ruser|group|shell]</option>
 105           </term>
 106           <listitem>
 107             <para>
 108               What is listed in the file and should be checked for.
 109             </para>
 110           </listitem>
 111         </varlistentry>
 112
 113         <varlistentry>
 114           <term>
 115             <option>sense=[allow|deny]</option>
 116           </term>
 117           <listitem>
 118             <para>
 119               Action to take if found in file, if the item is NOT found in
 120               the file, then the opposite action is requested.
 121             </para>
 122           </listitem>
 123         </varlistentry>
 124
 125         <varlistentry>
 126           <term>
 127             <option>file=<replaceable>/path/filename</replaceable></option>
 128           </term>
 129           <listitem>
 130             <para>
 131               File containing one item per line. The file needs to be a plain
 132               file and not world writable.
 133             </para>
 134           </listitem>
 135         </varlistentry>
 136
 137         <varlistentry>
 138           <term>
 139             <option>onerr=[succeed|fail]</option>
 140           </term>
 141           <listitem>
 142             <para>
 143               What to do if something weird happens like being unable to open
 144               the file.
 145             </para>
 146           </listitem>
 147         </varlistentry>
 148
 149         <varlistentry>
 150           <term>
 151             <option>apply=[<replaceable>user</replaceable>|<replaceable>@group</replaceable>]</option>
 152           </term>
 153           <listitem>
 154             <para>
 155               Restrict the user class for which the restriction apply. Note that
 156               with <option>item=[user|ruser|group]</option> this does not make sense,
 157               but for <option>item=[tty|rhost|shell]</option> it have a meaning.
 158             </para>
 159           </listitem>
 160         </varlistentry>
 161
 162         <varlistentry>
 163           <term>
 164             <option>quiet</option>
 165           </term>
 166           <listitem>
 167             <para>
 168               Do not treat service refusals or missing list files as
 169               errors that need to be logged.
 170             </para>
 171           </listitem>
 172         </varlistentry>
 173       </variablelist>
 174
 175     </para>
 176   </refsect1>
 177
 178   <refsect1 id="pam_listfile-types">
 179     <title>MODULE TYPES PROVIDED</title>
 180     <para>
 181       All module types (<option>auth</option>, <option>account</option>,
 182       <option>password</option> and <option>session</option>) are provided.
 183     </para>
 184   </refsect1>
 185
 186   <refsect1 id='pam_listfile-return_values'>
 187     <title>RETURN VALUES</title>
 188     <para>
 189       <variablelist>
 190
 191         <varlistentry>
 192           <term>PAM_AUTH_ERR</term>
 193           <listitem>
 194             <para>Authentication failure.</para>
 195           </listitem>
 196         </varlistentry>
 197
 198         <varlistentry>
 199           <term>PAM_BUF_ERR</term>
 200           <listitem>
 201              <para>
 202                Memory buffer error.
 203             </para>
 204           </listitem>
 205         </varlistentry>
 206
 207         <varlistentry>
 208           <term>PAM_IGNORE</term>
 209           <listitem>
 210             <para>
 211               The rule does not apply to the <option>apply</option> option.
 212             </para>
 213           </listitem>
 214         </varlistentry>
 215
 216         <varlistentry>
 217           <term>PAM_SERVICE_ERR</term>
 218           <listitem>
 219             <para>
 220               Error in service module.
 221             </para>
 222           </listitem>
 223         </varlistentry>
 224
 225         <varlistentry>
 226           <term>PAM_SUCCESS</term>
 227           <listitem>
 228             <para>
 229               Success.
 230             </para>
 231           </listitem>
 232         </varlistentry>
 233
 234       </variablelist>
 235     </para>
 236   </refsect1>
 237
 238   <refsect1 id='pam_listfile-examples'>
 239     <title>EXAMPLES</title>
 240     <para>
 241       Classic 'ftpusers' authentication can be implemented with this entry
 242       in <filename>/etc/pam.d/ftpd</filename>:
 243       <programlisting>
 244 #
 245 # deny ftp-access to users listed in the /etc/ftpusers file
 246 #
 247 auth    required       pam_listfile.so \
 248         onerr=succeed item=user sense=deny file=/etc/ftpusers
 249       </programlisting>
 250       Note, users listed in <filename>/etc/ftpusers</filename> file are
 251       (counterintuitively) <emphasis>not</emphasis> allowed access to
 252       the ftp service.
 253     </para>
 254     <para>
 255       To allow login access only for certain users, you can use a
 256       <filename>/etc/pam.d/login</filename> entry like this:
 257       <programlisting>
 258 #
 259 # permit login to users listed in /etc/loginusers
 260 #
 261 auth    required       pam_listfile.so \
 262         onerr=fail item=user sense=allow file=/etc/loginusers
 263       </programlisting>
 264       For this example to work, all users who are allowed to use the
 265       login service should be listed in the file
 266       <filename>/etc/loginusers</filename>.  Unless you are explicitly
 267       trying to lock out root, make sure that when you do this, you leave
 268       a way for root to log in, either by listing root in
 269       <filename>/etc/loginusers</filename>, or by listing a user who is
 270       able to <emphasis>su</emphasis> to the root account.
 271     </para>
 272   </refsect1>
 273
 274   <refsect1 id='pam_listfile-see_also'>
 275     <title>SEE ALSO</title>
 276     <para>
 277       <citerefentry>
 278         <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
 279       </citerefentry>,
 280       <citerefentry>
 281         <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
 282       </citerefentry>,
 283       <citerefentry>
 284         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 285       </citerefentry>
 286     </para>
 287   </refsect1>
 288
 289   <refsect1 id='pam_listfile-author'>
 290     <title>AUTHOR</title>
 291       <para>
 292         pam_listfile was written by Michael K. Johnson &lt;johnsonm@redhat.com&gt;
 293         and Elliot Lee &lt;sopwith@cuc.edu&gt;.
 294       </para>
 295   </refsect1>
 296
 297 </refentry>