From: Fredrik Tolf Date: Thu, 7 Oct 2010 08:27:12 +0000 (+0200) Subject: doc: Added manpage for htextauth. X-Git-Tag: 0.3~5 X-Git-Url: http://git.dolda2000.com/gitweb/?a=commitdiff_plain;h=d185ffb9d36ed23e28b632b7a17a24e323343c6b;hp=fb9b10275276ae4110e76fda6c897a6f11b31b0d;p=ashd.git doc: Added manpage for htextauth. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 2278bfd..be4698e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,5 @@ -dist_man1_MANS = callcgi.1 dirplex.1 htparser.1 patplex.1 sendfile.1 userplex.1 htls.1 callscgi.1 accesslog.1 +dist_man1_MANS = callcgi.1 dirplex.1 htparser.1 patplex.1 sendfile.1 \ + userplex.1 htls.1 callscgi.1 accesslog.1 htextauth.1 dist_man7_MANS = ashd.7 %.7 %.1: %.doc diff --git a/doc/htextauth.doc b/doc/htextauth.doc new file mode 100644 index 0000000..fb32f56 --- /dev/null +++ b/doc/htextauth.doc @@ -0,0 +1,82 @@ +htextauth(1) +============ + +NAME +---- +htextauth - HTTP Basic authenticator for ashd(7) + +SYNOPSIS +-------- +*htextauth* [*-hCs*] [*-r* 'REALM'] 'AUTHCMD' ['ARGS'...] `--` 'CHILD' ['ARGS'...] + +DESCRIPTION +----------- + +The *htextauth* handler starts a single child handler which it passes +all requests it receives, assuming they pass an authentication +test. *htextauth* will request HTTP Basic credentials from the client, +and pass such credentials to an external program in order to verify +them. The authentication program will be called every time a new user +needs to be authenticated. See the AUTHENTICATION section, below, for +the calling convention used for the authentication program. + +*htextauth* is a persistent handler, as defined in *ashd*(7), and the +specified child handler must also be a persistent handler. + +By default, *htextauth* will cache successfully verified credentials, +so that the authentication program does not have to be called for each +and every request. Cached credentials are cleared from the cache when +they have not been used for over 30 minutes. + +If the child handler exits, *htextauth* exits as well. + +OPTIONS +------- + +*-h*:: + + Print a brief help message to standard output and exit. + +*-C*:: + + Do not cache credentials. + +*-s*:: + + Require that all requests are made over HTTPS. + +*-r* 'REALM':: + + Specify 'REALM' as the authentication realm when requesting + credentials from the client. + +AUTHENTICATION +-------------- + +When a previously unseen user needs to be authenticated, *htextauth* +will fork and execute the 'AUTHCMD' program, with any arguments that +follow. *htextauth* will pass two lines of text to the authentication +program's standard input: the given user name on the first line, and +the password on the second. The credentials are checked in advance so +that they do not contain any control characters (below ASCII 32). + +If the authentication program successfully verifies the credentials +and wishes to grant access to the client, it needs to exit +successfully; that is, with exit status 0. Any other exit (including +being killed by a signal) is taken by *htextauth* as a failure. + +The authentication program can specify a reason for any failure by +writing such on standard output. If the program exits unsuccessfully, +*htextauth* will include any such message in the error page sent to +the client. + +Note that *htextauth* will wait for the authentication program to exit +and not process any other requests until then. + +AUTHOR +------ +Fredrik Tolf + +SEE ALSO +-------- +*ashd*(7)