=head1 NAME

vauthenticate - Authenticate a virtual user

=head1 SYNOPSIS

B<vauthenticate>

=head1 DESCRIPTION

F<vauthenticate> reads a domain name, user name, and pass phrase from
standard input, and authenticates the virtual user.  If authentication
is successful, it prints out information about the virtual user on
stdout

The domain name, user name, and pass phrase are passed to
F<vauthenticate> on standard input each seperated by a NUL byte.

The output consists of a series of lines containing an identifier, an
equal sign, and the data for that identifier, terminated by a newline.
The identifiers are:

=over 4

=item UID

The base user's numerical user ID.

=item GID

The base user's numerical group ID.

=item USER

The base user's name.

=item HOME

The base user's home directory.

=item MAILDIR

The virtual user's mailbox directory, relative to C<HOME>.

=item VUSER

The virtual user's name.

=back

=head1 OPTIONS

None

=head1 RETURN VALUE

Returns 0 if authentication succeeds, and non-zero otherwise.

=head1 SEE ALSO

vmailmgr(7)

=head1 CAVEATS

Although the output from F<vauthenticate> appears to be suitable for
using as shell input, care must be taken to escape characters that
would cause the shell to misbehave, such as semicolons.

=head1 RESTRICTIONS

This program will not authenticate non-virtual users.

=head1 AUTHOR

Bruce Guenter <bruceg@em.ca>