CHECKPASSWORD-PAM(8)            Authentication            CHECKPASSWORD-PAM(8)



NAME
       checkpassword-pam - PAM-based checkpassword compatible authentication

SYNOPSIS
       checkpassword-pam [-s PAM-SERVICE] [-e|--noenv] -- prog args...

       checkpassword-pam --help

       checkpassword-pam --version

       Additional debugging options (see below):
                   [--debug] [--stdout]

       Additional rarely used options (see below):
                   [-H|--no-chdir-home]



DESCRIPTION
       checkpassword-pam  uses PAM to authenticate the remote user with check-
       password protocol.


       checkpassword-style programs are usually run by network server programs
       that wish to authenticate remote user.


       checkpassword-pam  uses PAM service name specified by PAM_SERVICE envi-
       ronment variable, or by the -s or --service command-line option.


       After successful authentication, if --noenv option  is  not  specified,
       checkpassword-pam  sets  up supplementary groups of authenticated user,
       its gid, its uid, and its working directory  (those  values  are  taken
       from the system user database).


       Normally, checkpassword-pam switches to user home directory.   If --no-
       chdir-home or -H option is  specified,  this  step  is  skipped.   This
       option  is  useful when you have automounted home directories, but mail
       is delivered to a central location.


       Finally, checkpassword-pam executes prog with args as its arguments.


       -- is used as usual to separate the checkpassword-pam own options  from
       prog options.


       checkpassword-pam  logs  authentication  failures  (or  all actions, if
       --debug option is used) to syslog (or to stdout, if --stdout option  is
       used).


ENVIRONMENT VARIABLES
       PAM_SERVICE
              checkpassword-pam uses contents of PAM_SERVICE environment vari-
              able to specify the PAM service name.  This could  be  overriden
              by -s option, see above.


       After  successful  authentication,  checkpassword-pam  sets environment
       variable  USER.   Then  it  consults  system  user  database   (usually
       /etc/passwd).  If an entry is found for the authenticated user, it sets
       environment variables HOME, and SHELL to appropriate  values,  switches
       to proper uid and gid, and sets up supplementary groups.

       If --noenv option is specified, this step is skipped, the variables are
       left alone, and no uid/gid switch occurs.  This is needed when you have
       virtual users which are not listed in your /etc/passwd, and you need to
       only do authentication.  Setting up process environment in this case is
       handled by some other application like setuidgid.



DEBUGGING
       You  can turn on debugging using the --debug option.  checkpassword-pam
       starts to log all of its actions and the results of  those  actions  to
       syslog  (or  to  stdout,  based  on  the  state of --stdout option, see
       above).

       There is a way to manually trace how  the  checkpassword-pam  authenti-
       cates: use the shell redirection and the --stdout option.  In this case
       checkpassword-pam reads checkpassword protocol  data  from  stdin,  and
       logs actions to stdout.  You can trace the authentication for the given
       user and password with the following command-line (usually as root):


       # echo -e "username\0password\0timestamp\0" \
         | checkpassword-pam -s SERVICE \
           --debug --stdout -- /usr/bin/id 3<&0


       It will trace the PAM authentication process for the user username with
       password  password,  and run the id program, which will report the user
       and groups checkpassword-pam switched to.


       The idea of this method is courtesy of Mark Delany <markd-at-mira.net>.


BUGS
       If  you've  found  a bug in checkpasswd-pam, please report it to check-
       passwd-pam-devel@lists.sourceforge.net


SEE ALSO
       http://checkpasswd-pam.sourceforge.net/

       http://cr.yp.to/checkpwd.html

       "PAM Administrator's Guide" for your operating system.


LEGACY
       There are alternate older checkpassword-pam packages  available.   They
       are  derived  from  original  DJB's checkpassword code, and usually are
       less administrator-friendly than this  version.   You  can  tell  those
       packages  apart  by  looking  at  their version number: it is less than
       0.95.


AUTHOR
       This version of checkpassword-pam was written from  scratch  by  Alexey
       Mahotkin <alexm@hsys.msk.ru>

       checkpassword interface was designed by Daniel J. Bernstein.



GNU/Linux                         06 Oct 2005             CHECKPASSWORD-PAM(8)