checkvpw - check passwords for virtual and non-virtual users
checkvpw subprogram [arguments...]
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/bin/checkvpw /var/qmail/bin/qmail-pop3d Maildir/
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.
checkvpw requires that TCPLOCALHOST be set to the host name of
the local address of the connection.
vdeliver(1)
Bruce Guenter <bruceg@em.ca>.