diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/man/rotatelogs.8 | 42 |
1 files changed, 27 insertions, 15 deletions
diff --git a/docs/man/rotatelogs.8 b/docs/man/rotatelogs.8 index 6baaf14..29c35da 100644 --- a/docs/man/rotatelogs.8 +++ b/docs/man/rotatelogs.8 @@ -19,7 +19,7 @@ .el .ne 3 .IP "\\$1" \\$2 .. -.TH "ROTATELOGS" 8 "2018-07-06" "Apache HTTP Server" "rotatelogs" +.TH "ROTATELOGS" 8 "2023-03-05" "Apache HTTP Server" "rotatelogs" .SH NAME rotatelogs \- Piped logging program to rotate Apache logs @@ -44,7 +44,7 @@ rotatelogs \- Piped logging program to rotate Apache logs Causes the use of local time rather than GMT as the base for the interval or for \fBstrftime(3)\fR formatting with size-based rotation\&. .TP \fB-L\fR \fIlinkname\fR -Causes a hard link to be made from the current logfile to the specified link name\&. This can be used to watch the log continuously across rotations using a command like \fBtail -F linkname\fR\&. +.PP Causes a hard link to be made from the current logfile to the specified link name\&. This can be used to watch the log continuously across rotations using a command like \fBtail -F linkname\fR\&. .PP If the linkname is not an absolute path, it is relative to \fBrotatelogs\fR' working directory, which is the ServerRoot when \fBrotatelogs\fR is run by the server\&. .TP \fB-p\fR \fIprogram\fR If given, \fBrotatelogs\fR will execute the specified program every time a new log file is opened\&. The filename of the newly opened file is passed as the first argument to the program\&. If executing after a rotation, the old log file is passed as the second argument\&. \fBrotatelogs\fR does not wait for the specified program to terminate before continuing to operate, and will not log any error code returned on termination\&. The spawned program uses the same stdin, stdout, and stderr as rotatelogs itself, and also inherits the environment\&. @@ -58,6 +58,9 @@ Creates the parent directories of the path that the log file will be placed in i \fB-t\fR Causes the logfile to be truncated instead of rotated\&. This is useful when a log is processed in real time by a command like tail, and there is no need for archived data\&. No suffix will be added to the filename, however format strings containing '%' characters will be respected\&. .TP +\fB-T\fR +Causes all but the initial logfile to be truncated when opened\&. This is useful when the format string contains something that will loop around, such as the day of the month\&. Available in 2\&.4\&.56 and later\&. +.TP \fB-v\fR Produce verbose output on STDERR\&. The output contains the result of the configuration parsing, and all file open and close actions\&. .TP @@ -68,10 +71,10 @@ Echo logs through to stdout\&. Useful when logs need to be further processed in Create log file for each interval, even if empty\&. .TP \fB-n \fInumber-of-files\fR\fR -Use a circular list of filenames without timestamps\&. With -n 3, the series of log files opened would be "logfile", "logfile\&.1", "logfile\&.2", then overwriting "logfile"\&. Available in 2\&.4\&.5 and later\&. +Use a circular list of filenames without timestamps\&. This option overwrites log files at startup and during rotation\&. With -n 3, the series of log files opened would be "logfile", "logfile\&.1", "logfile\&.2", then overwriting "logfile"\&. When this program first opens "logfile", the file will only be truncated if \fB-t\fR is also provided\&. Every subsequent rotation will always begin with truncation of the target file\&. For size based rotation without \fB-t\fR and existing log files in place, this option may result in unintuitive behavior such as initial log entries being sent to "logfile\&.1", and entries in "logfile\&.1" not being preserved even if later "logfile\&.n" have not yet been used\&. Available in 2\&.4\&.5 and later\&. .TP \fB\fIlogfile\fR\fR -.PP The path plus basename of the logfile\&. If \fIlogfile\fR includes any '%' characters, it is treated as a format string for \fBstrftime(3)\fR\&. Otherwise, the suffix \fI\&.nnnnnnnnnn\fR is automatically added and is the time in seconds (unless the -t option is used)\&. Both formats compute the start time from the beginning of the current period\&. For example, if a rotation time of 86400 is specified, the hour, minute, and second fields created from the \fBstrftime(3)\fR format will all be zero, referring to the beginning of the current 24-hour period (midnight)\&. .PP When using \fBstrftime(3)\fR filename formatting, be sure the log file format has enough granularity to produce a different file name each time the logs are rotated\&. Otherwise rotation will overwrite the same file instead of starting a new one\&. For example, if \fIlogfile\fR was \fB/var/log/errorlog\&.%Y-%m-%d\fR with log rotation at 5 megabytes, but 5 megabytes was reached twice in the same day, the same log file name would be produced and log rotation would keep writing to the same file\&. +.PP The path plus basename of the logfile\&. If \fIlogfile\fR includes any '%' characters, it is treated as a format string for \fBstrftime(3)\fR\&. Otherwise, the suffix \fI\&.nnnnnnnnnn\fR is automatically added and is the time in seconds (unless the -t option is used)\&. Both formats compute the start time from the beginning of the current period\&. For example, if a rotation time of 86400 is specified, the hour, minute, and second fields created from the \fBstrftime(3)\fR format will all be zero, referring to the beginning of the current 24-hour period (midnight)\&. .PP When using \fBstrftime(3)\fR filename formatting, be sure the log file format has enough granularity to produce a different file name each time the logs are rotated\&. Otherwise rotation will overwrite the same file instead of starting a new one\&. For example, if \fIlogfile\fR was \fB/var/log/errorlog\&.%Y-%m-%d\fR with log rotation at 5 megabytes, but 5 megabytes was reached twice in the same day, the same log file name would be produced and log rotation would keep writing to the same file\&. .PP If the logfile is not an absolute path, it is relative to \fBrotatelogs\fR' working directory, which is the ServerRoot when \fBrotatelogs\fR is run by the server\&. .TP \fB\fIrotationtime\fR\fR The time between log file rotations in seconds\&. The rotation occurs at the beginning of this interval\&. For example, if the rotation time is 3600, the log file will be rotated at the beginning of every hour; if the rotation time is 86400, the log file will be rotated every night at midnight\&. (If no data is logged during an interval, no file will be created\&.) @@ -85,49 +88,58 @@ The number of minutes offset from UTC\&. If omitted, zero is assumed and UTC is .SH "EXAMPLES" .nf - + CustomLog "|bin/rotatelogs /var/log/logfile 86400" common - + .fi .PP This creates the files /var/log/logfile\&.nnnn where nnnn is the system time at which the log nominally starts (this time will always be a multiple of the rotation time, so you can synchronize cron scripts with it)\&. At the end of each rotation time (here after 24 hours) a new log is started\&. .nf - + CustomLog "|bin/rotatelogs -l /var/log/logfile\&.%Y\&.%m\&.%d 86400" common - + .fi .PP This creates the files /var/log/logfile\&.yyyy\&.mm\&.dd where yyyy is the year, mm is the month, and dd is the day of the month\&. Logging will switch to a new file every day at midnight, local time\&. .nf - + CustomLog "|bin/rotatelogs /var/log/logfile 5M" common - + .fi .PP This configuration will rotate the logfile whenever it reaches a size of 5 megabytes\&. .nf - + ErrorLog "|bin/rotatelogs /var/log/errorlog\&.%Y-%m-%d-%H_%M_%S 5M" - + .fi .PP This configuration will rotate the error logfile whenever it reaches a size of 5 megabytes, and the suffix to the logfile name will be created of the form \fBerrorlog\&.YYYY-mm-dd-HH_MM_SS\fR\&. .nf - + CustomLog "|bin/rotatelogs -t /var/log/logfile 86400" common - + +.fi + +.PP +This creates the file \fB/var/log/logfile\fR, truncating the file at startup and then truncating the file once per day\&. It is expected in this scenario that a separate process (such as tail) would process the file in real time\&. + +.nf + + CustomLog "|bin/rotatelogs -T /var/log/logfile\&.%d 86400" common + .fi .PP -This creates the file /var/log/logfile, truncating the file at startup and then truncating the file once per day\&. It is expected in this scenario that a separate process (such as tail) would process the file in real time\&. +If the server is started (or restarted) on the first of the month, this appends to \fB/var/log/logfile\&.01\fR\&. When a log entry is written on the second of the month, \fB/var/log/logfile\&.02\fR is truncated and new entries will be added to the top\&. This example keeps approximately 1 months worth of logs without external maintenance\&. .SH "PORTABILITY" |