doc/accesslog.doc

   1 accesslog(1)
   2 ============
   3
   4 NAME
   5 ----
   6 accesslog - Access logger for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *accesslog* [*-hFa*] [*-f* 'FORMAT'] [*-p* 'PIDFILE'] 'OUTFILE' 'CHILD' ['ARGS'...]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *accesslog* handler starts a single child handler which it passes
  16 all requests it receives, but also logs information about every such
  17 request to 'OUTFILE'. As for the format of the log records, see the
  18 FORMAT section, below.
  19
  20 *accesslog* is a persistent handler, as defined in *ashd*(7), and the
  21 specified child handler must also be a persistent handler.
  22
  23 If 'OUTFILE' is `-`, log records will be written on standard
  24 output. Otherwise, the specified filename is opened in append mode and
  25 kept open for as long as *accesslog* runs. SIGHUP can be sent to
  26 *accesslog* in order to get it to reopen the log file, which can be
  27 useful e.g. for log rotation.
  28
  29 If the child handler exits, *accesslog* exits as well.
  30
  31 OPTIONS
  32 -------
  33
  34 *-h*::
  35
  36         Print a brief help message to standard output and exit.
  37
  38 *-F*::
  39
  40         Do not flush the log file buffers for each log record. (This
  41         refers to the internal buffers, not the filesystem buffers.)
  42
  43 *-f* 'FORMAT'::
  44
  45         Use the specified 'FORMAT' string instead of the default log
  46         record format. See the FORMAT section, below, for a
  47         description of the 'FORMAT' string.
  48
  49 *-p* 'PIDFILE'::
  50
  51         Write the PID of the *accesslog* to 'PIDFILE'. 'PIDFILE' may
  52         be `-`, in which case the string "`.pid`" is appended to the
  53         log file name and used instead.
  54
  55 *-a*::
  56
  57         Try to emulate the Apache "combined" log format as closely as
  58         possible. Currently, the remote user, identd user, status code
  59         and number of sent bytes in Apache's combined format are
  60         replaced with dashes. Effectively, the following format string
  61         is used:
  62
  63 --------
  64 %A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" - - "%R" "%G"
  65 --------
  66
  67 FORMAT
  68 ------
  69
  70 The log record format is specified with the *-f* option described
  71 above. The format string is used as a template and certain fields are
  72 expanded. Characters in the format string not matching such fields are
  73 output as they are. A field is specified as a percent sign, followed
  74 by an optional argument enclosed in braces, followed by a single
  75 character specifying the item to log.
  76
  77 By default, the following format string is used:
  78
  79 --------
  80 %{%Y-%m-%d %H:%M:%S}t %m %u %A "%G"
  81 --------
  82
  83 The following log items are currently specified:
  84
  85 *%{*'HEADER'*}h*::
  86
  87         Expands into the HTTP header named by 'HEADER'. If the
  88         specified header does not exist in the request, *%h* expands
  89         into a dash.
  90
  91 *%u*::
  92
  93         Expands into the entire raw URL part of the request.
  94
  95 *%U*::
  96
  97         Expands into the raw URL part of the request, with any query
  98         string removed if present.
  99
 100 *%m*::
 101
 102         Expands into the HTTP method.
 103
 104 *%v*::
 105
 106         Expands into the HTTP version string.
 107
 108 *%r*::
 109
 110         Expands into the current rest string.
 111
 112 *%t*::
 113
 114         Expands into the current time, in RFC822 format, unless there
 115         is an argument present, in which case the argument is used as
 116         a format string to *strftime*(3). The time is expressed in the
 117         local timezone.
 118
 119 *%T*::
 120
 121         As for *%t*, but UTC time is used instead.
 122
 123 *%s*::
 124
 125         Expands into the non-integral fraction of the second of the
 126         current time, expressed in microseconds and padded with zeroes
 127         to 6 digits. For example, *%{%H:%M:%S}t.%s* can be used to log
 128         fractional time.
 129
 130 *%A*::
 131
 132         Expands into the `X-Ash-Address` header.
 133
 134 *%H*::
 135
 136         Expands into the `Host` header.
 137
 138 *%R*::
 139
 140         Expands into the `Referer` header.
 141
 142 *%G*::
 143
 144         Expands into the `User-Agent` header.
 145
 146 In any expanded field, any "unsafe" characters are escaped. Currently,
 147 this means that double-quotes and backslashes are prepended with a
 148 backslash, newlines and tabs are expressed as, respectively, `\n` and
 149 `\t`, and any other byte less than 32 or greater than 127 is expressed
 150 as `\xAA`, where `AA` is the hexadecimal representation of the byte.
 151
 152 SIGNALS
 153 -------
 154
 155 SIGHUP::
 156
 157         Reopen the log file by name. If the log file name cannot be
 158         re-opened, the old log file stream continues in use.
 159
 160 AUTHOR
 161 ------
 162 Fredrik Tolf <fredrik@dolda2000.com>
 163
 164 SEE ALSO
 165 --------
 166 *ashd*(7)