FreeBSD Handbook
Prev | Chapter 12 Configuration and Tuning | Next

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

Prev | Home | Next
Virtual Hosts | Up | Configuration Files