svlogd.8 (9573B)
1 .TH svlogd 8 2 .SH NAME 3 svlogd \- runit's service logging daemon 4 .SH SYNOPSIS 5 .B svlogd 6 [\-tttv] [\-r 7 .I c\fR] [\-R 8 .I xyz\fR] [\-l 9 .I len\fR] [\-b 10 .I buflen\fR] 11 .I logs 12 .SH DESCRIPTION 13 .I logs 14 consists of one or more arguments, each specifying a directory. 15 .P 16 .B svlogd 17 continuously reads log data from its standard input, optionally filters log 18 messages, and writes the data to one or more automatically rotated 19 .IR logs . 20 .P 21 Recent log files can automatically be processed by an arbitrary processor 22 program when they are rotated, and 23 .B svlogd 24 can be told to alert selected log messages to standard error, and through 25 udp. 26 .P 27 .B svlogd 28 runs until it sees end-of-file on standard input or is sent a TERM signal, 29 see below. 30 .SS LOG DIRECTORY 31 A log directory 32 .I log 33 contains some number of old log files, and the current log file 34 .IR current . 35 Old log files have a file name starting with 36 .I @ 37 followed by a precise timestamp (see the daemontools' 38 .B tai64n 39 program), indicating when 40 .I current 41 was rotated and renamed to this file. 42 .P 43 A log directory additionally contains the lock file 44 .IR lock , 45 maybe 46 .I state 47 and 48 .IR newstate , 49 and optionally the file 50 .IR config . 51 .B svlogd 52 creates necessary files if they don't exist. 53 .P 54 If 55 .B svlogd 56 has trouble opening a log directory, it prints a warning, and ignores this 57 log directory. 58 If 59 .B svlogd 60 is unable to open all log directories given at the command line, it exits 61 with an error. 62 This can happen on start-up or after receiving a HUP signal. 63 .SS LOG FILE ROTATION 64 .B svlogd 65 appends selected log messages to the 66 .I current 67 log file. 68 If 69 .I current 70 has 71 .I size 72 bytes or more (or there is a new-line within the last 73 .I len 74 of 75 .I size 76 bytes), or is older than a specified amount of 77 .IR time , 78 .I current 79 is rotated: 80 .P 81 .B svlogd 82 closes 83 .IR current , 84 changes permission of 85 .I current 86 to 0755, renames 87 .I current 88 to 89 .RI @ timestamp\fR.s, 90 and starts with a new empty 91 .IR current . 92 If 93 .B svlogd 94 sees 95 .I num 96 or more old log files in the log directory, it removes the oldest one. 97 Note that this doesn't decrease the number of log files if there are 98 already more than 99 .I num 100 log files, this must be done manually, e.g. for keeping 10 log files: 101 .P 102 ls \-1 \\@* |sort |sed \-ne '10,$p' |xargs rm 103 .SS PROCESSOR 104 If 105 .B svlogd 106 is told to process recent log files, it saves 107 .I current 108 to 109 .RI @ timestamp\fR.u, 110 feeds 111 .RI @ timestamp\fR.u 112 through ``sh \-c "\fIprocessor\fR"'' 113 and writes the output to 114 .RI @ timestamp\fR.t. 115 If the 116 .I processor 117 finishes successfully, 118 .RI @ timestamp\fR.t 119 is renamed to 120 .RI @ timestamp\fR.s, 121 and 122 .RI @ timestamp\fR.u 123 is deleted; otherwise 124 .RI @ timestamp\fR.t 125 is deleted and the 126 .I processor 127 is started again. 128 .B svlogd 129 also saves any output that the 130 .I processor 131 writes to file descriptor 5, and makes that output available on file 132 descriptor 4 when running 133 .I processor 134 on the next log file rotation. 135 .P 136 A 137 .I processor 138 is run in the background. 139 If 140 .B svlogd 141 sees a previously started 142 .I processor 143 still running when trying to start a new one for the same 144 .IR log , 145 it blocks until the currently running 146 .I processor 147 has finished successfully. 148 Only the HUP signal works in that situation. 149 Note that this may block any program feeding its log data to 150 .BR svlogd. 151 152 .SS CONFIG 153 On startup, and after receiving a HUP signal, 154 .B svlogd 155 checks for each log directory 156 .I log 157 if the configuration file 158 .I log/config 159 exists, and if so, reads the file line by line and adjusts configuration for 160 .I log 161 as follows: 162 .P 163 If the line is empty, or starts with a ``#'', it is ignored. 164 A line of the form 165 .TP 166 .RI s size 167 sets the maximum file size of 168 .I current 169 when 170 .B svlogd 171 should rotate the current log file to 172 .I size 173 bytes. 174 Default is 1000000. 175 If 176 .I size 177 is zero, 178 .B svlogd 179 doesn't rotate log files. 180 You should set 181 .I size 182 to at least (2 * 183 .IR len ). 184 .TP 185 .RI n num 186 sets the number of old log files 187 .B svlogd 188 should maintain to 189 .IR num . 190 If 191 .B svlogd 192 sees more that 193 .I num 194 old log files in 195 .I log 196 after log file rotation, it deletes the oldest one. 197 Default is 10. 198 If 199 .I num 200 is zero, 201 .B svlogd 202 doesn't remove old log files. 203 .TP 204 .RI N min 205 sets the minimum number of old log files 206 .B svlogd 207 should maintain to 208 .IR min . 209 .I min 210 must be less than 211 .IR num . 212 If 213 .I min 214 is set, and 215 .B svlogd 216 cannot write to 217 .I current 218 because the filesystem is full, and it sees more than 219 .I min 220 old log files, it deletes the oldest one. 221 .TP 222 .RI t timeout 223 sets the maximum age of the 224 .I current 225 log file when 226 .B svlogd 227 should rotate the current log file to 228 .I timeout 229 seconds. 230 If 231 .I current 232 is 233 .I timeout 234 seconds old, and is not empty, 235 .B svlogd 236 forces log file rotation. 237 .TP 238 .RI ! processor 239 tells 240 .B svlogd 241 to feed each recent log file through 242 .I processor 243 (see above) on log file rotation. 244 By default log files are not processed. 245 .TP 246 .RI u a.b.c.d[:port] 247 tells 248 .B svlogd 249 to transmit the first 250 .I len 251 characters of selected log messages to the IP address 252 .IR a.b.c.d , 253 port number 254 .IR port . 255 If 256 .I port 257 isn't set, the default port for syslog is used (514). 258 .I len 259 can be set through the \-l option, see below. 260 If 261 .B svlogd 262 has trouble sending udp packets, it writes error messages to the log 263 directory. 264 Attention: 265 logging through udp is unreliable, and should be used in private networks 266 only. 267 .TP 268 .RI U a.b.c.d[:port] 269 is the same as the 270 .I u 271 line above, but the log messages are no longer written to the log directory, 272 but transmitted through udp only. 273 Error messages from 274 .B svlogd 275 concerning sending udp packages still go to the log directory. 276 .TP 277 .RI p prefix 278 tells 279 .B svlogd 280 to prefix each line to be written to the log directory, to standard error, 281 or through UDP, with 282 .IR prefix . 283 .P 284 If a line starts with a 285 .IR \- , 286 .IR + , 287 .IR e , 288 or 289 .IR E , 290 .B svlogd 291 matches the first 292 .I len 293 characters of each log message against 294 .I pattern 295 and acts accordingly: 296 .TP 297 .RI \- pattern 298 the log message is deselected. 299 .TP 300 .RI + pattern 301 the log message is selected. 302 .TP 303 .RI e pattern 304 the log message is selected to be printed to standard error. 305 .TP 306 .RI E pattern 307 the log message is deselected to be printed to standard error. 308 .P 309 Initially each line is selected to be written to 310 .IR log/current . 311 Deselected log messages are discarded from 312 .IR log . 313 Initially each line is deselected to be written to standard err. 314 Log messages selected for standard error are written to standard error. 315 .SH PATTERN MATCHING 316 .B svlogd 317 matches a log message against the string 318 .I pattern 319 as follows: 320 .P 321 .I pattern 322 is applied to the log message one character by one, starting with the first. 323 A character not a star (``*'') and not a plus (``+'') matches itself. 324 A plus matches the next character in 325 .I pattern 326 in the log message one or more times. 327 A star before the end of 328 .I pattern 329 matches any string in the log message that does not include the next 330 character in 331 .IR pattern . 332 A star at the end of 333 .I pattern 334 matches any string. 335 .P 336 Timestamps optionally added by 337 .B svlogd 338 are not considered part of the log message. 339 .P 340 An 341 .B svlogd 342 pattern is not a regular expression. 343 For example consider a log message like this 344 .P 345 2005-12-18_09:13:50.97618 tcpsvd: info: pid 1977 from 10.4.1.14 346 .P 347 The following pattern doesn't match 348 .P 349 -*pid* 350 .P 351 because the first star matches up to the first p in tcpsvd, and then the 352 match fails because i is not s. 353 To match this log message, you can use a pattern like this instead 354 .P 355 -*: *: pid * 356 .SH OPTIONS 357 .TP 358 .B \-t 359 timestamp. 360 Prefix each selected line with a precise timestamp (see the daemontools' 361 .B tai64n 362 program) when writing to 363 .I log 364 or to standard error. 365 .TP 366 .B \-tt 367 timestamp. 368 Prefix each selected line with a human readable, sortable UTC timestamp of 369 the form YYYY-MM-DD_HH:MM:SS.xxxxx when writing to 370 .I log 371 or to standard error. 372 .TP 373 .B \-ttt 374 timestamp. 375 Prefix each selected line with a human readable, sortable UTC timestamp of 376 the form YYYY-MM-DDTHH:MM:SS.xxxxx when writing to 377 .I log 378 or to standard error. 379 .TP 380 .B \-r \fIc 381 replace. 382 .I c 383 must be a single character. 384 Replace non-printable characters in log messages with 385 .IR c . 386 Characters are replaced before pattern matching is applied. 387 .TP 388 .B \-R \fIxyz 389 replace charset. 390 Additionally to non-printable characters, replace all characters found in 391 .I xyz 392 with 393 .I c 394 (default ``_''). 395 .TP 396 .B \-l \fIlen 397 line length. 398 Pattern matching applies to the first 399 .I len 400 characters of a log message only. 401 Default is 1000. 402 .TP 403 .B \-b \fIbuflen 404 buffer size. 405 Set the size of the buffer 406 .B svlogd 407 uses when reading from standard input and writing to 408 .I logs 409 to 410 .IR buflen . 411 Default is 1024. 412 .I buflen 413 must be greater than 414 .IR len . 415 For 416 .B svlogd 417 instances that process a lot of data in short time, the buffer size should 418 be increased to improve performance. 419 .TP 420 .B \-v 421 verbose. 422 Print verbose messages to standard error. 423 .SH SIGNALS 424 If 425 .B svlogd 426 is sent a HUP signal, it closes and reopens all 427 .IR logs , 428 and updates their configuration according to 429 .IR log/config . 430 If 431 .B svlogd 432 has trouble opening a log directory, it prints a warning, and discards this 433 log directory. 434 If 435 .B svlogd 436 is unable to open all log directories given at the command line, it exits 437 with an error. 438 .P 439 If 440 .B svlogd 441 is sent a TERM signal, or if it sees end-of-file on standard input, it stops 442 reading standard input, processes the data in the buffer, waits for all 443 .I processor 444 subprocesses to finish if any, and exits 0 as soon as possible. 445 .P 446 If 447 .B svlogd 448 is sent an ALRM signal, it forces log file rotation for all 449 .I logs 450 with a non empty 451 .I current 452 log file. 453 .SH SEE ALSO 454 sv(8), 455 runsv(8), 456 chpst(8), 457 runit(8), 458 runit-init(8), 459 runsvdir(8), 460 runsvchdir(8) 461 .P 462 http://smarden.org/runit/ 463 .SH AUTHOR 464 Gerrit Pape <pape@smarden.org>