doc: Made an actual INSTALL file.
[ashd.git] / doc / accesslog.doc
CommitLineData
0bb6f3d4
FT
1accesslog(1)
2============
3
4NAME
5----
6accesslog - Access logger for ashd(7)
7
8SYNOPSIS
9--------
ca170d77 10*accesslog* [*-hFaL*] [*-f* 'FORMAT'] [*-p* 'PIDFILE'] 'OUTFILE' 'CHILD' ['ARGS'...]
602135b0 11
ca170d77 12*accesslog* *-P* 'LOGFILE'
0bb6f3d4
FT
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
ca170d77
FT
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
0bb6f3d4
FT
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.
55
472abd3c
FT
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
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--------
71%A - - [%{%d/%b/%Y:%H:%M:%S %z}t] "%m %u %v" - - "%R" "%G"
72--------
73
ca170d77
FT
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
0bb6f3d4
FT
88FORMAT
89------
90
91The log record format is specified with the *-f* option described
92above. The format string is used as a template and certain fields are
93expanded. Characters in the format string not matching such fields are
94output as they are. A field is specified as a percent sign, followed
95by an optional argument enclosed in braces, followed by a single
96character specifying the item to log.
97
98By default, the following format string is used:
99
100--------
101%{%Y-%m-%d %H:%M:%S}t %m %u %A "%G"
102--------
103
104The 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
167In any expanded field, any "unsafe" characters are escaped. Currently,
168this means that double-quotes and backslashes are prepended with a
169backslash, newlines and tabs are expressed as, respectively, `\n` and
170`\t`, and any other byte less than 32 or greater than 127 is expressed
171as `\xAA`, where `AA` is the hexadecimal representation of the byte.
172
173SIGNALS
174-------
175
176SIGHUP::
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
181AUTHOR
182------
183Fredrik Tolf <fredrik@dolda2000.com>
184
185SEE ALSO
186--------
187*ashd*(7)