Log File Maintenance
You can capture logs. Fantastic! Now just let the log files grow until they fill your hard disk and leave room for nothing else, right? Or you can discard old logs and have the system keep the logs to a manageable size. This is called log rotation.
Look at the system messages log, /var/log/messages, and you should see six messages files: messages, messages.0.gz, messages.1.gz, messages.2.gz, messages.3.gz, and messages.4.gz. The plain messages file is the current log file. The other files are older logs; messages.0.gz is the newest, and messages.4.gz is the oldest.
When the current log file hits either a certain age or a specific size, log rotation discards the oldest log file (messages.4.gz), and the second-oldest file, messages.3.gz, is renamed to messages.4.gz; messages.2.gz is renamed to messages.3.gz; and so on. The existing messages file is renamed to messages.0 and compressed, and a new messages file is created.
The newsyslog(8) program rotates log files, restarts daemons, runs commands, shuffles old files into other directories, and handles all routine tasks. root runs newsyslog once per hour via cron(8). When newsyslog starts, it reads /etc/newsyslog.conf and examines each log file listed. If the conditions for rotating the log file are met, the log is rotated and other configured actions are taken.
newsyslog.conf Fields
newsyslog.conf uses one line per log file. Each line has seven fields, like this:
/var/log/authlog root:wheel 640 7 * 168 Z
From left to right, the fields are log file, owner, permissions, number of files to retain, size, time, and flags. After the flags field, you might see a number of optional arguments. We’ll look at each of the fields in order.
Log File
The first entry on each line is the full path to the log file to be processed (/var/log/authlog in this example). This must exactly match the current log file.
Owner
The second field (root:wheel in our example) lists the log file’s owner and group, separated by a colon. This field is optional, and is not present in many of the default entries.
By default, log files are owned by the root user and the wheel group, but newsyslog can change the owner of log files. While changing ownership isn’t common, you might want to explicitly declare it for specific files.
You can choose to change only the owner or only the group. In these cases, use a colon with a name on only one side of it, such as :wheel or root:. You must always include the colon if you’re changing ownership.
Permissions
The third field (640 in our example) gives the rotated file’s permissions in standard octal notation, as discussed in chmod(1). This field is optional, and it is not present in many default entries.
Count
The fourth field specifies the number of archived log files that newsyslog keeps. In our example, /var/log/messages has the current log file and five archives, numbered 0 through 4. newsyslog.conf has a count of 5 for /var/log/messages.
Size
The fifth field is a file size in kilobytes. When newsyslog runs, it checks the size of the log file. If the log is larger than the size given here, newsyslog rotates the log. If you don’t want the file size to affect when newsyslog rotates the file, put an asterisk here.
Time
To rotate the log based on time, use the sixth field, which has four possible values: an asterisk, a number, and a time in one of two standard formats. If you rotate the log based on size rather than age, put an asterisk here. If you put a number here, you are specifying a number of hours after which the log will rotate. Our example of /var/log/authlog rotates every 168 hours.
The time formats—ISO 8601 restricted and newsyslog-specific—are a little more complicated.
ISO 8601 restrictedA time entry beginning with an
@symbol is in the ISO 8601 restricted time format. The ISO 8601 restricted time format is used bynewsyslogon most Unix-like systems, because it was the time format used in MIT’s primordialnewsyslog. The ISO 8601 format is a bit obtuse, but every Unix-like operating system I’m aware of supports it.A full date in ISO 8601 format is 14 digits with a
Tin the middle. The first four digits are the year, the next two are the month, and the next two are the day of the month. (TheTserves as a sort of decimal point, separating whole days from fractions of a day.) The next two digits are hours, the next two are minutes, and the last two are seconds. For example, the date September 13, 2013, at 3:18 and 58 seconds PM is expressed as20130913T151858. (Specifying a specific date and time to rotate a log wouldn’t be terribly useful because the log would rotate only once.)You can choose to specify only the fields near the
T, leaving fields farther away blank. Again, if you think of theTas a decimal point, you don’t need to write 5.87 as 005.8700; the leading and trailing zeros are irrelevant.In the case of
newsyslog, empty fields are wildcards. For example,4T00matches midnight on the fourth day of every month, andT23matches the twenty-third hour, or 11 PM, every day. If newsyslog.conf lists the time@T2359, the log rotates at 11:59 PM every day. (Of course,newsyslogruns once an hour, so the log won’t rotate exactly then.)As with
cron(8), specify time units in detail. For example,@9T, the ninth day of the month, rotates the log once an hour, every hour, on the ninth day of the month, which would mean it rotates the log all day on that day. It would probably be better to specify a time of@9T01, which would rotate the log at 1 AM on the ninth day of the month. You don’t need to specify times any more closely than the hour, asnewsyslogruns only hourly.
newsyslog timesBecause ISO 8601 time doesn’t let you easily specify weekly jobs, and it’s impossible to specify the last day of the month, OpenBSD includes a
newsyslog-specific time format that lets you easily specify these common times.Any entry with a leading dollar sign (
$) is written in month week day format.This particular format uses three identifiers:
M(day of month),W(day of week), andH(hour of day). Each identifier is followed by a number indicating the unit you’re using. Hours range from0to23, and days run from0(Sunday) to6(Saturday). Days of the month start at1and go to31, withLorlrepresenting the last day of the month. For example, to rotate a log on the fifth of each month at noon, use$M5H12. To start the month-end accounting at 11 PM on the last day of the month, use$MLH23.If you don’t specify an hour, the time defaults to midnight on the chosen day. And if a newsyslog.conf entry lists both a time and a size for file rotation,
newsyslogrotates the log if either requirement is met.
Flags
The seventh field, which is optional, instructs newsyslog on special processing for the file itself. OpenBSD uses four flags:
-
Z. Compress the file withgzip(1). -
B. Do not add a “log file turned over” message to the file (for binary files). -
F. Follow symlinks. -
M. A user is monitoring this log.
While the B and Z flags are not, strictly speaking, mutually incompatible, most log files need only one of them, and most binary files don’t compress well anyway. (The default newsyslog.conf compresses the packet filtering log file, but that’s something of an oddity.) If you see the Z flag with the M flag, the old log file will be sent to the user before the log is compressed.
Monitoring Logs
OpenBSD’s newsyslog can email logs to a user before rotating them. If you carefully control how you sort your logs, this feature can be useful. For example, sudo(8) logs successful uses at priority notice, but failed uses at priority alert. You might split these into separate log files in syslog.conf, like this:
!sudo *.* /var/log/sudo *.alert /var/log/sudofail
The file /var/log/sudofail should now contain only sudo failures, such as users entering incorrect passwords or exceeding their privileges.
Now you could tell newsyslog to check for monitored logs by running it with the -m flag. (newsyslog runs as one of root’s cron jobs.)
To have the sudo failure log emailed to you every time the log rotates, you can put your account in the monitor field.
/var/log/sudofail root:wheel 640 30 * $H06 ZM mwlucas
This assumes that email to the account mwlucas on this machine reaches me. The simplest way to ensure that would be to forward the email in /etc/mail/aliases.
Adding a PID File
If newsyslog tries to rotate and compress a file, but the process writing the file is still writing to the file, the file can become corrupted. Some programs need a right proper slapping before they will let go of their log files. How? Just list a PID file here, and newsyslog will send that process ID a SIGHUP (like a kill -1).
Note that PID files are not a terribly secure way to identify specific processes because they are subject to race conditions and other attacks. If the server has a command for rotating its logs, that’s probably a wiser choice than signaling a process indicated in a PID file.
Signal Name
To send a signal other than SIGHUP to a process with a PID file, use a different signal name. The signal name must begin with SIG and be specified by name. You can find a full list of signals in signal(3), but the software documentation should tell you which signal the process needs to release in order to restart its log file. This field is optional, but if you use it, you must enter a full path to a PID file immediately before it.
Command to Execute
Rather than signaling a process, you can have newsyslog run a command when rotating logs by giving the full path to the command in double quotes. While this field is optional, it cannot be combined with a PID file. You can use a PID file or a command name, but not both.