pam_listfile(8) — Linux manual page


PAM_LISTFILE(8)             Linux-PAM Manual             PAM_LISTFILE(8)

NAME         top

       pam_listfile - deny or allow services based on an arbitrary file

SYNOPSIS         top item=[tty|user|rhost|ruser|group|shell]
                       sense=[allow|deny] file=/path/filename
                       onerr=[succeed|fail] [apply=[user|@group]]

DESCRIPTION         top

       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

       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         top

           What is listed in the file and should be checked for.

           Action to take if found in file, if the item is NOT found in
           the file, then the opposite action is requested.

           File containing one item per line. The file needs to be a
           plain file and not world writable.

           What to do if something weird happens like being unable to
           open the file.

           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.

           Do not treat service refusals or missing list files as errors
           that need to be logged.


       All module types (auth, account, password and session) are

RETURN VALUES         top

           Authentication failure.

           Memory buffer error.

           The rule does not apply to the apply option.

           Error in service module.


EXAMPLES         top

       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 \
                   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 \
                   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.

SEE ALSO         top

       pam.conf(5), pam.d(5), pam(8)

AUTHOR         top

       pam_listfile was written by Michael K. Johnson
       <> and Elliot Lee <>.

COLOPHON         top

       This page is part of the linux-pam (Pluggable Authentication
       Modules for Linux) project.  Information about the project can be
       found at ⟨⟩.  If you have a bug report
       for this manual page, see ⟨//⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨⟩ on 2023-12-22.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-12-18.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Linux-PAM Manual               12/22/2023                PAM_LISTFILE(8)