psendfile: Fixed missing include.
[ashd.git] / doc / htextauth.doc
CommitLineData
d185ffb9
FT
1htextauth(1)
2============
3
4NAME
5----
6htextauth - HTTP Basic authenticator for ashd(7)
7
8SYNOPSIS
9--------
10*htextauth* [*-hCs*] [*-r* 'REALM'] 'AUTHCMD' ['ARGS'...] `--` 'CHILD' ['ARGS'...]
11
12DESCRIPTION
13-----------
14
15The *htextauth* handler starts a single child handler which it passes
16all requests it receives, assuming they pass an authentication
17test. *htextauth* will request HTTP Basic credentials from the client,
18and pass such credentials to an external program in order to verify
19them. The authentication program will be called every time a new user
20needs to be authenticated. See the AUTHENTICATION section, below, for
21the calling convention used for the authentication program.
22
23*htextauth* is a persistent handler, as defined in *ashd*(7), and the
24specified child handler must also be a persistent handler.
25
26By default, *htextauth* will cache successfully verified credentials,
27so that the authentication program does not have to be called for each
28and every request. Cached credentials are cleared from the cache when
29they have not been used for over 30 minutes.
30
19d4a41e
FT
31When authentication succeeds, *htextauth* removes the HTTP
32`Authorization` header from the request before passing the request on
33to the child handler, and adds the `X-Ash-Remote-User` header in its
34place, containing the name of the authenticated user.
35
d185ffb9
FT
36If the child handler exits, *htextauth* exits as well.
37
38OPTIONS
39-------
40
41*-h*::
42
43 Print a brief help message to standard output and exit.
44
45*-C*::
46
47 Do not cache credentials.
48
49*-s*::
50
51 Require that all requests are made over HTTPS.
52
53*-r* 'REALM'::
54
55 Specify 'REALM' as the authentication realm when requesting
56 credentials from the client.
57
58AUTHENTICATION
59--------------
60
61When a previously unseen user needs to be authenticated, *htextauth*
62will fork and execute the 'AUTHCMD' program, with any arguments that
63follow. *htextauth* will pass two lines of text to the authentication
64program's standard input: the given user name on the first line, and
65the password on the second. The credentials are checked in advance so
66that they do not contain any control characters (below ASCII 32).
67
68If the authentication program successfully verifies the credentials
69and wishes to grant access to the client, it needs to exit
70successfully; that is, with exit status 0. Any other exit (including
71being killed by a signal) is taken by *htextauth* as a failure.
72
73The authentication program can specify a reason for any failure by
74writing such on standard output. If the program exits unsuccessfully,
75*htextauth* will include any such message in the error page sent to
76the client.
77
78Note that *htextauth* will wait for the authentication program to exit
79and not process any other requests until then.
80
ea4e6725
FT
81FILES
82-----
83The file `etc/extauth/vhtpasswd` in the *ashd* source distribution is
84a simple authenticator program (written in Python) that can be used
85with *htextauth*, which verifies the given credentials against a
86simple database of users with encrypted passwords. It can be used as
87is, or as a simple example of how to produce authenticator
88programs. The accompanying `mkhtpasswd` program can be used to
89maintain the password database.
90
d185ffb9
FT
91AUTHOR
92------
93Fredrik Tolf <fredrik@dolda2000.com>
94
95SEE ALSO
96--------
d3ef283f 97*ashd*(7), RFC 2617