- Added documentation

- Fixed bugs
- Added support for dns to sock_any

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