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