12.10 Configuring the System Logger, syslogd
Contributed by Niclas Zeising.System logging is an important aspect of system administration. It is used both to detect hardware and software issues and errors in the system. It also plays a very important role in security auditing and incident response. System daemons without a controlling terminal also usually log information to a system logging facility or other log file.
This section describes how to configure and use the FreeBSD system logger, syslogd(8), and how to perform log rotation and log management using newsyslog(8). Focus will be on setting up and using syslogd on a local machine. For more advanced setups using a separate loghost, see Section 30.11.
12.10.1 Using syslogd
In the default FreeBSD configuration syslogd(8) is started at boot. This is controlled by the variable syslogd_enable in /etc/rc.conf. There are numerous application arguments that affect the behavior of syslogd(8). To change them, use syslogd_flags in /etc/rc.conf. Refer to syslogd(8) for more information on the arguments, and rc.conf(5), Section 12.3 and Section 12.7 for more information about /etc/rc.conf and the rc(8) subsystem.
12.10.2 Configuring syslogd
The configuration file, by default /etc/syslog.conf, controls what syslogd(8) does with the log entries once they are received. There are several parameters to control the handling of incoming events, of which the most basic are facility and level. The facility describes which subsystem generated the message, such as the kernel or a daemon, and the level describes the severity of the event that occurred. This makes it possible to log the message to different log files, or discard it, depending on the facility and level. It is also possible to take action depending on the application that sent the message, and in the case of remote logging, also the hostname of the machine generating the logging event.
Configuring syslogd(8) is quite straight forward. The configuration file contains one line per action, and the syntax for each line is a selector field followed by an action field. The syntax of the selector field is facility.level which will match log messages from facility at level level or higher. It is also possible to add an optional comparison flag before the level to specify more precisely what is logged. Multiple selector fields can be used for the same action, and are separated with a semicolon (;). Using * will match everything. The action field denotes where to send the log message, such as a file or a remote log host. As an example, here is the default syslog.conf from FreeBSD:
# $FreeBSD$ # # Spaces ARE valid field separators in this file. However, # other *nix-like systems still insist on using tabs as field # separators. If you are sharing this file between systems, you # may want to use only tabs as field separators here. # Consult the syslog.conf(5) manpage. *.err;kern.warning;auth.notice;mail.crit /dev/console*.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err /var/log/messages security.* /var/log/security auth.info;authpriv.info /var/log/auth.log mail.info /var/log/maillog
lpr.info /var/log/lpd-errs ftp.info /var/log/xferlog cron.* /var/log/cron *.=debug /var/log/debug.log
*.emerg * # uncomment this to log all writes to /dev/console to /var/log/console.log #console.info /var/log/console.log # uncomment this to enable logging of all log messages to /var/log/all.log # touch /var/log/all.log and chmod it to mode 600 before it will work #*.* /var/log/all.log # uncomment this to enable logging to a remote loghost named loghost #*.* @loghost # uncomment these if you're running inn # news.crit /var/log/news/news.crit # news.err /var/log/news/news.err # news.notice /var/log/news/news.notice !ppp
*.* /var/log/ppp.log !*
- Match all messages with a level of err or higher, as well as kern.warning, auth.notice and mail.crit, and send these log messages to the console (/dev/console).
- Match all messages from the mail facility at level info or above, and log the messages to /var/log/maillog.
- This line uses a comparison flag, = to only match messages at level debug, and log them in /var/log/debug.log.
- Here is an example usage of a program specification. This will make the rules following only be valid for the program in the program specification. In this case this line and the following makes all messages from ppp, but no other programs, end up in /var/log/ppp.log.
This example shows that there are plenty of levels and subsystems. The levels are, in order from most to least critical: emerg, alert, crit, err, warning, notice, info and debug.
The facilities are, in no particular order: auth, authpriv, console, cron, daemon, ftp, kern, lpr, mail, mark, news, security, syslog, user, uucp and local0 through local7. Be aware that other operating systems might have different facilities.
With this knowledge it is easy to add a new line to /etc/syslog.conf to log everything from the different daemons on level notice and higher to /var/log/daemon.log. Just add the following:
daemon.notice /var/log/daemon.log
For more information about the different levels and facilities, refer to syslog(3) and syslogd(8). For more information about syslog.conf, its syntax, and more advanced usage examples, see syslog.conf(5) and Section 30.11.
12.10.3 Log Management and Rotation with newsyslog
Log files tend to grow quickly and accumulate steadily. This leads to the files being full of less immediately useful information while filling up the hard drive. Log management attempts to mitigate this. In FreeBSD, newsyslog(8) is used to manage log files. This program periodically rotates and compresses log files, and optionally creates missing log files and signals programs when log files are moved. The log files are not necessarily generated by syslog as newsyslog(8) works with any logs written from any program. Note that newsyslog is normally run from cron(8) and is not a system daemon. In the default configuration, it is run every hour.
12.10.3.1 Configuring newsyslog
To know what actions to take, newsyslog(8) reads its configuration file, by default /etc/newsyslog.conf. This configuration file contains one line for each file that newsyslog(8) manages. Each line states the file owner, permissions, when to rotate that file, optional flags that affect log rotation, such as compression, and programs to signal when the log is rotated. Here is the default configuration in FreeBSD:
# configuration file for newsyslog # $FreeBSD$ # # Entries which do not specify the '/pid_file' field will cause the # syslogd process to be signalled when that log file is rotated. This # action is only appropriate for log files which are written to by the # syslogd process (ie, files listed in /etc/syslog.conf). If there # is no process which needs to be signalled when a given log file is # rotated, then the entry for that file should include the 'N' flag. # # The 'flags' field is one or more of the letters: BCDGJNUXZ or a '-'. # # Note: some sites will want to select more restrictive protections than the # defaults. In particular, it may be desirable to switch many of the 644 # entries to 640 or 600. For example, some sites will consider the # contents of maillog, messages, and lpd-errs to be confidential. In the # future, these defaults may change to more conservative ones. # # logfilename [owner:group] mode count size when flags [/pid_file] [sig_num] /var/log/all.log 600 7 * @T00 J /var/log/amd.log 644 7 100 * J /var/log/auth.log 600 7 100 @0101T JC /var/log/console.log 600 5 100 * J /var/log/cron 600 3 100 * JC /var/log/daily.log 640 7 * @T00 JN /var/log/debug.log 600 7 100 * JC /var/log/init.log 644 3 100 * J /var/log/kerberos.log 600 7 100 * J /var/log/lpd-errs 644 7 100 * JC /var/log/maillog 640 7 * @T00 JC /var/log/messages 644 5 100 @0101T JC /var/log/monthly.log 640 12 * $M1D0 JN /var/log/pflog 600 3 100 * JB /var/run/pflogd.pid /var/log/ppp.log root:network 640 3 100 * JC /var/log/security 600 10 100 * JC /var/log/sendmail.st 640 10 * 168 B /var/log/utx.log 644 3 * @01T05 B /var/log/weekly.log 640 5 1 $W6D0 JN /var/log/xferlog 600 7 100 * JC
Each line starts with the name of the file to be rotated, optionally followed by an owner and group for both rotated and newly created files. The next field, mode is the mode of the files and count denotes how many rotated log files should be kept. The size and when fields tell newsyslog when to rotate the file. A log file is rotated when either its size is larger than the size field, or when the time in the when filed has passed. * means that this field is ignored. The flags field gives newsyslog(8) further instructions, such as how to compress the rotated file, or to create the log file if it is missing. The last two fields are optional, and specify the PID-file of a process and a signal number to send to that process with when the file is rotated. For more information on all fields, valid flags and how to specify the rotation time, refer to newsyslog.conf(5). Remember that newsyslog is run from cron and can not rotate files more often than it is run from cron(8).