lib: Clear the epoll event descriptor before use.
[ashd.git] / doc / accesslog.doc
CommitLineData
0bb6f3d4
FT
1accesslog(1)
2============
3
4NAME
5----
6accesslog - Access logger for ashd(7)
7
8SYNOPSIS
9--------
10*accesslog* [*-hFa*] [*-f* 'FORMAT'] 'OUTFILE' 'CHILD' ['ARGS'...]
11
12DESCRIPTION
13-----------
14
15The *accesslog* handler starts a single child handler which it passes
16all requests it receives, but also logs information about every such
17request to 'OUTFILE'. As for the format of the log records, see the
18FORMAT section, below.
19
20*accesslog* is a persistent handler, as defined in *ashd*(7), and the
21specified child handler must also be a persistent handler.
22
23If 'OUTFILE' is `-`, log records will be written on standard
24output. Otherwise, the specified filename is opened in append mode and
25kept open for as long as *accesslog* runs. SIGHUP can be sent to
26*accesslog* in order to get it to reopen the log file, which can be
27useful e.g. for log rotation.
28
29If the child handler exits, *accesslog* exits as well.
30
31OPTIONS
32-------
33
34*-h*::
35
36 Print a brief help message to standard output and exit.
37
38*-F*::
39
40 Do not flush the log file buffers for each log record. (This
41 refers to the internal buffers, not the filesystem buffers.)
42
43*-f* 'FORMAT'::
44
45 Use the specified 'FORMAT' string instead of the default log
46 record format. See the FORMAT section, below, for a
47 description of the 'FORMAT' string.
48
49*-a*::
50
51 Try to emulate the Apache "combined" log format as closely as
52 possible. Currently, the remote user, identd user, status code
53 and number of sent bytes in Apache's combined format are
54 replaced with dashes. Effectively, the following format string
55 is used:
56
57--------
58%A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" - - "%R" "%G"
59--------
60
61FORMAT
62------
63
64The log record format is specified with the *-f* option described
65above. The format string is used as a template and certain fields are
66expanded. Characters in the format string not matching such fields are
67output as they are. A field is specified as a percent sign, followed
68by an optional argument enclosed in braces, followed by a single
69character specifying the item to log.
70
71By default, the following format string is used:
72
73--------
74%{%Y-%m-%d %H:%M:%S}t %m %u %A "%G"
75--------
76
77The following log items are currently specified:
78
79*%{*'HEADER'*}h*::
80
81 Expands into the HTTP header named by 'HEADER'. If the
82 specified header does not exist in the request, *%h* expands
83 into a dash.
84
85*%u*::
86
87 Expands into the entire raw URL part of the request.
88
89*%U*::
90
91 Expands into the raw URL part of the request, with any query
92 string removed if present.
93
94*%m*::
95
96 Expands into the HTTP method.
97
98*%v*::
99
100 Expands into the HTTP version string.
101
102*%r*::
103
104 Expands into the current rest string.
105
106*%t*::
107
108 Expands into the current time, in RFC822 format, unless there
109 is an argument present, in which case the argument is used as
110 a format string to *strftime*(3). The time is expressed in the
111 local timezone.
112
113*%T*::
114
115 As for *%t*, but UTC time is used instead.
116
117*%s*::
118
119 Expands into the non-integral fraction of the second of the
120 current time, expressed in microseconds and padded with zeroes
121 to 6 digits. For example, *%{%H:%M:%S}t.%s* can be used to log
122 fractional time.
123
124*%A*::
125
126 Expands into the `X-Ash-Address` header.
127
128*%H*::
129
130 Expands into the `Host` header.
131
132*%R*::
133
134 Expands into the `Referer` header.
135
136*%G*::
137
138 Expands into the `User-Agent` header.
139
140In any expanded field, any "unsafe" characters are escaped. Currently,
141this means that double-quotes and backslashes are prepended with a
142backslash, newlines and tabs are expressed as, respectively, `\n` and
143`\t`, and any other byte less than 32 or greater than 127 is expressed
144as `\xAA`, where `AA` is the hexadecimal representation of the byte.
145
146SIGNALS
147-------
148
149SIGHUP::
150
151 Reopen the log file by name. If the log file name cannot be
152 re-opened, the old log file stream continues in use.
153
154AUTHOR
155------
156Fredrik Tolf <fredrik@dolda2000.com>
157
158SEE ALSO
159--------
160*ashd*(7)