path: root/doc/httpauthd.conf.5

.\" 
.\" Copyright (c) 2004, Nate Nielsen
.\" 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.
.\"     * The names of contributors to this software may not 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.
.\" 
.\"
.\" CONTRIBUTORS
.\"  Nate Nielsen <nielsen@memberwebs.com>
.\"
.Dd April, 2004
.Dt httpauthd.conf 5
.Os httpauth 
.Sh NAME
.Nm httpauthd.conf
.Nd the configuration file for 
.Xr httpauthd 8
.Sh DESCRIPTION
.Xr httpauthd 8
reads it's configuration from this file when starting up. It contains global
settings followed by the various authentication methods and their settings.
.Sh SYNTAX
The settings are specified one per line. The setting name comes first 
followed by a colon, and the value for that setting. Authentication method 
sections are prefixed with a '[method]' on a line of it's own. 
.Pp
Lines beginning with a # mark are comments. An example:
.Bd -literal -offset indent
# Sample Configuration File
Socket: 0.0.0.0:8020
AuthTypes: Basic Digest

[Simple]
Alias: MyAuth
PasswordFile: /srv/passwd.file
.Ed
.Sh AUTHENTICATION METHODS
Methods are the various ways 
.Xr httpauthd
can authenticate a user. A method will use either LDAP, a file or some 
other means to determine if a user is valid. The methods currently 
implemented are:
.Bl -hang
.It LDAP 
Authenticate against an LDAP server.
.It MYSQL 
Authenticate against a MYSQL database
.It PGSQL 
Authenticate against a PostgreSQL database.
.It Simple 
Authenticate against a password file. For info on creating this file see 
.Xr mkha1 8
.El
.Pp
A method block in the configuration file needs to contain one of the 
above method names as the header for it's section (ie: [LDAP]). It 
can be given another name by specifying an 
.Em Alias
for it. 
.Pp
This allows for the creation of various configurations with purpose 
specific names. These names are used by callers of
.Xr httpauthd 8
to identify how to authenticate a given HTTP connection.
.Pp
Aliases are created by putting a colon and a name after the section type, 
like this:
.Bd -literal -offset indent
[Simple:MyName]
.Ed
.Sh GLOBAL OPTIONS
These options affect httpauthd as a whole. They should be placed before the 
beginning of the first authentication method section. In addition certain
options can be placed in this section which affect all the authentication
methods. These are outlined under the 
.Em METHOD OPTIONS 
heading further below.
.Bl -hang 
.It Cd Socket
This is where httpauthd listens for connections. It can either be a unix
type socket by specifying a file path (eg: /var/run/ha.sock), a port number 
(eg: 8030) or a IP address with optional port number (eg: 192.168.2.38:8200). 
If you specify an IP address without a port, 
.Em 8020
will be used.
.Pp
[ Default: 
.Em /var/run/httpauthd.sock
]
.It Cd MaxThreads
This equals the amount of authentication connections that 
.Xr httpauthd 8 
will be able to have open at once.
.Pp
[ Default: 
.Em 32
]
.El

