Dolda2000 GitWeb / ashd.git / blame
| 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 | ||
| 19d4a41e FT |
31 | When authentication succeeds, *htextauth* removes the HTTP |
| 32 | `Authorization` header from the request before passing the request on | |
| 33 | to the child handler, and adds the `X-Ash-Remote-User` header in its | |
| 34 | place, containing the name of the authenticated user. | |
| 35 | ||
| d185ffb9 FT |
36 | If the child handler exits, *htextauth* exits as well. |
| 37 | ||
| 38 | OPTIONS | |
| 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 | ||
| 58 | AUTHENTICATION | |
| 59 | -------------- | |
| 60 | ||
| 61 | When a previously unseen user needs to be authenticated, *htextauth* | |
| 62 | will fork and execute the 'AUTHCMD' program, with any arguments that | |
| 63 | follow. *htextauth* will pass two lines of text to the authentication | |
| 64 | program's standard input: the given user name on the first line, and | |
| 65 | the password on the second. The credentials are checked in advance so | |
| 66 | that they do not contain any control characters (below ASCII 32). | |
| 67 | ||
| 68 | If the authentication program successfully verifies the credentials | |
| 69 | and wishes to grant access to the client, it needs to exit | |
| 70 | successfully; that is, with exit status 0. Any other exit (including | |
| 71 | being killed by a signal) is taken by *htextauth* as a failure. | |
| 72 | ||
| 73 | The authentication program can specify a reason for any failure by | |
| 74 | writing such on standard output. If the program exits unsuccessfully, | |
| 75 | *htextauth* will include any such message in the error page sent to | |
| 76 | the client. | |
| 77 | ||
| 78 | Note that *htextauth* will wait for the authentication program to exit | |
| 79 | and not process any other requests until then. | |
| 80 | ||
| 81 | AUTHOR | |
| 82 | ------ | |
| 83 | Fredrik Tolf <fredrik@dolda2000.com> | |
| 84 | ||
| 85 | SEE ALSO | |
| 86 | -------- | |
| d3ef283f | 87 | *ashd*(7), RFC 2617 |