doc: Describe the new behavior of accesslog.

[ashd.git] / doc / accesslog.doc

diff --git a/doc/accesslog.doc b/doc/accesslog.doc
index 0ae7653..2baf508 100644 (file)
--- a/doc/accesslog.doc
+++ b/doc/accesslog.doc
@@ -7,7 +7,9 @@ accesslog - Access logger for ashd(7)
 
 SYNOPSIS
 --------
-*accesslog* [*-hFa*] [*-f* 'FORMAT'] 'OUTFILE' 'CHILD' ['ARGS'...]
+*accesslog* [*-hFaeL*] [*-f* 'FORMAT'] [*-p* 'PIDFILE'] 'OUTFILE' 'CHILD' ['ARGS'...]
+
+*accesslog* *-P* 'LOGFILE'
 
 DESCRIPTION
 -----------
@@ -28,6 +30,11 @@ useful e.g. for log rotation.
 
 If the child handler exits, *accesslog* exits as well.
 
+Normally, *accesslog* locks the logfile using *fcntl*(2) to ensure
+that only one process writes to a logfile at any time. The *-L* switch
+can be used to override that behavior to let several processes share a
+logfile, or to use logfiles that cannot be locked for some reason.
+
 OPTIONS
 -------
 
@@ -44,7 +51,13 @@ OPTIONS
 
        Use the specified 'FORMAT' string instead of the default log
        record format. See the FORMAT section, below, for a
-       description of the 'FORMAT' string.
+       description of the 'FORMAT' string. See also the *-e* option.
+
+*-p* 'PIDFILE'::
+
+       Write the PID of the *accesslog* process to
+       'PIDFILE'. 'PIDFILE' may be `-`, in which case the string
+       "`.pid`" is appended to the log file name and used instead.
 
 *-a*::
 
@@ -55,9 +68,32 @@ OPTIONS
        is used:
 
 --------
-%A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" - - "%R" "%G"
+%A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" %c %o "%R" "%G"
 --------
 
+*-e*::
+
+       Make extended log data available. This option makes
+       *accesslog* run in a different mode where it looks at not only
+       the request, but also the (entire) response, which requires
+       quite a bit more CPU time per request. However, some log items
+       are only available in this mode; these have been marked as
+       such under the FORMAT section, below.
+
+*-L*::
+
+       Do not attempt to lock the logfile. Note that this switch
+       conflicts with the use of the *-P* option.
+
+*-P* 'LOGFILE'::
+
+       Makes *accesslog* fetch the PID of the process currently
+       holding the lock on 'LOGFILE', write that to standard output,
+       and then exit. No further command-line arguments are
+       processed. This option is useful for sending SIGHUP to
+       accesslog when rotating logfiles without having to use a PID
+       file.
+
 FORMAT
 ------
 
@@ -137,6 +173,32 @@ The following log items are currently specified:
 
        Expands into the `User-Agent` header.
 
+The following log items are only available when running in extended
+mode, requested by the *-e* option, as described above. If unavailable
+due to not running in extended mode, each of the log items below will
+instead expand into a dash.
+
+*%c*::
+
+       Expands into the HTTP status code of the response.
+
+*%i*::
+
+       Expands into the number of bytes sent by the client as a
+       request-body. HTTP headers are not counted.
+
+*%o*::
+
+       Expands into the number of bytes sent back by the handler, to
+       the client, as the response-body. HTTP headers are not
+       counted, and neither are overhead as part of any required
+       transfer-encoding, such as chunking.
+
+*%d*::
+
+       Expands into the time it took for the handler to complete the
+       response, expressed as seconds with 6 decimals precision.
+
 In any expanded field, any "unsafe" characters are escaped. Currently,
 this means that double-quotes and backslashes are prepended with a
 backslash, newlines and tabs are expressed as, respectively, `\n` and