diff options
Diffstat (limited to 'doc/httpauthd.conf.5')
| -rw-r--r-- | doc/httpauthd.conf.5 | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/doc/httpauthd.conf.5 b/doc/httpauthd.conf.5 new file mode 100644 index 0000000..2e3c49e --- /dev/null +++ b/doc/httpauthd.conf.5 @@ -0,0 +1,316 @@ +.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 |