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