1 =head1 NAME

     2 

     3 checkvpw - check passwords for virtual and non-virtual users

     4 

     5 =head1 SYNOPSIS

     6 

     7 B<checkvpw> B<subprogram> [B<arguments...>]

     8 

     9 =head1 DESCRIPTION

    10 

    11 This program is a drop-in replacement for the standard checkpassword,

    12 written by D. J. Bernstein (djb@pobox.com).

    13 In the absence of virtual hosting (determined by the use of

    14 F</var/qmail/control/virtualdomainss> and IP aliases),

    15 it behaves identically to checkpassword.

    16 When virtual hosting is used, it permits logins from a unique set of

    17 users for each of the aliases.

    18 

    19 F<checkvpw> must be run from either the F<tcp-env> program

    20 (part of the F<qmail>

    21 package) or from a suitable substitute, such as F<tcpserver>

    22 (part of the F<ucspi-tcp> package).

    23 These packages are used to determine to

    24 which address a remote host is connecting.

    25 F<checkvpw> must also be passed the checkpassword-compatible

    26 authentication data on file descriptor three.

    27 This can be accomplished by running it from a tool such as

    28 F<qmail-popup>.

    29 

    30 F<checkvpw> accepts a command line in the following format:

    31 

    32 	checkvpw [subprogram] [arguments...]

    33 

    34 If the authentication information is valid, the subprogram is run,

    35 otherwise F<checkvpw> returns an error to the program that invokes it.

    36 

    37 If the user name contains the character C<@>, the host name

    38 reported by F<tcp-env> is replaced by the string following the

    39 C<@>, and the user name is replaced by the string preceding the

    40 C<@>.

    41 If the local host name reported by F<tcp-env> matches one of those

    42 in F</var/qmail/control/virtualdomains>, F<checkvpw> prepends the

    43 I<prepend> string associated with the host name to the given user

    44 name.

    45 Wildcards in F<virtualdomains> are permitted and are handled in the

    46 same way F<qmail> handles them (see L<qmail-send>).

    47 For example, if the line C<.bar.com:bar> appears in the virtual hosts

    48 file, it matches C<one.two.bar.com> but not C<bar.com>.

    49 

    50 If the user name resulting from the above step appears in the system

    51 password file (typically F</etc/passwd>), the user is treated as a

    52 local user and authenticated with the information from that file.

    53 If this authentication succeeds, the mail directory is set to the

    54 subdirectory named on the command line.

    55 If the user name does not appear in the system password file and is of

    56 the form C<name-ext> where C<name> does appear in the password

    57 file, the user is treated as a "virtual" user and authenticated with the

    58 information from a file named F<passwd> in the user's home directory.

    59 If this authentication succeeds, the mail directory is set to the

    60 subdirectory F<users/ext/> in the user's home directory, where

    61 C<ext> is from the above step.

    62 

    63 F<checkvpw> also does some rewriting on the arguments of the

    64 subprogram.

    65 Any argument matching the string "C<maildir>" (ignoring case) is

    66 replaced with the full path of the mail directory, as determined by the

    67 steps above.

    68 

    69 This program may be invoked in combination with F<qmail-popup> and

    70 F<qmail-pop3d> from inetd by placing the following line in the

    71 F</etc/inetd.conf> configuration file (all one line):

    72 

    73 	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/

    74 

    75 =head1 RETURN VALUE

    76 

    77 0 if the user is successfully authenticated, nonzero if any error

    78 occurred.  Exit code 1 indicates that a bad password was given, 2

    79 indicates that the program was used incorrectly, and 111 indicates

    80 a temporary failure.

    81 

    82 =head1 ENVIRONMENT

    83 

    84 F<checkvpw> requires that C<TCPLOCALHOST> be set to the host name of

    85 the local address of the connection.

    86 

    87 =head1 SEE ALSO

    88 

    89 vdeliver(1)

    90 

    91 =head1 AUTHOR

    92 

    93 Bruce Guenter <F<bruceg@em.ca>>.

    94