Commit | Line | Data |
---|---|---|
0bb6f3d4 FT |
1 | accesslog(1) |
2 | ============ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | accesslog - Access logger for ashd(7) | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
3d500f7f | 10 | *accesslog* [*-hFaeL*] [*-f* 'FORMAT'] [*-p* 'PIDFILE'] 'OUTFILE' 'CHILD' ['ARGS'...] |
602135b0 | 11 | |
ca170d77 | 12 | *accesslog* *-P* 'LOGFILE' |
0bb6f3d4 FT |
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 | ||
ca170d77 FT |
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 | ||
0bb6f3d4 FT |
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 | |
3d500f7f | 54 | description of the 'FORMAT' string. See also the *-e* option. |
0bb6f3d4 | 55 | |
472abd3c FT |
56 | *-p* 'PIDFILE':: |
57 | ||
fda48525 FT |
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. | |
472abd3c | 61 | |
0bb6f3d4 FT |
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 | -------- | |
3d500f7f | 71 | %A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" %c %o "%R" "%G" |
0bb6f3d4 FT |
72 | -------- |
73 | ||
3d500f7f FT |
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 | ||
ca170d77 FT |
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 | ||
0bb6f3d4 FT |
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 | ||
3d500f7f FT |
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 | ||
5a723273 FT |
202 | *%{*'HEADER'*}p*:: |
203 | ||
204 | Expands into the HTTP response header named by 'HEADER'. If | |
205 | the specified header does not exist in the request, *%p* | |
206 | expands into a dash. | |
207 | ||
208 | *%{*'HEADER'*}P*:: | |
209 | ||
210 | Similar to *%p*, except that 'HEADER' is prepended with | |
211 | `X-Ash-`, for simple convenience. | |
212 | ||
0bb6f3d4 FT |
213 | In any expanded field, any "unsafe" characters are escaped. Currently, |
214 | this means that double-quotes and backslashes are prepended with a | |
215 | backslash, newlines and tabs are expressed as, respectively, `\n` and | |
216 | `\t`, and any other byte less than 32 or greater than 127 is expressed | |
217 | as `\xAA`, where `AA` is the hexadecimal representation of the byte. | |
218 | ||
219 | SIGNALS | |
220 | ------- | |
221 | ||
222 | SIGHUP:: | |
223 | ||
224 | Reopen the log file by name. If the log file name cannot be | |
225 | re-opened, the old log file stream continues in use. | |
226 | ||
227 | AUTHOR | |
228 | ------ | |
229 | Fredrik Tolf <fredrik@dolda2000.com> | |
230 | ||
231 | SEE ALSO | |
232 | -------- | |
233 | *ashd*(7) |