diff -r 000000000000 -r 6f7a81934006 authenticate/checkvpw.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/authenticate/checkvpw.pod	Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,94 @@
+=head1 NAME
+
+checkvpw - check passwords for virtual and non-virtual users
+
+=head1 SYNOPSIS
+
+B<checkvpw> B<subprogram> [B<arguments...>]
+
+=head1 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
+F</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.
+
+F<checkvpw> must be run from either the F<tcp-env> program
+(part of the F<qmail>
+package) or from a suitable substitute, such as F<tcpserver>
+(part of the F<ucspi-tcp> package).
+These packages are used to determine to
+which address a remote host is connecting.
+F<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
+F<qmail-popup>.
+
+F<checkvpw> accepts a command line in the following format:
+
+	checkvpw [subprogram] [arguments...]
+
+If the authentication information is valid, the subprogram is run,
+otherwise F<checkvpw> returns an error to the program that invokes it.
+
+If the user name contains the character C<@>, the host name
+reported by F<tcp-env> is replaced by the string following the
+C<@>, and the user name is replaced by the string preceding the
+C<@>.
+If the local host name reported by F<tcp-env> matches one of those
+in F</var/qmail/control/virtualdomains>, F<checkvpw> prepends the
+I<prepend> string associated with the host name to the given user
+name.
+Wildcards in F<virtualdomains> are permitted and are handled in the
+same way F<qmail> handles them (see L<qmail-send>).
+For example, if the line C<.bar.com:bar> appears in the virtual hosts
+file, it matches C<one.two.bar.com> but not C<bar.com>.
+
+If the user name resulting from the above step appears in the system
+password file (typically F</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 C<name-ext> where C<name> does appear in the password
+file, the user is treated as a "virtual" user and authenticated with the
+information from a file named F<passwd> in the user's home directory.
+If this authentication succeeds, the mail directory is set to the
+subdirectory F<users/ext/> in the user's home directory, where
+C<ext> is from the above step.
+
+F<checkvpw> also does some rewriting on the arguments of the
+subprogram.
+Any argument matching the string "C<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 F<qmail-popup> and
+F<qmail-pop3d> from inetd by placing the following line in the
+F</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/
+
+=head1 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.
+
+=head1 ENVIRONMENT
+
+F<checkvpw> requires that C<TCPLOCALHOST> be set to the host name of
+the local address of the connection.
+
+=head1 SEE ALSO
+
+vdeliver(1)
+
+=head1 AUTHOR
+
+Bruce Guenter <F<bruceg@em.ca>>.
+