doc/accesslog.doc

   1 accesslog(1)
   2 ============
   3
   4 NAME
   5 ----
   6 accesslog - Access logger for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *accesslog* [*-hFaL*] [*-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.
  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" - - "%R" "%G"
  72 --------
  73
  74 *-L*::
  75
  76         Do not attempt to lock the logfile. Note that this switch
  77         conflicts with the use of the *-P* option.
  78
  79 *-P* 'LOGFILE'::
  80
  81         Makes *accesslog* fetch the PID of the process currently
  82         holding the lock on 'LOGFILE', write that to standard output,
  83         and then exit. No further command-line arguments are
  84         processed. This option is useful for sending SIGHUP to
  85         accesslog when rotating logfiles without having to use a PID
  86         file.
  87
  88 FORMAT
  89 ------
  90
  91 The log record format is specified with the *-f* option described
  92 above. The format string is used as a template and certain fields are
  93 expanded. Characters in the format string not matching such fields are
  94 output as they are. A field is specified as a percent sign, followed
  95 by an optional argument enclosed in braces, followed by a single
  96 character specifying the item to log.
  97
  98 By default, the following format string is used:
  99
 100 --------
 101 %{%Y-%m-%d %H:%M:%S}t %m %u %A "%G"
 102 --------
 103
 104 The following log items are currently specified:
 105
 106 *%{*'HEADER'*}h*::
 107
 108         Expands into the HTTP header named by 'HEADER'. If the
 109         specified header does not exist in the request, *%h* expands
 110         into a dash.
 111
 112 *%u*::
 113
 114         Expands into the entire raw URL part of the request.
 115
 116 *%U*::
 117
 118         Expands into the raw URL part of the request, with any query
 119         string removed if present.
 120
 121 *%m*::
 122
 123         Expands into the HTTP method.
 124
 125 *%v*::
 126
 127         Expands into the HTTP version string.
 128
 129 *%r*::
 130
 131         Expands into the current rest string.
 132
 133 *%t*::
 134
 135         Expands into the current time, in RFC822 format, unless there
 136         is an argument present, in which case the argument is used as
 137         a format string to *strftime*(3). The time is expressed in the
 138         local timezone.
 139
 140 *%T*::
 141
 142         As for *%t*, but UTC time is used instead.
 143
 144 *%s*::
 145
 146         Expands into the non-integral fraction of the second of the
 147         current time, expressed in microseconds and padded with zeroes
 148         to 6 digits. For example, *%{%H:%M:%S}t.%s* can be used to log
 149         fractional time.
 150
 151 *%A*::
 152
 153         Expands into the `X-Ash-Address` header.
 154
 155 *%H*::
 156
 157         Expands into the `Host` header.
 158
 159 *%R*::
 160
 161         Expands into the `Referer` header.
 162
 163 *%G*::
 164
 165         Expands into the `User-Agent` header.
 166
 167 In any expanded field, any "unsafe" characters are escaped. Currently,
 168 this means that double-quotes and backslashes are prepended with a
 169 backslash, newlines and tabs are expressed as, respectively, `\n` and
 170 `\t`, and any other byte less than 32 or greater than 127 is expressed
 171 as `\xAA`, where `AA` is the hexadecimal representation of the byte.
 172
 173 SIGNALS
 174 -------
 175
 176 SIGHUP::
 177
 178         Reopen the log file by name. If the log file name cannot be
 179         re-opened, the old log file stream continues in use.
 180
 181 AUTHOR
 182 ------
 183 Fredrik Tolf <fredrik@dolda2000.com>
 184
 185 SEE ALSO
 186 --------
 187 *ashd*(7)