.Sh METHOD OPTIONS
These options change settings in how the various methods handle authentication.
When they appear after a method section, they only affect that method. Most of 
them can also appear in the inital section of the configuration file in which
case they're used as defaults.
.Bl -hang
.It Cd Alias
Change the name of the current authentication method. This is necessary when
you're using a certain method twice (eg: LDAP) with different settings. This
option can only be used in a method section.
.It Cd AuthTypes
The allowed HTTP authentication types, separated by spaces. Any combination of: 
.Ar Basic Digest 
.Pp
[ Default:
.Ar Basic Digest 
]
.It Cd CacheMax
The maximum amount of successful authentication requests a method can cache.
.Pp
[ Default:
.Em 1024
]
.It Cd CacheTimeout
The length of time in seconds that a successful authentication remains cached. 
How this exactly works depends on the method it applies to. 
.Pp
[ Default:
.Em 900
]
.It Cd DigestIgnoreNC
When set to 
.Em True
allows the NC value in 
.Em Digest
authentication to be incorrect. This opens up various replay attacks.
.Pp
[ Default:
.Em False
]
.It Cd DigestIgnoreURI
When set to 
.Em True
allows the URI value in
.Em Digest
authentication to be mismatched with the URI requested. This opens up 
a variety of replay attacks, but may be necessary in some cases.
.Pp
[ Default:
.Em False
]
.It Cd Realm
The realm used in 
.Em Basic
and 
.Em Digest
authentication. 
.Pp
[ Default:
.Em (none)
]
.El
.Sh SIMPLE METHOD OPTIONS
These are settings for the 
.Em Simple
authentication method. This method authenticates against password hashes in a file.
.Bl -hang
.It Cd PasswordFile
The path of the file that contains the password hashes. This file can be in either
the format created by 
.Xr htpasswd 1
or 
.Xr htdigest 1
(tools that come with apache). You can also use the 
.Xr mkha1 8
tool that comes with httpauth.
.Pp
[ Required ]
.El
.Sh LDAP METHOD OPTIONS
Settings for the 
.Em LDAP
authentication method. This method authenticates users against an LDAP server.
.Bl -hang
.It Cd LDAPBase
The base DN to use in the search for a user. This only applies when no 
LDAPDNMap is specified. 
.Pp
[ Required when 
.Em LDAPDNMap 
is missing ]
.It Cd LDAPDNMap
Specifies the DN for a user name. The
.Em %u
and 
.Em %r 
flags can be used in the DN, which will substitute the user and realm
respectively. 
.Pp
[ Optional ]
.It Cd LDAPDoBind
When performing Basic authentication, 
.Xr httpauthd
can try to bind to the LDAP server as the user in question. This 
allows authentication even when no access to cleartext passwords
is available. Note that this does not apply to Digest authentication.
.Pp
[ Default: 
.Em True
]
.It Cd LDAPFilter
The LDAP filter to use when querying the server. The
.Em %u
and 
.Em %r 
flags can be used in the filter, which will substitute the user and realm
respectively. When used without a
.Em LDAPDNMap
then this is used to identify the LDAP entry for the user. In this case care 
should be taken that the filter only returns one record. 
.Pp
[ Required when 
.Em LDAPDNMap 
is missing ]
.It Cd LDAPHA1Attr
A HA1 is a special kind of digest containing the user name, realm and 
password. This can be used in place of cleartext passwords when doing
Digest authentication. This setting specifies the attribute on the 
LDAP server that the hash can be found in. Use the 
.Xr mkha1 8
tool for creating HA1 hashes.
.Pp
.Xr httpauthd 8
can perform both Basic and Digest authentication against this attribute.
Note that the realm however is stored in the hash and must match the 
realm being sent to the client in the 
.Em Realm
setting.
.Pp
[ Optional ]
.It Cd LDAPMax
The maximum amount of connections to make to the LDAP server. 
.Pp
[ Default:
.Em 10
]
.It Cd LDAPPasswsord
The password to use with 
.Em LDAPUser
.Pp
[ Optional ]
.It Cd LDAPPwAttr
The name of the attribute on the LDAP server that contains the user's 
password. This can be for Basic authentication (when 
.Em LDAPDoBind
is off) or Digest authentication. When used with Digest Auth (and no 
.Em LDAPHA1Attr
is specified) it needs to contain a cleartext password. 
.Pp
[ Default: 
.Em userPassword
]
.It Cd LDAPScope
When searching the LDAP for a user (ie: 
.Em LDAPDNMap
is not specified) this is the scope for the search. Specify one of the
following:
.Ar sub base one
.Pp
[ Default:
.Em sub
]
.It Cd LDAPServers
The host names or IP addresses of the LDAP servers to authenticate against. 
Separated by spaces. More than one can be specified for failover capability.
.Pp
[ Required ]
.It Cd LDAPTimeout
The timeout for searches on the LDAP server (in seconds).
.Pp
[ Default:
.Em 30
]
.It Cd LDAPUser
When specified 
.Xr httpauthd
will bind as this user after connecting to the LDAP server. This is useful
in the case where anonymous users can't perform LDAP searches, for example.
.Pp
[ Optional ]
.El
.Sh MYSQL AND PGSQL METHOD OPTIONS
Here are the options for the MYSQL and PGSQL handlers. 
.Bl -hang
.It Cd DBDatabase
The database on the DB server to connect to. 
.Pp
[ Required ]
.It Cd DBHA1Column
The name of the column in 
.Ar DBQuery 
that contains the HA1 for the user. A HA1 
is a special kind of digest containing the user name, realm and password. 
This can be used in place of cleartext passwords when doing Digest 
authentication. Use the 
.Xr mkha1 8
tool for creating HA1 hashes.
.Pp
[ Optional ]
.It Cd DBMax
The maximum number of connections to make to the database server.
.Pp
[ Default: 
.Em 10
]
.It Cd DBPassword
The password for the 
.Ar DBUser
option.
.Pp
[ Optional ]
.It Cd DBPort
When connecting to the server via TCP this option specifies the port 
to connect on. 
.Pp
[ Default: DB server's default port ]
.It Cd DBPWColumn
The name of the column in 
.Ar DBQuery 
that contains the password. 
.Pp
[ Default: First Column ]
.It Cd DBPWType
The type of password stored in the database. The options are:
.Ar clear crypt md5 sha1
.Pp
[ Default: 
.Em clear 
]
.It Cd DBQuery
The query to execute when authenticating a user. The
.Em %u
and 
.Em %r 
flags can be used in the query, which will substitute the user and realm
respectively. This should be a 'SELECT' type query or a query that returns
data. 
.Pp
[ Required ]
.It Cd DBServer
The address to connect to the database at. It can either be a IP address,
host name, or unix type socket. If this option is not specified then the
default connection (see MYSQL or PGSQL docs) will be used.
.Pp
[ Optional ]
.It Cd DBTimeout
Time in seconds to wait for a connection to the DB server.
.Pp
[ Default:
.Em 30
]
.It Cd DBUser
The user to connect to the database as. 
.Pp
[ Default: DB's default user ]
.El
.Sh SEE ALSO
.Xr httpauthd 8
.Sh AUTHOR
.An Nate Nielsen Aq nielsen@memberwebs.com