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