                          Authentication Documentation
                          ----------------------------

routers.cgi will optionally use additional user authentication to grant
users different rights of access.  You can enable this in the routers2.conf
file with the auth-required directive.

If you have authentication enabled in your web server, then routes.cgi will
recognise this as being authoritative.  Otherwise, you will be prompted for
a login from the CGI script itself (if you have auth-required enabled).

auth-required can be set to YES, NO or OPTIONAL.  In the case of OPTIONAL, then
if you have not already authenticated, you will get the 'default' level of
access.  If set to YES then you have no access until you have logged in.

When you have logged in, then routers.cgi will process the [user-xxx] section
of the file (if your username is xxx).  This can override defaults set in the
[routers.cgi] section, and allows you to grant access to different files and
directories, or archive rights, on a per-user basis.

If a user attempts to log in (or is forced to) then their username/password
will be authenticated by all methods defined in routers2.conf.  All are
regarded as being authoritative.  The login sets a cookie that expires after
a defined interval, and is refreshed every time the page refreshes.

LDAP authentication can check several contexts, with several attributes.  It
can only check a single server, but will try LDAP and/or LDAPS if available.
It will use LDAPS in preference.  In order to use LDAP authentication, you
must install the Net::LDAP; for LDAPS you also need Net::LDAPS, which in turn 
requires OpenSSL, Net::SSLeay, and IO::Socket::SSL

Before you enable authentication, make sure you have managed to get routers.cgi
working without it.

