granicus.if.org Git - linux-pam/blob - modules/pam_mail/pam_mail.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_mail">
   6
   7   <refmeta>
   8     <refentrytitle>pam_mail</refentrytitle>
   9     <manvolnum>8</manvolnum>
  10     <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_mail-name">
  14     <refname>pam_mail</refname>
  15     <refpurpose>Inform about available mail</refpurpose>
  16   </refnamediv>
  17
  18   <refsynopsisdiv>
  19     <cmdsynopsis id="pam_mail-cmdsynopsis">
  20       <command>pam_mail.so</command>
  21       <arg choice="opt">
  22         close
  23       </arg>
  24       <arg choice="opt">
  25         debug
  26       </arg>
  27       <arg choice="opt">
  28         dir=<replaceable>maildir</replaceable>
  29       </arg>
  30       <arg choice="opt">
  31         empty
  32       </arg>
  33       <arg choice="opt">
  34         hash=<replaceable>count</replaceable>
  35       </arg>
  36       <arg choice="opt">
  37         noenv
  38       </arg>
  39       <arg choice="opt">
  40         nopen
  41       </arg>
  42       <arg choice="opt">
  43         quiet
  44       </arg>
  45       <arg choice="opt">
  46         standard
  47       </arg>
  48     </cmdsynopsis>
  49   </refsynopsisdiv>
  50
  51   <refsect1 id="pam_mail-description">
  52
  53     <title>DESCRIPTION</title>
  54
  55     <para>
  56       The pam_mail PAM module provides the "you have new mail"
  57       service to the user. It can be plugged into any application
  58       that has credential or session hooks. It gives a single message
  59       indicating the <emphasis>newness</emphasis> of any mail it finds
  60       in the user's mail folder. This module also sets the PAM
  61       environment variable, <emphasis remap='B'>MAIL</emphasis>, to the
  62       user's mail directory.
  63     </para>
  64     <para>
  65       If the mail spool file (be it <filename>/var/mail/$USER</filename>
  66       or a pathname given with the <option>dir=</option> parameter) is
  67       a directory then pam_mail assumes it is in the
  68       <emphasis remap='I'>Maildir</emphasis> format.
  69     </para>
  70   </refsect1>
  71
  72   <refsect1 id="pam_mail-options">
  73
  74     <title>OPTIONS</title>
  75     <para>
  76       <variablelist>
  77
  78         <varlistentry>
  79           <term>
  80             <option>close</option>
  81           </term>
  82           <listitem>
  83             <para>
  84               Indicate if the user has any mail also on logout.
  85             </para>
  86           </listitem>
  87         </varlistentry>
  88
  89         <varlistentry>
  90           <term>
  91             <option>debug</option>
  92           </term>
  93           <listitem>
  94             <para>
  95               Print debug information.
  96             </para>
  97           </listitem>
  98         </varlistentry>
  99
 100         <varlistentry>
 101           <term>
 102             <option>dir=<replaceable>maildir</replaceable></option>
 103           </term>
 104           <listitem>
 105             <para>
 106               Look for the users' mail in an alternative location defined by
 107              <filename>maildir/&lt;login&gt;</filename>.  The default
 108              location for mail is <filename>/var/mail/&lt;login&gt;</filename>.
 109              Note, if the supplied
 110              <filename>maildir</filename> is prefixed by a '~', the
 111              directory is interpreted as indicating a file in the user's
 112              home directory.
 113             </para>
 114           </listitem>
 115         </varlistentry>
 116
 117         <varlistentry>
 118           <term>
 119             <option>empty</option>
 120           </term>
 121           <listitem>
 122             <para>
 123               Also print message if user has no mail.
 124             </para>
 125           </listitem>
 126         </varlistentry>
 127
 128         <varlistentry>
 129           <term>
 130             <option>hash=<replaceable>count</replaceable></option>
 131           </term>
 132           <listitem>
 133             <para>
 134               Mail directory hash depth. For example, a
 135               <emphasis>hashcount</emphasis> of 2 would
 136               make the mail file be
 137               <filename>/var/spool/mail/u/s/user</filename>.
 138             </para>
 139           </listitem>
 140         </varlistentry>
 141
 142         <varlistentry>
 143           <term>
 144             <option>noenv</option>
 145           </term>
 146           <listitem>
 147             <para>
 148               Do not set the <emphasis remap='B'>MAIL</emphasis>
 149               environment variable.
 150             </para>
 151           </listitem>
 152         </varlistentry>
 153
 154         <varlistentry>
 155           <term>
 156             <option>nopen</option>
 157           </term>
 158           <listitem>
 159             <para>
 160               Don't print any mail information on login. This flag is
 161               useful to get the <emphasis remap='B'>MAIL</emphasis>
 162               environment variable set, but to not display any information
 163               about it.
 164             </para>
 165           </listitem>
 166         </varlistentry>
 167
 168         <varlistentry>
 169           <term>
 170             <option>quiet</option>
 171           </term>
 172           <listitem>
 173             <para>
 174               Only report when there is new mail.
 175             </para>
 176           </listitem>
 177         </varlistentry>
 178
 179         <varlistentry>
 180           <term>
 181             <option>standard</option>
 182           </term>
 183           <listitem>
 184             <para>
 185               Old style "You have..." format which doesn't show the
 186               mail spool being used. This also implies "empty".
 187             </para>
 188           </listitem>
 189         </varlistentry>
 190
 191       </variablelist>
 192
 193     </para>
 194   </refsect1>
 195
 196   <refsect1 id="pam_mail-types">
 197     <title>MODULE TYPES PROVIDED</title>
 198     <para>
 199       The <option>session</option> and
 200       <option>auth</option> (on establishment and
 201       deletion of credentials) module types are provided.
 202     </para>
 203   </refsect1>
 204
 205   <refsect1 id='pam_mail-return_values'>
 206     <title>RETURN VALUES</title>
 207     <variablelist>
 208       <varlistentry>
 209         <term>PAM_BUF_ERR</term>
 210         <listitem>
 211            <para>
 212              Memory buffer error.
 213           </para>
 214         </listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term>PAM_SERVICE_ERR</term>
 219         <listitem>
 220           <para>
 221             Badly formed arguments.
 222           </para>
 223         </listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term>PAM_SUCCESS</term>
 228         <listitem>
 229           <para>
 230             Success.
 231           </para>
 232         </listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term>PAM_USER_UNKNOWN</term>
 237         <listitem>
 238           <para>
 239             User not known.
 240           </para>
 241         </listitem>
 242       </varlistentry>
 243
 244     </variablelist>
 245   </refsect1>
 246
 247   <refsect1 id='pam_mail-examples'>
 248     <title>EXAMPLES</title>
 249     <para>
 250       Add the following line to <filename>/etc/pam.d/login</filename> to
 251       indicate that the user has new mail when they login to the system.
 252       <programlisting>
 253 session  optional  pam_mail.so standard
 254       </programlisting>
 255     </para>
 256   </refsect1>
 257
 258   <refsect1 id='pam_mail-see_also'>
 259     <title>SEE ALSO</title>
 260     <para>
 261       <citerefentry>
 262         <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
 263       </citerefentry>,
 264       <citerefentry>
 265         <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
 266       </citerefentry>,
 267       <citerefentry>
 268         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 269       </citerefentry>
 270     </para>
 271   </refsect1>
 272
 273   <refsect1 id='pam_mail-author'>
 274     <title>AUTHOR</title>
 275       <para>
 276         pam_mail was written by Andrew G. Morgan &lt;morgan@kernel.org&gt;.
 277       </para>
 278   </refsect1>
 279
 280 </refentry>