<sect1 id="configtuning-syslog">

    <sect1info>

      <authorgroup>

	<author>

	  <firstname>Niclas</firstname>

	  <surname>Zeising</surname>

	  <contrib>Contributed by </contrib>

	  <!-- 30 May 2012 -->

	</author>

      </authorgroup>

    </sect1info>

    <title>Configuring the system logger

      <application>syslogd</application></title>

    <indexterm><primary>system logging</primary></indexterm>

    <indexterm><primary>syslog</primary></indexterm>

    <indexterm><primary>syslogd</primary></indexterm>

    <para>System logging is an important aspect of system administration.

      It is used both to detect hardware and software issues and errors in

      the system, as well as playing 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.</para>

    <para>This section will describe how to configure and use the &os; system

      logger, &man.syslogd.8;, as well as discuss log rotation

      and log management using &man.newsyslog.8;.  Focus

      will be on setting up and using <command>syslogd</command> on

      a local machine.  For more advanced setups using a separate loghost, see

      <xref linkend="network-syslogd">.</para>

    <sect2>

      <title>Using <application>syslogd</application></title>

      <para>In the default &os; configuration &man.syslogd.8; is started

	at boot.  This is controlled by the variable

	<literal>syslogd_enable</literal> in <filename>/etc/rc.conf</filename>.

	There are numerous application arguments that affect the behavior of

	&man.syslogd.8.  To change them, use

	<literal>syslogd_flags</literal> in <filename>/etc/rc.conf</filename>.

	Refer to &man.syslogd.8; for more information on the arguments, and

	&man.rc.conf.5;, <xref linkend="configtuning-core-configuration">

	and <xref linkend="configtuning-rcd"> for more information about

	<filename>/etc/rc.conf</filename> and the &man.rc.8; subsystem.</para>

    </sect2>

    <sect2>

      <title>Configuring <application>syslogd</application></title>

      <indexterm><primary>syslog.conf</primary></indexterm>

      <para>The configuration file, by default

	<filename>/etc/syslog.conf</filename>, controls what &man.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 <firstterm>facility</firstterm> and

	<firstterm>level</firstterm>.  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.</para>

      <para>Configuring &man.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

	<replaceable>facility.level</replaceable> and this will match

	log messages from <replaceable>facility</replaceable> at level

	<replaceable>level</replaceable> 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 (<literal>;</literal>).  Using

	<literal>*</literal> 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 <filename>syslog.conf</filename> from &os;:</para>

      <programlisting># &dollar;&os;&dollar;

#

#       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 &man.syslog.conf.5; manpage.

*.err;kern.warning;auth.notice;mail.crit                /dev/console <co id="co-syslog-many-match">

*.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 <co id="co-syslog-one-match">

lpr.info                                        /var/log/lpd-errs

ftp.info                                        /var/log/xferlog

cron.*                                          /var/log/cron

*.=debug                                        /var/log/debug.log <co id="co-syslog-comparison">

*.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 <co id="co-syslog-prog-spec">

*.*                                             /var/log/ppp.log

