doc/accesslog.doc

   1 accesslog(1)
   2 ============
   3
   4 NAME
   5 ----
   6 accesslog - Access logger for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *accesslog* [*-hFaeL*] [*-f* 'FORMAT'] [*-p* 'PIDFILE'] 'OUTFILE' 'CHILD' ['ARGS'...]
  11
  12 *accesslog* *-P* 'LOGFILE'
  13
  14 DESCRIPTION
  15 -----------
  16
  17 The *accesslog* handler starts a single child handler which it passes
  18 all requests it receives, but also logs information about every such
  19 request to 'OUTFILE'. As for the format of the log records, see the
  20 FORMAT section, below.
  21
  22 *accesslog* is a persistent handler, as defined in *ashd*(7), and the
  23 specified child handler must also be a persistent handler.
  24
  25 If 'OUTFILE' is `-`, log records will be written on standard
  26 output. Otherwise, the specified filename is opened in append mode and
  27 kept open for as long as *accesslog* runs. SIGHUP can be sent to
  28 *accesslog* in order to get it to reopen the log file, which can be
  29 useful e.g. for log rotation.
  30
  31 If the child handler exits, *accesslog* exits as well.
  32
  33 Normally, *accesslog* locks the logfile using *fcntl*(2) to ensure
  34 that only one process writes to a logfile at any time. The *-L* switch
  35 can be used to override that behavior to let several processes share a
  36 logfile, or to use logfiles that cannot be locked for some reason.
  37
  38 OPTIONS
  39 -------
  40
  41 *-h*::
  42
  43         Print a brief help message to standard output and exit.
  44
  45 *-F*::
  46
  47         Do not flush the log file buffers for each log record. (This
  48         refers to the internal buffers, not the filesystem buffers.)
  49
  50 *-f* 'FORMAT'::
  51
  52         Use the specified 'FORMAT' string instead of the default log
  53         record format. See the FORMAT section, below, for a
  54         description of the 'FORMAT' string. See also the *-e* option.
  55
  56 *-p* 'PIDFILE'::
  57
  58         Write the PID of the *accesslog* process to
  59         'PIDFILE'. 'PIDFILE' may be `-`, in which case the string
  60         "`.pid`" is appended to the log file name and used instead.
  61
  62 *-a*::
  63
  64         Try to emulate the Apache "combined" log format as closely as
  65         possible. Currently, the remote user, identd user, status code
  66         and number of sent bytes in Apache's combined format are
  67         replaced with dashes. Effectively, the following format string
  68         is used:
  69
  70 --------
  71 %A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" %c %o "%R" "%G"
  72 --------
  73
  74 *-e*::
  75
  76         Make extended log data available. This option makes
  77         *accesslog* run in a different mode where it looks at not only
  78         the request, but also the (entire) response, which requires
  79         quite a bit more CPU time per request. However, some log items
  80         are only available in this mode; these have been marked as
  81         such under the FORMAT section, below.
  82
  83 *-L*::
  84
  85         Do not attempt to lock the logfile. Note that this switch
  86         conflicts with the use of the *-P* option.
  87
  88 *-P* 'LOGFILE'::
  89
  90         Makes *accesslog* fetch the PID of the process currently
  91         holding the lock on 'LOGFILE', write that to standard output,
  92         and then exit. No further command-line arguments are
  93         processed. This option is useful for sending SIGHUP to
  94         accesslog when rotating logfiles without having to use a PID
  95         file.
  96
  97 FORMAT
  98 ------
  99
 100 The log record format is specified with the *-f* option described
 101 above. The format string is used as a template and certain fields are
 102 expanded. Characters in the format string not matching such fields are
 103 output as they are. A field is specified as a percent sign, followed
 104 by an optional argument enclosed in braces, followed by a single
 105 character specifying the item to log.
 106
 107 By default, the following format string is used:
 108
 109 --------
 110 %{%Y-%m-%d %H:%M:%S}t %m %u %A "%G"
 111 --------
 112
 113 The following log items are currently specified:
 114
 115 *%{*'HEADER'*}h*::
 116
 117         Expands into the HTTP header named by 'HEADER'. If the
 118         specified header does not exist in the request, *%h* expands
 119         into a dash.
 120
 121 *%u*::
 122
 123         Expands into the entire raw URL part of the request.
 124
 125 *%U*::
 126
 127         Expands into the raw URL part of the request, with any query
 128         string removed if present.
 129
 130 *%m*::
 131
 132         Expands into the HTTP method.
 133
 134 *%v*::
 135
 136         Expands into the HTTP version string.
 137
 138 *%r*::
 139
 140         Expands into the current rest string.
 141
 142 *%t*::
 143
 144         Expands into the current time, in RFC822 format, unless there
 145         is an argument present, in which case the argument is used as
 146         a format string to *strftime*(3). The time is expressed in the
 147         local timezone.
 148
 149 *%T*::
 150
 151         As for *%t*, but UTC time is used instead.
 152
 153 *%s*::
 154
 155         Expands into the non-integral fraction of the second of the
 156         current time, expressed in microseconds and padded with zeroes
 157         to 6 digits. For example, *%{%H:%M:%S}t.%s* can be used to log
 158         fractional time.
 159
 160 *%A*::
 161
 162         Expands into the `X-Ash-Address` header.
 163
 164 *%H*::
 165
 166         Expands into the `Host` header.
 167
 168 *%R*::
 169
 170         Expands into the `Referer` header.
 171
 172 *%G*::
 173
 174         Expands into the `User-Agent` header.
 175
 176 The following log items are only available when running in extended
 177 mode, requested by the *-e* option, as described above. If unavailable
 178 due to not running in extended mode, each of the log items below will
 179 instead expand into a dash.
 180
 181 *%c*::
 182
 183         Expands into the HTTP status code of the response.
 184
 185 *%i*::
 186
 187         Expands into the number of bytes sent by the client as a
 188         request-body. HTTP headers are not counted.
 189
 190 *%o*::
 191
 192         Expands into the number of bytes sent back by the handler, to
 193         the client, as the response-body. HTTP headers are not
 194         counted, and neither are overhead as part of any required
 195         transfer-encoding, such as chunking.
 196
 197 *%d*::
 198
 199         Expands into the time it took for the handler to complete the
 200         response, expressed as seconds with 6 decimals precision.
 201
 202 In any expanded field, any "unsafe" characters are escaped. Currently,
 203 this means that double-quotes and backslashes are prepended with a
 204 backslash, newlines and tabs are expressed as, respectively, `\n` and
 205 `\t`, and any other byte less than 32 or greater than 127 is expressed
 206 as `\xAA`, where `AA` is the hexadecimal representation of the byte.
 207
 208 SIGNALS
 209 -------
 210
 211 SIGHUP::
 212
 213         Reopen the log file by name. If the log file name cannot be
 214         re-opened, the old log file stream continues in use.
 215
 216 AUTHOR
 217 ------
 218 Fredrik Tolf <fredrik@dolda2000.com>
 219
 220 SEE ALSO
 221 --------
 222 *ashd*(7)