Additional debugging options (see below):
Additional rarely used options (see below):
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 environment 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).
Before invoking prog, checkpassword-pam sets environment variables USER, HOME, and SHELL to appropriate values. If --noenv option is specified, this step is skipped and the variables are left alone. 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 is handled by some other application like setuidgid.
There is a way to manually trace how the checkpassword-pam authenticates: 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>.
"PAM Administrator's Guide" for your operating system.
checkpassword interface was designed by Daniel J. Bernstein.