=head1	NAME

useraud - User authentication daemon

=head1	SYNOPSIS

  useraud [<options>] [<configfile>]

=head1	DESCRIPTION

The program runs as a daemon. It listens on a UNIX domain socket
for incoming connections form useraudi processes (started by inetd/xinetd)
and processes the requests.

=head1	OPTIONS

=over	6

=item	B<-d>

enables debug mode (runs the program in foreground and writes debug
information).

=back

=head1	RETURN VALUE

The program is a standing daemon and does not return a value.

=head1	CONFIGURATION FILE

=head2	GENERAL FILE STRUCTURE

The configuration file consists of one ``options'' section and one
or multiple ``backend'' sections.

=head2	OPTIONS SECTION

The options section is introduced by ``[options]'' standing alone
in a line.
The lines in the section contain key/value pairs, key and value are
separated by ``=''.
The following keys can be used:

=over	6

=item	B<run as user => I<username>

chooses a user account used to run the useraud daemon. This entry is optional.
On some systems for some backends useraud must run as ``root'' to have
access to the encrypted passwords.

=item	B<run as group => I<groupname>

specifies a group used to run the useraud daemon. This entry is optional.
The user account used to run the HTTP daemon should be a member of this group
if you plan to use useraud with web applications.

=item	B<socket => I<path>

sets the file name of the UNIX domain socket for communication between
useraudi and useraud. I recommend to use a path below the
``/var/run'' directory.

=item	B<database =>I<type>B<:>I<path>

sets the database type and the file name for the database. The type can
be one of ``bdb'' (Berkeley DB), ``gdbm'' (Gnu database manager)
or ``ndbm'' (NDBM on some commercial UNIX systems). Make sure you have
compiled the dktools project with support for the database type you choose.

=item	B<cleanup interval => I<seconds>

specifies the minimum amount of time (default: 2 days) between
automatic database cleanups.

=item	B<hash type => I<list>

contains a comma-separated list of hash types useraud is allowed to use.
The list may contain ``crypt'', ``md5'', ``ripemd-160'', ``sha-1'',
``sha-224'', ``sha-256'', ``sha-384'', and ``sha-512''.

You should allow at least one of the SHA-... algorithms and the algorithm
used by the user database backend to hash passwords.

=item	B<report no such user => I<boolean>

decides which response to send for non-existing user names: either
``no such user'' for ``yes'' or a faked challenge or ``wrong password''
response for ``no''.

=item	B<local user name test => I<boolean>

controls whether or not local applications connecting over a UNIX domain
socket are allowed to verify user names using the 110 or 111 request.

=item	B<net user name test => I<boolean>

controls whether or not remote applications connecting over a network
socket to useraudi are allowed to verify user names using the 110
or 111 request. Make sure to use a TCP wrapper (i.e. tcpd) to restrict
the remote computers able to connect to useraudi.

=item	B<cookie ttl => I<seconds>

sets the maximum lifetime of a cookie.

=item	B<cookie size => I<bytes>

sets the cookie length in characters.

=item	B<random seed file => I<path>

specifies the file name to store the PRNG seed.
Access to this file must be restricted, only the user account running
useraud must have access to this file.

=item	B<log file => I<path>

sets the name of the log file.

=item	B<log file level => I<string>

sets the minimum priority level required to log a message to the log
file, may be one of ``debug'', ``progress'', ``info'', ``notice'',
``warning'', ``error'', or ``fatal''.

=item	B<syslog level => I<string>

sets the minimum priority level required to log a message to the syslog
system.

=back

=head2	BACKEND SECTION

A backend section is introduced by ``[backend I<type>]'' standing alone
in a line. At this time there is only support for the ``system''
backend type.

The lines in the section contain key/value pairs, key and value are
separated by ``=''.
The following keys can be used:

=over	6

=item	B<password hash type => I<string>

sets the hash type used to encrypt the password, one from ``crypt'', ``md5'',
``ripemd-160'', ``sha-1'', ``sha-224'', ``sha-256'', ``sha-384'',
or ``sha-512''.

=item	B<exclude user => I<username-list>

lists users to exclude for this backend. Usernames in the list are
separated by spaces or tabulators. This line is allowed multiple times
in a backend section.

=item	B<add attribute => I<major> I<minor> I<string>

adds the listed attribute to the details of authenticated users.
The I<major> and I<minor> numbers are integer values. Ths string
is passed ``as is''.

If you configure multiple backends you can use this feature to find which
backend was used to authenticate the user.

=item	B<map attribute => I<major> I<minor> I<string>

maps one attribute from a user database record into the details
for authenticated users. The I<string> can be a database column name,
LDAP attribute name..., the appropriate value is mapped into the response.

This feature is not implemented for the ``system'' backend type.

=back

=head1	SEE ALSO

http://dktools.sourceforge.net/useraud.html

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2010, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