!*</programlisting>

      <calloutlist>

	<callout arearefs="co-syslog-many-match">

	  <para>Match all messages with a level of

	    <literal>err</literal> or higher, as well as

	    <literal>kern.warning</literal>, <literal>auth.notice</literal>

	    and <literal>mail.crit</literal>, and sends these log messages

	    to the console (<filename>/dev/console</filename>).</para>

	</callout>

	<callout arearefs="co-syslog-one-match">

	  <para>Match all messages from the <literal>mail</literal>

	    facility at level <literal>info</literal> or above, and logs the

	    messages to <filename>/var/log/maillog</filename>.</para>

	</callout>

	<callout arearefs="co-syslog-comparison">

	  <para>This line uses a comparison flag, <literal>=</literal>

	    to only match messages at level <literal>debug</literal>, and

	    logs them in <filename>/var/log/debug.log</filename>.</para>

	</callout>

	<callout arearefs="co-syslog-prog-spec">

	  <para>Here is an example usage of a

	    <emphasis>program specification</emphasis>.  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

	    <command>ppp</command>, but no other programs, end up in

	    <filename>/var/log/ppp.log</filename>.</para>

	</callout>

      </calloutlist>

      <para>This example shows that there are plenty of levels and

	subsystems.  The levels are, in order from most to least

	critical: <literal>emerg</literal>, <literal>alert</literal>,

	<literal>crit</literal>, <literal>err</literal>,

	<literal>warning</literal>, <literal>notice</literal>,

	<literal>info</literal> and <literal>debug</literal>.</para>

      <para>The facilities are, in no particular order:

	<literal>auth</literal>, <literal>authpriv</literal>,

	<literal>console</literal>, <literal>cron</literal>,

	<literal>daemon</literal>, <literal>ftp</literal>,

	<literal>kern</literal>, <literal>lpr</literal>,

	<literal>mail</literal>, <literal>mark</literal>,

	<literal>news</literal>, <literal>security</literal>,

	<literal>syslog</literal>, <literal>user</literal>,

	<literal>uucp</literal> and <literal>local0</literal> through

	<literal>local7</literal>.  Be aware that other operating systems

	might have different facilities.</para>

      <para>With this knowledge it is easy to add a new line to

	<filename>/etc/syslog.conf</filename> to log everything from the

	different daemons on level <literal>notice</literal> and higher to

	<filename>/var/log/daemon.log</filename>. Just add the following:</para>

      <programlisting>daemon.notice                                        /var/log/daemon.log</programlisting>

      <para>For more information about the different levels and facilities,

	refer to &man.syslog.3; and &man.syslogd.8;.  For more information

	about <filename>syslog.conf</filename>, its syntax and more advanced

	usage examples, see &man.syslog.conf.5; and

	<xref linkend="network-syslogd">.</para>

    </sect2>

    <sect2>

      <title>Log management and rotation with

	<application>newsyslog</application></title>

      <indexterm><primary>newsyslog</primary></indexterm>

      <indexterm><primary>newsyslog.conf</primary></indexterm>

      <indexterm><primary>log rotation</primary></indexterm>

      <indexterm><primary>log management</primary></indexterm>

      <para>Log files tend to grow quickly and accumulate steadily.  This

	leads to the files being full of less immediately useful

	information, as well as filling up the hard drive.  To mitigate

	this, log management comes into play.  In &os;, &man.newsyslog.8;

	is the tool used to manage log files.  This program is used to

	periodically rotate and compress log files, as well as optionally

	create missing log files and signal programs when log files are moved.

	The log files do not necessarily have to come from syslog,

	&man.newsyslog.8; works with any logs written from any program.

	It is important to note that <command>newsyslog</command>

	is normally run from &man.cron.8; and is not a system daemon.

	In the default configuration it is run every hour.</para>

      <sect3>

	<title>Configuring <application>newsyslog</application></title>

	<para>To know what actions to take, &man.newsyslog.8; reads its

	  configuration file, by default

	  <filename>/etc/newsyslog.conf</filename>.  This configuration file

	  contains one line for each file that &man.newsyslog.8; manages.

	  Each line states the file owner, permissions, and when to

	  rotate that file, as well as optional flags that affect

	  the log rotation (such as compression) and programs to

	  signal when the log is rotated. As an example, here is

	  the default configuration in &os;:</para>

	<programlisting># configuration file for newsyslog

# $&os;$

#

# 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</programlisting>

	<para>Each line starts with the name of the file to be

	  rotated, optionally followrd by an owner

	  and group for both rotated and newly created files.

	  The next field, <literal>mode</literal> is the mode of the files

	  and <literal>count</literal> denotes how many rotated log files

	  should be kept.  The <literal>size</literal> and

	  <literal>when</literal> fields tell

	  <command>newsyslog</command> when to rotate the file.

	  A log file is rotated when either its size is larger than the

	  <literal>size</literal> field, or when the time in the

	  <literal>when</literal> filed has passed.  <literal>*</literal>

	  means that this field is ignored.  The

	  <replaceable>flags</replaceable> field gives

	  &man.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 <acronym role="Process Identifier">PID</acronym>-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

	  &man.newsyslog.conf.5;.  Remember that

	  <command>newsyslog</command> is run from

	  <command>cron</command> and can not rotate files more

	  often than it is run from &man.cron.8;.</para>

      </sect3>

    </sect2>

  </sect1>