etcnewsyslog.conf

/etc/newsyslog.conf

Log file growth is one common cause of disk space shortages. By rotating your logs, the system compresses older logs, makes room for new logs, and discards the oldest logs. OpenBSD's log file rotation program, newsyslog(8), can handle all this and more. Cron runs newsyslog(8) once per hour. The /etc/ newsyslog.conf file tells newsyslog(8) under which conditions a log should be rotated and what actions should be taken upon rotation.

The /etc/newsyslog file uses one line per log file, and each line has between five and eight fields. For example:

 /var/log/messages                    644  5    30  *    Z 

Log File Path

The first field is the full path to the log file to be processed, /var/log/messages in this example.

Owner and Group

The second field is optional and does not actually appear in the example above. You can list an owner and group for the rotated log file, separated by a period (such as "root.wheel").

Newsyslog(8) can change the owner and group of old log files. By default, log files are owned by root and are in the wheel group. While it's not common to change the owner, you might have to use this ability on multi-user machines.

You can choose to change only the owner or change only the group. In these cases you must use a period, even though nothing appears on the other side of it. For example, ".customer12" will change the file to be owned by the group "customer12," while "customer15." will change the owner to be customer15.

Permissions

The third field (644) in the example gives the permissions mode, in standard UNIX three-digit notation. See chmod(1) for details.

Count

Next is the "count" field, which represents the number of old log files that newsyslog(8) will keep — sort of. Newsyslog(8) starts counting archived log files at 0. Many computer systems start numbering at 0, but newsyslog(8) includes 0 as well as the count number. With the default count setting of 5 for /var/log/ messages, /var/log/ includes the following files:

 /var/log/messages /var/log/messages.0.gz /var/log/messages.1.gz /var/log/messages.2.gz /var/log/messages.3.gz /var/log/messages.4.gz /var/log/messages.5.gz 

This is six backups, not five, plus the current log file! The oldest backup log is numbered 5, which is what newsyslog(8) uses the count for. While it's better to have too many logs than not enough, if you have a space shortage you might need to reduce the number of logs you keep. The important thing is that you understand what actually happens when you specify a number of logs to retain.

Size

The fifth field (30 in our example) is the file size. When newsyslog runs, it compares the size listed here with the size of the file. If the file is larger than the given size (in kilobytes), it is rotated. If the file size doesn't affect when you want to rotate the file, list an asterisk in this field.

Time

This is the number of hours that must pass before the logs will be archived again. If you put 24 here, the logs will be rotated once per day. If you put an asterisk here, the age of the file will not be considered when deciding when to rotate the file.

Flags

This optional field tells newsyslog(8) of other actions it should take. OpenBSD supports four flags.

Flag	Meaning
Z	Compress the file with gzip(1) or compress(1)
B	Do not include the "log file turned over" message in the log (for binary files)
F	Follow symlinks
M	A user is monitoring this log

Monitoring User

Newsyslog(8) can notify users when a log file they are interested in is rotated. To do this newsyslog(8) must be run with the "-m" option and the "M" flag must be set on the log file. Next, list the username of the user who will be notified. This entry is optional.

PID File

Some programs record their process ID in a file. Newsyslog can send a signal to a process when the log file has been rotated, so the program knows to start a new log file. List the full path to the PID file next on the line. By default, newsyslog sends a SIGHUP; if you want to use a different signal, specify a signal name in the next field. This entry is optional.

Signal Name

If you don't want to send a SIGHUP to a process with a PID file, you can use a different signal name instead. The signal name must begin with SIG- and must be specified by name. You can get a full list of signals in signal(3). This field is optional, but requires a path to a PID file appear previously.

Command to Execute

Rather than sending a signal to a process, you can have newsyslog(8) run a command when it has finished rotating logs. The command must be given in double quotes. While this field is optional, it cannot be used with a PID file and a signal entry.