.\" .\" 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 .\" .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: .Ar Simple LDAP NTLM .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. .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 NTLM .Pp [ Default: .Ar Basic Digest NTLM ] .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 DigestDomains The .Em domains setting used with .Em Digest authentication. This allows you to specify one or more URIs which are in the same authentication space. The specified URIs are prefixes, i.e. the client will assume that all URIs "below" these are also protected by the same username/password. The URIs may be either absolute URIs (i.e. inluding a scheme, host, port, etc) or relative URIs. Separated by spaces. .Pp [ Default: .Em (none) ] .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). .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. .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 NTLM METHOD OPTIONS Settings for the .Em NTLM authentication method. This method authenticates users against NT domain server. .Bl -hang .It Cd NTLMBackup The backup domain server to authenticate against. Used when .Em NTLMServer is not available. .Pp [ Optional ] .It Cd NTLMDomain The domain which contains the users that will be authenticated. This is the NT domain, not the DNS domain. .Pp [ Required ] .It Cd NTLMServer The domain server to authenticate against. You should specify a name here not an IP address. .Pp [ Required ] .It Cd PendingMax The maximum amount of halfway authenticated NTLM connections allowed. This corresponds directly to the amount of concurrent connections made to .Em NTLMServer .Pp [ Default: .Em 16 ] .It Cd PendingTimeout The maximum time a halfway authenticated NTLM connection is allowed to remain that way (in seconds). .Pp [ Default: .Em 20 ] .El .Sh SEE ALSO .Xr httpauthd 8 .Sh AUTHOR .An Nate Nielsen Aq nielsen@memberwebs.com