From: Rich Bowen Date: Mon, 22 Jun 2026 17:21:58 +0000 (+0000) Subject: docs: Rewrite log rotation section in logs.xml X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=87c208c48c74285ab4d2e7d07bc4fd306638ee2f;p=thirdparty%2Fapache%2Fhttpd.git docs: Rewrite log rotation section in logs.xml - Replace hand-rolled mv/graceful/sleep/gzip recipe with modern practices: rotatelogs (recommended) and system logrotate - Add examples for time-based, size-based, and strftime-pattern rotation - Rewrite piped logs section: tighten prose, remove redundant rotatelogs example, wrap highlight blocks in tags - Remove "In order to", "simply", bare "Apache" references git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935553 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/logs.xml b/docs/manual/logs.xml index 78f43aa218..4a3c28f110 100644 --- a/docs/manual/logs.xml +++ b/docs/manual/logs.xml @@ -525,95 +525,117 @@ LogFormat "%!200,304,302{Referer}i" refererlog
Log Rotation -

On even a moderately busy server, the quantity of - information stored in the log files is very large. The access - log file typically grows 1 MB or more per 10,000 requests. It - will consequently be necessary to periodically rotate the log - files by moving or deleting the existing logs. This cannot be - done while the server is running, because Apache httpd will continue - writing to the old log file as long as it holds the file open. - Instead, the server must be restarted after the log files are - moved or deleted so that it will open new log files.

- -

By using a graceful restart, the server can be - instructed to open new log files without losing any existing or - pending connections from clients. However, in order to - accomplish this, the server must continue to write to the old - log files while it finishes serving old requests. It is - therefore necessary to wait for some time after the restart - before doing any processing on the log files. A typical - scenario that simply rotates the logs and compresses the old - logs to save space is:

- - - mv access_log access_log.old
- mv error_log error_log.old
- apachectl graceful
- sleep 600
- gzip access_log.old error_log.old - - -

Another way to perform log rotation is using piped logs as discussed in the next - section.

-
+

On even a moderately busy server, log files grow quickly — + the access log typically grows 1 MB or more per 10,000 requests. + Without rotation, logs consume disk space indefinitely and become + unwieldy to analyze. You should set up automatic log rotation from + the start.

+ +
+ Using rotatelogs (recommended) + +

The simplest approach is to use httpd's built-in + rotatelogs program via piped + logs. This rotates logs without requiring a server restart + and without any external tools. To rotate logs every 24 hours:

+ + + +CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/httpd/access_log 86400" combined +ErrorLog "|/usr/local/apache/bin/rotatelogs /var/log/httpd/error_log 86400" + + + +

To rotate when the log reaches a certain size (e.g., 100 MB):

+ + + +CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/httpd/access_log 100M" combined + + + +

You can also use a time-based filename pattern with + strftime format strings:

+ + + +CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/httpd/access_log.%Y-%m-%d 86400" combined + + + +

See rotatelogs for the full set of options, + including offset times, file count limits, and compression.

+
-
- Piped Logs +
+ Using logrotate or system log management -

Apache httpd is capable of writing error and access log - files through a pipe to another process, rather than directly - to a file. This capability dramatically increases the - flexibility of logging, without adding code to the main server. - In order to write logs to a pipe, simply replace the filename - with the pipe character "|", followed by the name - of the executable which should accept log entries on its - standard input. The server will start the piped-log process when - the server starts, and will restart it if it crashes while the - server is running. (This last feature is why we can refer to - this technique as "reliable piped logging".)

- -

Piped log processes are spawned by the parent Apache httpd - process, and inherit the userid of that process. This means - that piped log programs usually run as root. It is therefore - very important to keep the programs simple and secure.

- -

One important use of piped logs is to allow log rotation - without having to restart the server. The Apache HTTP Server - includes a simple program called rotatelogs - for this purpose. For example, to rotate the logs every 24 hours, you - can use:

+

Most Linux distributions include logrotate, which + can rotate, compress, and expire log files on a schedule. If your + distribution already ships an httpd logrotate configuration (check + /etc/logrotate.d/), it may already be handling rotation + for you.

- -CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common - +

When using an external rotation tool like logrotate, + you need to signal httpd to reopen its log files after + the old ones are moved aside. The standard approach is a + graceful restart:

-

Notice that quotes are used to enclose the entire command - that will be called for the pipe. Although these examples are - for the access log, the same technique can be used for the - error log.

+ + +/usr/sbin/apachectl graceful + + -

As with conditional logging, piped logs are a very powerful - tool, but they should not be used where a simpler solution like - off-line post-processing is available.

+

Your logrotate configuration's postrotate script + should include this (or the equivalent + systemctl reload command). httpd continues writing to + the old file handle until it receives the signal, so any post-processing + of rotated files should allow a brief delay.

-

By default the piped log process is spawned without invoking - a shell. Use "|$" instead of "|" - to spawn using a shell (usually with /bin/sh -c):

+
+
- -# Invoke "rotatelogs" using a shell -CustomLog "|$/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common - +
+ Piped Logs -

This was the default behavior for Apache 2.2. - Depending on the shell specifics this might lead to - an additional shell process for the lifetime of the logging - pipe program and signal handling problems during restart. - For compatibility reasons with Apache 2.2 the notation - "||" is also supported and equivalent to using - "|".

+

httpd can write error and access log files through a pipe to + another process, rather than directly to a file. To use a piped + log, replace the filename with the pipe character + "|", followed by the command that should receive + log entries on its standard input:

+ + + +CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/httpd/access_log 86400" combined + + + +

httpd starts the piped-log process at server startup and + restarts it automatically if it crashes (this is sometimes called + "reliable piped logging"). The quotes enclose the entire piped + command — this syntax works for both + CustomLog and + ErrorLog.

+ +

Piped log processes are spawned by the parent httpd process and + inherit its userid. This typically means they run as root, so keep + piped log programs simple and secure.

+ +

By default the piped log process is spawned directly, without + invoking a shell. Use "|$" instead of + "|" to spawn via a shell (usually + /bin/sh -c):

+ + + +CustomLog "|$/usr/local/apache/bin/rotatelogs /var/log/httpd/access_log 86400" combined + + + +

The shell variant is occasionally needed if your piped command + uses shell features like globbing or variable expansion. For most + cases, the direct (non-shell) invocation is preferred.

Windows note

Note that on Windows, you may run into problems when running many piped