<sect1 id="configtuning-syslog">

    <sect1info>

      <authorgroup>

	<author>

	  <firstname>Niclas</firstname>

	  <surname>Zeising</surname>

	  <contrib>Contributed by </contrib>

	  <!-- 24 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, <application>syslogd</application> as well as discuss log rotation

      and log management using <application>newsyslog</application>.  Focus

      will be on setting up and using <application>syslogd</application> 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

	when the system boots.  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

	<application>syslogd</application>.  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;

	should do 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 host of the machine generating

	the logging event.</para>

      <para>Configuring <application>syslogd</application> 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

	<literal>facility.level</literal> and this will match log messages

	from <literal>facility</literal> at level <literal>level</literal> or

	higher.  It is also possible to add an optional comparison flag

	before the level to be able to specify more exact 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 is where to send the log message, e.g. 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-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 <co id="co-syslog-2">

lpr.info                                        /var/log/lpd-errs

ftp.info                                        /var/log/xferlog

cron.*                                          /var/log/cron

*.=debug                                        /var/log/debug.log <co id="co-syslog-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 <co id="co-syslog-4">

*.*                                             /var/log/ppp.log

!*</programlisting>

      <calloutlist>

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

	  <para>This line matches 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-2">

	  <para>This line matches 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-3">

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

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

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

	</callout>

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

	  <para>This line uses a so called program specification, which means

	    that the block following that to the next program specification

	    will only match for messages from that program.  In this example

	    this line and the following will make all messages from

	    <application>ppp</application> end up in

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

	</callout>

      </calloutlist>

      <para>As can be seen from the configuration file above, 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 notice 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, refer to &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 log 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.  The

	<application>newsyslog</application> application 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,

	<application>newsyslog</application> works with any logs written from

	any program.  It is important to note that

	<application>newsyslog</application> 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 lines, one per log file that

	  <application>newsyslog</application> manages.  It states the file

	  owner, permissions and when to rotate that file, as well as optional

	  flags that affects 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>As shown above, each line starts with the name of the

	  log file to be rotated.  This is followed by an optional owner

	  and group specification of 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

	  <application>newsyslog</application> when to rotate the log file.

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

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

	  <literal>when</literal> filed has passed. An asterisk,

	  <literal>*</literal> means that this field is ignored.  The

	  <literal>flags</literal> field gives

	  <application>newsyslog</application> 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

	  a <acronym role="Process Identifier">PID</acronym>-file of a process

	  as well as a signal number to signal that process with when the log

	  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 also that

	  <application>newsyslog</application> is run from

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

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

      </sect3>

    </sect2>

  </sect1>