diff -r 000000000000 -r 6f7a81934006 authenticate/vauthenticate.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/authenticate/vauthenticate.pod	Wed Jan 16 22:39:43 2008 +0100
@@ -0,0 +1,75 @@
+=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>