summaryrefslogtreecommitdiff
path: root/modules/pam_listfile
diff options
context:
space:
mode:
authorThorsten Kukuk <kukuk@thkukuk.de>2006-06-02 15:37:38 +0000
committerThorsten Kukuk <kukuk@thkukuk.de>2006-06-02 15:37:38 +0000
commitbad0ed8d159cb77466ed81a624355b1e80ead0dc (patch)
treec1115143eded6faa7e8fe0abc42fc50d4e28fe17 /modules/pam_listfile
parent29a98911d9cb5e9187c1afe4e161c6861fac4f2b (diff)
Relevant BUGIDs: 1427738
Purpose of commit: new feature/bugfix Commit summary: --------------- 2006-06-02 Thorsten Kukuk <kukuk@thkukuk.de> * doc/man/PAM.8: Regenerate with DocBook XSL Stylesheets v1.70.1. * doc/man/pam.3: Likewise. * doc/man/pam.conf.5: Likewise. * doc/man/pam_acct_mgmt.3: Likewise. * doc/man/pam_authenticate.3: Likewise. * doc/man/pam_chauthtok.3: Likewise. * doc/man/pam_close_session.3: Likewise. * doc/man/pam_conv.3: Likewise. * doc/man/pam_end.3: Likewise. * doc/man/pam_error.3: Likewise. * doc/man/pam_fail_delay.3: Likewise. * doc/man/pam_get_data.3: Likewise. * doc/man/pam_get_item.3: Likewise. * doc/man/pam_get_user.3: Likewise. * doc/man/pam_getenv.3: Likewise. * doc/man/pam_getenvlist.3: Likewise. * doc/man/pam_info.3: Likewise. * doc/man/pam_open_session.3: Likewise. * doc/man/pam_prompt.3: Likewise. * doc/man/pam_putenv.3: Likewise. * doc/man/pam_set_data.3: Likewise. * doc/man/pam_set_item.3: Likewise. * doc/man/pam_setcred.3: Likewise. * doc/man/pam_sm_acct_mgmt.3: Likewise. * doc/man/pam_start.3: Likewise. * doc/man/pam_strerror.3: Likewise. * doc/man/pam_syslog.3: Likewise. * modules/pam_access/access.conf.5: Likewise. * modules/pam_access/pam_access.8: Likewise. * modules/pam_cracklib/pam_cracklib.8: Likewise. * modules/pam_deny/pam_deny.8: Likewise. * modules/pam_echo/pam_echo.8: Likewise. * modules/pam_env/pam_env.8: Likewise. * modules/pam_env/pam_env.conf.5: Likewise. * modules/pam_exec/pam_exec.8: Likewise. * modules/pam_filter/pam_filter.8: Likewise. * modules/pam_ftp/pam_ftp.8: Likewise. * modules/pam_group/group.conf.5: Likewise. * modules/pam_group/pam_group.8: Likewise. * modules/pam_issue/pam_issue.8: Likewise. * modules/pam_lastlog/pam_lastlog.8: Likewise. * modules/pam_mkhomedir/pam_mkhomedir.8: Likewise. * modules/pam_succeed_if/pam_succeed_if.8: Likewise. * modules/pam_umask/pam_umask.8: Likewise. * modules/pam_unix/pam_unix_acct.c (pam_sm_acct_mgmt): Use dngettext if available [#1427738]. * configure.in: Check for dngettext [#1427738]. * po/*.po: Update to dngettext usage. * modules/pam_listfile/Makefile.am: Include Make.xml.rules. * modules/pam_listfile/pam_listfile.8.xml: New. * modules/pam_listfile/pam_listfile.8: New, generated from xml file. * modules/pam_listfile/README.xml: New. * modules/pam_listfile/README: Regenerated from xml file.
Diffstat (limited to 'modules/pam_listfile')
-rw-r--r--modules/pam_listfile/Makefile.am12
-rw-r--r--modules/pam_listfile/README121
-rw-r--r--modules/pam_listfile/README.xml41
-rw-r--r--modules/pam_listfile/pam_listfile.8164
-rw-r--r--modules/pam_listfile/pam_listfile.8.xml282
5 files changed, 594 insertions, 26 deletions
diff --git a/modules/pam_listfile/Makefile.am b/modules/pam_listfile/Makefile.am
index 114e2f3c..5eb5c75c 100644
--- a/modules/pam_listfile/Makefile.am
+++ b/modules/pam_listfile/Makefile.am
@@ -4,7 +4,10 @@
CLEANFILES = *~
-EXTRA_DIST = README tst-pam_listfile
+EXTRA_DIST = README $(MANS) $(XMLS) tst-pam_listfile
+
+man_MANS = pam_listfile.8
+XMLS = README.xml pam_listfile.8.xml
TESTS = tst-pam_listfile
@@ -19,3 +22,10 @@ if HAVE_VERSIONING
endif
securelib_LTLIBRARIES = pam_listfile.la
+
+if ENABLE_REGENERATE_MAN
+noinst_DATA = README
+README: pam_listfile.8.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
+
diff --git a/modules/pam_listfile/README b/modules/pam_listfile/README
index b65e7dbb..4bfabe2d 100644
--- a/modules/pam_listfile/README
+++ b/modules/pam_listfile/README
@@ -1,25 +1,96 @@
-SUMMARY:
- pam_listfile:
- Checks a specified item against a list in a file.
- Options:
- * item=[tty|user|rhost|ruser|group|shell]
- * sense=[allow|deny] (action to take if found in file,
- if the item is NOT found in the file, then
- the opposite action is requested)
- * file=/the/file/to/get/the/list/from
- * onerr=[succeed|fail] (if something weird happens
- such as unable to open the file, what to do?)
- * apply=[user|@group]
- restrict the user class for which the restriction
- apply. Note that with item=[user|ruser|group] this
- does not make sense, but for item=[tty|rhost|shell]
- it have a meaning. (Cristian Gafton)
-
- Also checks to make sure that the list file is a plain
- file and not world writable.
-
- - Elliot Lee <sopwith@redhat.com>, Red Hat Software.
- v0.9 August 16, 1996.
-
-BUGS:
- Bugs?
+pam_listfile — deny or allow services based on an arbitrary file.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DESCRIPTION
+
+pam_listfile is a PAM module which provides a way to deny or allow services
+based on an arbitrary file.
+
+The module gets the item of the type specified -- user specifies the username,
+PAM_USER; tty specifies the name of the terminal over which the request has
+been made, PAM_TTY; rhost specifies the name of the remote host (if any) from
+which the request was made, PAM_RHOST; and ruser specifies the name of the
+remote user (if available) who made the request, PAM_RUSER -- and looks for an
+instance of that item in the file=filename. filename contains one line per item
+listed. If the item is found, then if sense=allow, PAM_SUCCESS is returned,
+causing the authorization request to succeed; else if sense=deny, PAM_AUTH_ERR
+is returned, causing the authorization request to fail.
+
+If an error is encountered (for instance, if filename does not exist, or a
+poorly-constructed argument is encountered), then if onerr=succeed, PAM_SUCCESS
+is returned, otherwise if onerr=fail, PAM_AUTH_ERR or PAM_SERVICE_ERR (as
+appropriate) will be returned.
+
+An additional argument, apply=, can be used to restrict the application of the
+above to a specific user (apply=username) or a given group (apply=@groupname).
+This added restriction is only meaningful when used with the tty, rhost and
+shell items.
+
+Besides this last one, all arguments should be specified; do not count on any
+default behavior.
+
+No credentials are awarded by this module.
+
+OPTIONS
+
+item=[tty|user|rhost|ruser|group|shell]
+
+ What is listed in the file and should be checked for.
+
+sense=[allow|deny]
+
+ Action to take if found in file, if the item is NOT found in the file, then
+ the opposite action is requested.
+
+file=/path/filename
+
+ File containing one item per line. The file needs to be a plain file and
+ not world writeable.
+
+onerr=[succeed|fail]
+
+ What to do if something weird happens like being unable to open the file.
+
+apply=[user|@group]
+
+ Restrict the user class for which the restriction apply. Note that with
+ item=[user|ruser|group] this oes not make sense, but for item=[tty|rhost|
+ shell] it have a meaning.
+
+EXAMPLES
+
+Classic 'ftpusers' authentication can be implemented with this entry in /etc/
+pam.d/ftpd:
+
+#
+# deny ftp-access to users listed in the /etc/ftpusers file
+#
+auth required pam_listfile.so \
+ onerr=succeed item=user sense=deny file=/etc/ftpusers
+
+
+Note, users listed in /etc/ftpusers file are (counterintuitively) not allowed
+access to the ftp service.
+
+To allow login access only for certain users, you can use a /etc/pam.d/login
+entry like this:
+
+#
+# permit login to users listed in /etc/loginusers
+#
+auth required pam_listfile.so \
+ onerr=fail item=user sense=allow file=/etc/loginusers
+
+
+For this example to work, all users who are allowed to use the login service
+should be listed in the file /etc/loginusers. Unless you are explicitly trying
+to lock out root, make sure that when you do this, you leave a way for root to
+log in, either by listing root in /etc/loginusers, or by listing a user who is
+able to su to the root account.
+
+AUTHOR
+
+pam_listfile was written by Michael K. Johnson <johnsonm@redhat.com> and Elliot
+Lee <sopwith@cuc.edu>.
+
diff --git a/modules/pam_listfile/README.xml b/modules/pam_listfile/README.xml
new file mode 100644
index 00000000..d851aef3
--- /dev/null
+++ b/modules/pam_listfile/README.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.docbook.org/xml/4.3/docbookx.dtd"
+[
+<!--
+<!ENTITY pamaccess SYSTEM "pam_listfile.8.xml">
+-->
+]>
+
+<article>
+
+ <articleinfo>
+
+ <title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_listfile.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_listfile-name"]/*)'/>
+ </title>
+
+ </articleinfo>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_listfile.8.xml" xpointer='xpointer(//refsect1[@id = "pam_listfile-description"]/*)'/>
+ </section>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_listfile.8.xml" xpointer='xpointer(//refsect1[@id = "pam_listfile-options"]/*)'/>
+ </section>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_listfile.8.xml" xpointer='xpointer(//refsect1[@id = "pam_listfile-examples"]/*)'/>
+ </section>
+
+ <section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_listfile.8.xml" xpointer='xpointer(//refsect1[@id = "pam_listfile-author"]/*)'/>
+ </section>
+
+</article>
diff --git a/modules/pam_listfile/pam_listfile.8 b/modules/pam_listfile/pam_listfile.8
new file mode 100644
index 00000000..826d337e
--- /dev/null
+++ b/modules/pam_listfile/pam_listfile.8
@@ -0,0 +1,164 @@
+.\" Title: pam_listfile
+.\" Author:
+.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
+.\" Date: 06/02/2006
+.\" Manual: Linux\-PAM Manual
+.\" Source: Linux\-PAM Manual
+.\"
+.TH "PAM_LISTFILE" "8" "06/02/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_listfile \- deny or allow services based on an arbitrary file.
+.SH "SYNOPSIS"
+.HP 16
+\fBpam_listfile.so\fR item=[tty|user|rhost|ruser|group|shell] sense=[allow|deny] file=\fI/path/filename\fR onerr=[succeed|fail] [apply=[\fIuser\fR|\fI@group\fR]]
+.SH "DESCRIPTION"
+.PP
+pam_listfile is a PAM module which provides a way to deny or allow services based on an arbitrary file.
+.PP
+The module gets the
+\fBitem\fR
+of the type specified \-\-
+\fIuser\fR
+specifies the username,
+\fIPAM_USER\fR; tty specifies the name of the terminal over which the request has been made,
+\fIPAM_TTY\fR; rhost specifies the name of the remote host (if any) from which the request was made,
+\fIPAM_RHOST\fR; and ruser specifies the name of the remote user (if available) who made the request,
+\fIPAM_RUSER\fR
+\-\- and looks for an instance of that item in the
+\fBfile=\fR\fB\fIfilename\fR\fR.
+\fIfilename\fR
+contains one line per item listed. If the item is found, then if
+\fBsense=\fR\fB\fIallow\fR\fR,
+\fIPAM_SUCCESS\fR
+is returned, causing the authorization request to succeed; else if
+\fBsense=\fR\fB\fIdeny\fR\fR,
+\fIPAM_AUTH_ERR\fR
+is returned, causing the authorization request to fail.
+.PP
+If an error is encountered (for instance, if
+\fIfilename\fR
+does not exist, or a poorly\-constructed argument is encountered), then if
+\fIonerr=succeed\fR,
+\fIPAM_SUCCESS\fR
+is returned, otherwise if
+\fIonerr=fail\fR,
+\fIPAM_AUTH_ERR\fR
+or
+\fIPAM_SERVICE_ERR\fR
+(as appropriate) will be returned.
+.PP
+An additional argument,
+\fBapply=\fR, can be used to restrict the application of the above to a specific user (\fBapply=\fR\fB\fIusername\fR\fR) or a given group (\fBapply=\fR\fB\fI@groupname\fR\fR). This added restriction is only meaningful when used with the
+\fItty\fR,
+\fIrhost\fR
+and
+\fIshell\fR
+items.
+.PP
+Besides this last one, all arguments should be specified; do not count on any default behavior.
+.PP
+No credentials are awarded by this module.
+.SH "OPTIONS"
+.PP
+.TP 3n
+\fBitem=[tty|user|rhost|ruser|group|shell]\fR
+What is listed in the file and should be checked for.
+.TP 3n
+\fBsense=[allow|deny]\fR
+Action to take if found in file, if the item is NOT found in the file, then the opposite action is requested.
+.TP 3n
+\fBfile=\fR\fB\fI/path/filename\fR\fR
+File containing one item per line. The file needs to be a plain file and not world writeable.
+.TP 3n
+\fBonerr=[succeed|fail]\fR
+What to do if something weird happens like being unable to open the file.
+.TP 3n
+\fBapply=[\fR\fB\fIuser\fR\fR\fB|\fR\fB\fI@group\fR\fR\fB]\fR
+Restrict the user class for which the restriction apply. Note that with
+\fBitem=[user|ruser|group]\fR
+this oes not make sense, but for
+\fBitem=[tty|rhost|shell]\fR
+it have a meaning.
+.SH "MODULE SERVICES PROVIDED"
+.PP
+The services
+\fBauth\fR,
+\fBaccount\fR,
+\fBpassword\fR
+and
+\fBsession\fR
+are supported.
+.SH "RETURN VALUES"
+.PP
+.TP 3n
+PAM_AUTH_ERR
+Authentication failure.
+.TP 3n
+PAM_BUF_ERR
+Memory buffer error.
+.TP 3n
+PAM_IGNORE
+The rule does not apply to the
+\fBapply\fR
+option.
+.TP 3n
+PAM_SERVICE_ERR
+Error in service module.
+.TP 3n
+PAM_SUCCESS
+Success.
+.SH "EXAMPLES"
+.PP
+Classic 'ftpusers' authentication can be implemented with this entry in
+\fI/etc/pam.d/ftpd\fR:
+.sp
+.RS 3n
+.nf
+#
+# deny ftp\-access to users listed in the /etc/ftpusers file
+#
+auth required pam_listfile.so \\
+ onerr=succeed item=user sense=deny file=/etc/ftpusers
+
+.fi
+.RE
+.sp
+Note, users listed in
+\fI/etc/ftpusers\fR
+file are (counterintuitively)
+\fInot\fR
+allowed access to the ftp service.
+.PP
+To allow login access only for certain users, you can use a
+\fI/etc/pam.d/login\fR
+entry like this:
+.sp
+.RS 3n
+.nf
+#
+# permit login to users listed in /etc/loginusers
+#
+auth required pam_listfile.so \\
+ onerr=fail item=user sense=allow file=/etc/loginusers
+
+.fi
+.RE
+.sp
+For this example to work, all users who are allowed to use the login service should be listed in the file
+\fI/etc/loginusers\fR. Unless you are explicitly trying to lock out root, make sure that when you do this, you leave a way for root to log in, either by listing root in
+\fI/etc/loginusers\fR, or by listing a user who is able to
+\fIsu\fR
+to the root account.
+.SH "SEE ALSO"
+.PP
+
+\fBpam.conf\fR(5),
+\fBpam.d\fR(8),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
+pam_listfile was written by Michael K. Johnson <johnsonm@redhat.com> and Elliot Lee <sopwith@cuc.edu>.
diff --git a/modules/pam_listfile/pam_listfile.8.xml b/modules/pam_listfile/pam_listfile.8.xml
new file mode 100644
index 00000000..85489d3c
--- /dev/null
+++ b/modules/pam_listfile/pam_listfile.8.xml
@@ -0,0 +1,282 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="pam_listfile">
+
+ <refmeta>
+ <refentrytitle>pam_listfile</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_listfile-name">
+ <refname>pam_listfile</refname>
+ <refpurpose>deny or allow services based on an arbitrary file.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis id="pam_listfile-cmdsynopsis">
+ <command>pam_listfile.so</command>
+ <arg choice="plain">
+ item=[tty|user|rhost|ruser|group|shell]
+ </arg>
+ <arg choice="plain">
+ sense=[allow|deny]
+ </arg>
+ <arg choice="plain">
+ file=<replaceable>/path/filename</replaceable>
+ </arg>
+ <arg choice="plain">
+ onerr=[succeed|fail]
+ </arg>
+ <arg choice="opt">
+ apply=[<replaceable>user</replaceable>|<replaceable>@group</replaceable>]
+ </arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="pam_listfile-description">
+
+ <title>DESCRIPTION</title>
+
+ <para>
+ pam_listfile is a PAM module which provides a way to deny or
+ allow services based on an arbitrary file.
+ </para>
+ <para>
+ The module gets the <option>item</option> of the type specified --
+ <emphasis>user</emphasis> specifies the username,
+ <emphasis>PAM_USER</emphasis>; tty specifies the name of the terminal
+ over which the request has been made, <emphasis>PAM_TTY</emphasis>;
+ rhost specifies the name of the remote host (if any) from which the
+ request was made, <emphasis>PAM_RHOST</emphasis>; and ruser specifies
+ the name of the remote user (if available) who made the request,
+ <emphasis>PAM_RUSER</emphasis> -- and looks for an instance of that
+ item in the <option>file=<replaceable>filename</replaceable></option>.
+ <filename>filename</filename> contains one line per item listed. If
+ the item is found, then if
+ <option>sense=<replaceable>allow</replaceable></option>,
+ <emphasis>PAM_SUCCESS</emphasis> is returned, causing the authorization
+ request to succeed; else if
+ <option>sense=<replaceable>deny</replaceable></option>,
+ <emphasis>PAM_AUTH_ERR</emphasis> is returned, causing the authorization
+ request to fail.
+ </para>
+ <para>
+ If an error is encountered (for instance, if
+ <filename>filename</filename> does not exist, or a poorly-constructed
+ argument is encountered), then if <emphasis>onerr=succeed</emphasis>,
+ <emphasis>PAM_SUCCESS</emphasis> is returned, otherwise if
+ <emphasis>onerr=fail</emphasis>, <emphasis>PAM_AUTH_ERR</emphasis> or
+ <emphasis>PAM_SERVICE_ERR</emphasis> (as appropriate) will be returned.
+ </para>
+ <para>
+ An additional argument, <option>apply=</option>, can be used
+ to restrict the application of the above to a specific user
+ (<option>apply=<replaceable>username</replaceable></option>)
+ or a given group
+ (<option>apply=<replaceable>@groupname</replaceable></option>).
+ This added restriction is only meaningful when used with the
+ <emphasis>tty</emphasis>, <emphasis>rhost</emphasis> and
+ <emphasis>shell</emphasis> items.
+ </para>
+ <para>
+ Besides this last one, all arguments should be specified; do not
+ count on any default behavior.
+ </para>
+ <para>
+ No credentials are awarded by this module.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pam_listfile-options">
+
+ <title>OPTIONS</title>
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <option>item=[tty|user|rhost|ruser|group|shell]</option>
+ </term>
+ <listitem>
+ <para>
+ What is listed in the file and should be checked for.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>sense=[allow|deny]</option>
+ </term>
+ <listitem>
+ <para>
+ Action to take if found in file, if the item is NOT found in
+ the file, then the opposite action is requested.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>file=<replaceable>/path/filename</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ File containing one item per line. The file needs to be a plain
+ file and not world writeable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>onerr=[succeed|fail]</option>
+ </term>
+ <listitem>
+ <para>
+ What to do if something weird happens like being unable to open
+ the file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>apply=[<replaceable>user</replaceable>|<replaceable>@group</replaceable>]</option>
+ </term>
+ <listitem>
+ <para>
+ Restrict the user class for which the restriction apply. Note that
+ with <option>item=[user|ruser|group]</option> this oes not make sense,
+ but for <option>item=[tty|rhost|shell]</option> it have a meaning.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </refsect1>
+
+ <refsect1 id="pam_listfile-services">
+ <title>MODULE SERVICES PROVIDED</title>
+ <para>
+ The services <option>auth</option>, <option>account</option>,
+ <option>password</option> and <option>session</option> are supported.
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_listfile-return_values'>
+ <title>RETURN VALUES</title>
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term>PAM_AUTH_ERR</term>
+ <listitem>
+ <para>Authentication failure.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_IGNORE</term>
+ <listitem>
+ <para>
+ The rule does not apply to the <option>apply</option> option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_SERVICE_ERR</term>
+ <listitem>
+ <para>
+ Error in service module.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Success.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_listfile-examples'>
+ <title>EXAMPLES</title>
+ <para>
+ Classic 'ftpusers' authentication can be implemented with this entry
+ in <filename>/etc/pam.d/ftpd</filename>:
+ <programlisting>
+#
+# deny ftp-access to users listed in the /etc/ftpusers file
+#
+auth required pam_listfile.so \
+ onerr=succeed item=user sense=deny file=/etc/ftpusers
+ </programlisting>
+ Note, users listed in <filename>/etc/ftpusers</filename> file are
+ (counterintuitively) <emphasis>not</emphasis> allowed access to
+ the ftp service.
+ </para>
+ <para>
+ To allow login access only for certain users, you can use a
+ <filename>/etc/pam.d/login</filename> entry like this:
+ <programlisting>
+#
+# permit login to users listed in /etc/loginusers
+#
+auth required pam_listfile.so \
+ onerr=fail item=user sense=allow file=/etc/loginusers
+ </programlisting>
+ For this example to work, all users who are allowed to use the
+ login service should be listed in the file
+ <filename>/etc/loginusers</filename>. Unless you are explicitly
+ trying to lock out root, make sure that when you do this, you leave
+ a way for root to log in, either by listing root in
+ <filename>/etc/loginusers</filename>, or by listing a user who is
+ able to <emphasis>su</emphasis> to the root account.
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_listfile-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_listfile-author'>
+ <title>AUTHOR</title>
+ <para>
+ pam_listfile was written by Michael K. Johnson &lt;johnsonm@redhat.com&gt;
+ and Elliot Lee &lt;sopwith@cuc.edu&gt;.
+ </para>
+ </refsect1>
+
+</refentry>