1 files changed, 142 insertions, 0 deletions
diff --git a/Linux-PAM/doc/modules/pam_mail.sgml b/Linux-PAM/doc/modules/pam_mail.sgml
new file mode 100644
index 00000000..397df29e
--- /dev/null
+++ b/Linux-PAM/doc/modules/pam_mail.sgml
@@ -0,0 +1,142 @@
+<!--
+   $Id: pam_mail.sgml,v 1.1.1.2 2002/09/15 20:08:31 hartmans Exp $
+   
+   This file was written by Andrew G. Morgan <morgan@kernel.org>
+-->
+
+<sect1>The mail module
+
+<sect2>Synopsis
+
+<p>
+<descrip>
+
+<tag><bf>Module Name:</bf></tag>
+<tt/pam_mail/
+
+<tag><bf>Author:</bf></tag>
+Andrew G. Morgan &lt;morgan@kernel.org&gt;
+
+<tag><bf>Maintainer:</bf></tag>
+Author
+
+<tag><bf>Management groups provided:</bf></tag>
+Authentication (credential)
+Session (open)
+
+<tag><bf>Cryptographically sensitive:</bf></tag>
+	
+<tag><bf>Security rating:</bf></tag>
+
+<tag><bf>Clean code base:</bf></tag>
+
+<tag><bf>System dependencies:</bf></tag>
+Default mail directory <tt>/var/spool/mail/</tt>
+
+<tag><bf>Network aware:</bf></tag>
+
+</descrip>
+
+<sect2>Overview of module
+
+<p>
+This module looks at the user's mail directory and indicates
+whether the user has any mail in it.
+
+<sect2>Session component
+
+<p>
+<descrip>
+
+<tag><bf>Recognized arguments:</bf></tag>
+<tt/debug/; <tt/dir=/<em/directory-name/; <tt/nopen/; <tt/close/;
+<tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/;
+<tt/quiet/;
+
+<tag><bf>Description:</bf></tag>
+
+This module provides the ``you have new mail'' service to the user. It
+can be plugged into any application that has credential hooks. It gives a
+single message indicating the <em/newness/ of any mail it finds in the
+user's mail folder. This module also sets the <bf/Linux-PAM/
+environment variable, <tt/MAIL/, to the user's mail directory.
+
+<p>
+The behavior of this module can be modified with one of the following
+flags:
+
+<p>
+<itemize>
+<item><tt/debug/
+- write more information to <tt/syslog(3)/.
+
+<item><tt/dir=/<em/pathname/
+- look for the users' mail in an alternative directory given by
+<em/pathname/.  The default location for mail is
+<tt>/var/spool/mail</tt>. Note, if the supplied <em/pathname/ is
+prefixed by a `<tt/&tilde;/', the directory is interpreted as
+indicating a file in the user's home directory.
+
+<item><tt/nopen/
+- instruct the module to <em/not/ print any mail information when the
+user's credentials are acquired. This flag is useful to get the <tt/MAIL/
+environment variable set, but to not display any information about it.
+
+<item><tt/close/
+- instruct the module to indicate if the user has any mail at the as
+the user's credentials are revoked.
+
+<item><tt/noenv/
+- do not set the <tt/MAIL/ environment variable.
+
+<item><tt/empty/
+- indicate that the user's mail directory is empty if this is found to
+be the case.
+
+<item><tt/hash=/<em/hashcount/
+- mail directory hash depth.  For example, a <em/hashcount/ of 2 would
+make the mailfile be <tt>/var/spool/mail/u/s/user</tt>.
+
+<item><tt/standard/
+- old style "You have..." format which doesn't show the mail spool being used.
+  this also implies "empty"
+
+<item><tt/quiet/
+- only report when there is new mail.
+
+</itemize>
+
+<tag><bf>Examples/suggested usage:</bf></tag>
+
+This module can be used to indicate that the user has new mail when
+they <em/login/ to the system. Here is a sample entry for your
+<tt>/etc/pam.conf</tt> file:
+<tscreen>
+<verb>
+#
+# do we have any mail?
+#
+login	session	 optional	pam_mail.so
+</verb>
+</tscreen>
+
+<p>
+Note, if the mail spool file (be it <tt>/var/spool/mail/$USER</tt> or
+a pathname given with the <tt>dir=</tt> parameter) is a directory then
+<tt>pam_mail</tt> assumes it is in the <it>Qmail Maildir</it> format.
+
+<p>
+Note, some applications may perform this function themselves. In such
+cases, this module is not necessary.
+
+</descrip>
+
+<sect2>Authentication component
+
+<p>
+Then authentication companent works the same as the session component,
+except that everything is done during the <tt>pam_setcred()</tt> phase.
+
+<!--
+End of sgml insert for this module.
+-->