| 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* to 'PIDFILE'. 'PIDFILE' may |
| 59 | be `-`, in which case the string "`.pid`" is appended to the |
| 60 | 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) |