lib: Use abort() instead of exit() when smalloc fails.
[ashd.git] / doc / accesslog.doc
... / ...
CommitLineData
1accesslog(1)
2============
3
4NAME
5----
6accesslog - Access logger for ashd(7)
7
8SYNOPSIS
9--------
10*accesslog* [*-hFaeL*] [*-f* 'FORMAT'] [*-p* 'PIDFILE'] 'OUTFILE' 'CHILD' ['ARGS'...]
11
12*accesslog* *-P* 'LOGFILE'
13
14DESCRIPTION
15-----------
16
17The *accesslog* handler starts a single child handler which it passes
18all requests it receives, but also logs information about every such
19request to 'OUTFILE'. As for the format of the log records, see the
20FORMAT section, below.
21
22*accesslog* is a persistent handler, as defined in *ashd*(7), and the
23specified child handler must also be a persistent handler.
24
25If 'OUTFILE' is `-`, log records will be written on standard
26output. Otherwise, the specified filename is opened in append mode and
27kept 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
29useful e.g. for log rotation.
30
31If the child handler exits, *accesslog* exits as well.
32
33Normally, *accesslog* locks the logfile using *fcntl*(2) to ensure
34that only one process writes to a logfile at any time. The *-L* switch
35can be used to override that behavior to let several processes share a
36logfile, or to use logfiles that cannot be locked for some reason.
37
38OPTIONS
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. See also the *-e* option.
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" %c %o "%R" "%G"
72--------
73
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
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
97FORMAT
98------
99
100The log record format is specified with the *-f* option described
101above. The format string is used as a template and certain fields are
102expanded. Characters in the format string not matching such fields are
103output as they are. A field is specified as a percent sign, followed
104by an optional argument enclosed in braces, followed by a single
105character specifying the item to log.
106
107By default, the following format string is used:
108
109--------
110%{%Y-%m-%d %H:%M:%S}t %m %u %A "%G"
111--------
112
113The 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
176The following log items are only available when running in extended
177mode, requested by the *-e* option, as described above. If unavailable
178due to not running in extended mode, each of the log items below will
179instead 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
202In any expanded field, any "unsafe" characters are escaped. Currently,
203this means that double-quotes and backslashes are prepended with a
204backslash, newlines and tabs are expressed as, respectively, `\n` and
205`\t`, and any other byte less than 32 or greater than 127 is expressed
206as `\xAA`, where `AA` is the hexadecimal representation of the byte.
207
208SIGNALS
209-------
210
211SIGHUP::
212
213 Reopen the log file by name. If the log file name cannot be
214 re-opened, the old log file stream continues in use.
215
216AUTHOR
217------
218Fredrik Tolf <fredrik@dolda2000.com>
219
220SEE ALSO
221--------
222*ashd*(7)