checkvpw - check passwords for virtual and non-virtual users

# NAME

checkvpw - check passwords for virtual and non-virtual users

# SYNOPSIS

checkvpw subprogram [arguments...]

# DESCRIPTION

This program is a drop-in replacement for the standard checkpassword, written by D. J. Bernstein (djb@pobox.com). In the absence of virtual hosting (determined by the use of /var/qmail/control/virtualdomainss and IP aliases), it behaves identically to checkpassword. When virtual hosting is used, it permits logins from a unique set of users for each of the aliases.

checkvpw must be run from either the tcp-env program (part of the qmail package) or from a suitable substitute, such as tcpserver (part of the ucspi-tcp package). These packages are used to determine to which address a remote host is connecting. checkvpw must also be passed the checkpassword-compatible authentication data on file descriptor three. This can be accomplished by running it from a tool such as qmail-popup.

checkvpw accepts a command line in the following format:

    checkvpw [subprogram] [arguments...]

If the authentication information is valid, the subprogram is run, otherwise checkvpw returns an error to the program that invokes it.

If the user name contains the character `@`, the host name reported by tcp-env is replaced by the string following the `@`, and the user name is replaced by the string preceding the `@`. If the local host name reported by tcp-env matches one of those in /var/qmail/control/virtualdomains, checkvpw prepends the prepend string associated with the host name to the given user name. Wildcards in virtualdomains are permitted and are handled in the same way qmail handles them (see qmail-send). For example, if the line `.bar.com:bar` appears in the virtual hosts file, it matches `one.two.bar.com` but not `bar.com`.

If the user name resulting from the above step appears in the system password file (typically /etc/passwd), the user is treated as a local user and authenticated with the information from that file. If this authentication succeeds, the mail directory is set to the subdirectory named on the command line. If the user name does not appear in the system password file and is of the form `name-ext` where `name` does appear in the password file, the user is treated as a "virtual" user and authenticated with the information from a file named passwd in the user's home directory. If this authentication succeeds, the mail directory is set to the subdirectory users/ext/ in the user's home directory, where `ext` is from the above step.

checkvpw also does some rewriting on the arguments of the subprogram. Any argument matching the string "`maildir`" (ignoring case) is replaced with the full path of the mail directory, as determined by the steps above.

This program may be invoked in combination with qmail-popup and qmail-pop3d from inetd by placing the following line in the /etc/inetd.conf configuration file (all one line):

    pop-3 stream tcp nowait root /var/qmail/bin/tcp-env tcp-env -R /var/qmail/bin/qmail-popup <hostname> /usr/pkg/bin/checkvpw /var/qmail/bin/qmail-pop3d Maildir/

# RETURN VALUE

0 if the user is successfully authenticated, nonzero if any error occurred. Exit code 1 indicates that a bad password was given, 2 indicates that the program was used incorrectly, and 111 indicates a temporary failure.

# ENVIRONMENT

checkvpw requires that `TCPLOCALHOST` be set to the host name of the local address of the connection.

# SEE ALSO

vdeliver(1)

# AUTHOR

Bruce Guenter <bruce@untroubled.org>.