12.10. Configuring the System Logger, syslogd

Contributed by Niclas Zeising.

System logging is an important aspect of system administration. It is used to detect hardware and software issues and errors in the system. It plays an important role in security auditing and incident response. System daemons without a controlling terminal 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(8) on a local machine. For more advanced setups using a separate loghost, see Section 28.12, “Remote Host Logging with syslogd.

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, “Core Configuration” and Section 12.7, “Using rc(8) Under FreeBSD” 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, the hostname of the machine generating the logging event.

The configuration file for syslogd(8) 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 to a file or 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 1
*.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 2
lpr.info                                        /var/log/lpd-errs
ftp.info                                        /var/log/xferlog
cron.*                                          /var/log/cron
*.=debug                                        /var/log/debug.log 3
*.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 4
*.*                                             /var/log/ppp.log
!*

1

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).

2

Match all messages from the mail facility at level info or above, and log the messages to /var/log/maillog.

3

This line uses a comparison flag, = to only match messages at level debug, and log them in /var/log/debug.log.

4

Here is an example usage of a program specification. This makes the rules following it only valid for the program in the program specification. In this case, this and the following lines log all messages from ppp(8), but no other programs, to /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 /etc/syslog.conf, its syntax, and more advanced usage examples, see syslog.conf(5) and Section 28.12, “Remote Host Logging with syslogd.

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 syslogd(8) as newsyslog(8) works with any logs written from any program. While newsyslog(8) is normally run from cron(8), it is not a system daemon. In the default configuration, it is run every hour.

12.10.3.1. Configuring newsyslog

To know which 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: head/en_US.ISO8859-1/books/handbook/config/chapter.xml 43126 2013-11-07 16:37:11Z gabor $
#
# 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/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 mode field sets the permissions on the log file and count denotes how many rotated log files should be kept. The size and when fields tell newsyslog(8) 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 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). Since newsyslog(8) is run from cron(8), it can not rotate files more often than it is run from cron(8).

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.