diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/httpauth.conf.5 | 82 | ||||
| -rw-r--r-- | doc/httpauthd.8 | 45 | ||||
| -rw-r--r-- | doc/httpauthd.conf.5 | 316 | ||||
| -rw-r--r-- | doc/httpauthd.conf.sample | 34 |
5 files changed, 399 insertions, 82 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..56ca28e --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,4 @@ + +man_MANS = httpauthd.8 httpauthd.conf.5 + +EXTRA_DIST = protocol.txt httpauthd.conf.sample ${man_MANS} diff --git a/doc/httpauth.conf.5 b/doc/httpauth.conf.5 deleted file mode 100644 index fd26c7b..0000000 --- a/doc/httpauth.conf.5 +++ /dev/null @@ -1,82 +0,0 @@ -.Dd April, 2004 -.Dt HTTPAUTH.CONF 5 -.Os httpauth -.Sh NAME -.Nm httpauth.conf -.Nd the configuration file for -.Em httpauthd -.Sh DESCRIPTION -The XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx -.Nm -scripting language is a regular expression language used for fine grained, -buffer based search and replace. It is not limited to lines. A full description -of what -.Nm -is capable of is outside the scope of this document. -.Pp -.Ar script -is a text or compiled -.Nm -script. For details see the language documentation that came along with the distribution. -.Pp -When used with the -.Fl f -argument -.Nm -replaces files in place. Otherwise it reads from -.Ar infile -and writes to -.Ar outfile -\&. If either infile or outfile are missing or are equal to a dash -.Sq Li - -, then rep processes -.Em stdin -or -.Em stdout -respectively. -.Sh OPTIONS -The options are as follows: -.Bl -tag -width Fl -.It Fl b -Backup files where replacements have occurred. The backup files have an -.Sq x_r -extension appended to their filename. -.It Fl i -Prompt for confirmation before each replacement. -.It Fl p -Only output replaced text. Can be used as a rudimentary parser. -.It Fl q -Supress status messages. Only errors will be sent to stderr. -.It Fl z -Set the replacement buffer size to -.Ar buffsize . -This speeds up execution as regular expressions only have to act on a small -portion of the whole file at once. However the largest match will be limited to -roughly -.Ar buffsize -, so use this option with care. The script loops over each buffer until no more -matches are found within it. Care is taken to overlap the buffers as much as -possible to ensure that any match smaller than -.Ar buffsize -can be matched. -.Sh NOTE -The -.Nm -command uses -.Xr getopt 3 -to parse it's arguments, which allows it to accept -the -.Sq Li -- -option which will stop processing of flag options at that point. This allows -the processing of files with names that begin with a dash -.Pq Sq - . -.Sh BUGS -When reading from -.Em stdin -you must specify a buffer size. -.Sh SEE ALSO -.Xr repc 1 , -.Xr rlib 3 , -.Xr pcre 3 -.Sh AUTHOR -.An Nate Nielsen Aq nielsen@memberwebs.com
\ No newline at end of file diff --git a/doc/httpauthd.8 b/doc/httpauthd.8 new file mode 100644 index 0000000..afdf753 --- /dev/null +++ b/doc/httpauthd.8 @@ -0,0 +1,45 @@ +.Dd April, 2004 +.Dt httpauthd 8 +.Os httpauth +.Sh NAME +.Nm httpauthd +.Nd a daemon which performs HTTP authentication +.Sh DESCRIPTION +.Xr httpauthd 8 +is a daemon that performs HTTP authentication for a variety of HTTP servers. +Callers send it HTTP headers, which it then processes and returns responses +destined for the client. +.Pp +It listens on unix or IP sockets, allowing for centralization of HTTP +authentication and an extra layer security if necessary. +.Pp +.Nm httpauthd +can perform a variety of different types of authentication, and is built +in an extensible manner so more can be added in the future. +.Pp +.Bl -bullet -compact +.It +Basic and Digest authentication against a file. +.It +Basic and Digest authentication against an LDAP server. +.It +Basic and NTLM authentication against a SMB domain server. +.El +.Sh OPTIONS +The options are as follows: +.Bl -tag -width Fl +.It Fl d +Don't detach from the console and run as a daemon. In addition the +.Ar level +argument specifies what level of error messages to display. 0 being +the least, 4 the most. +.It Fl f +Specify an alternate location for the configuration file. +.It Fl X +Process stdin and stdout instead of listening for connections on a +socket. Useful for troubleshooting problems. +.El +.Sh SEE ALSO +.Xr httpauth.conf 8 +.Sh AUTHOR +.An Nate Nielsen Aq nielsen@memberwebs.com 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 diff --git a/doc/httpauthd.conf.sample b/doc/httpauthd.conf.sample new file mode 100644 index 0000000..f5e1e87 --- /dev/null +++ b/doc/httpauthd.conf.sample @@ -0,0 +1,34 @@ + +# Sample HTTPAUTH configuration file + +# Listen on a TCP port +Socket: 0.0.0.0 + +# Only perform Digest authentication +AuthTypes: Digest + +# ---------------------------------------------------- +# This is the beginning of an Simple method section +[Simple] + +# Give the method a name +Alias: LocalUsers + +# The file +PasswordFile: /usr/data/localusers.pw + + + + +# ---------------------------------------------------- +# This is the beginning of an LDAP method section +[LDAP] + +# Give the method a name +Alias: AllUsers + +LDAPServers: ldap.test.com +LDAPDoBind: True +LDAPDNMap: cn=%u,dc=test,dc=com +LDAPFilter: (objectClass=person) + |