Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 24 May 2012 17:16:48 +0200 (CEST)
From:      Niclas Zeising <zeising@daemonic.se>
To:        FreeBSD-gnats-submit@FreeBSD.org
Subject:   docs/168305: [PATCH] rewrite of the syslogd and newsyslogd parts of the config chapter of the handbook
Message-ID:  <201205241516.q4OFGmuu075183@vincent.daemonic.se>
Resent-Message-ID: <201205241520.q4OFK1Ln054941@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help

>Number:         168305
>Category:       docs
>Synopsis:       [PATCH] rewrite of the syslogd and newsyslogd parts of the config chapter of the handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu May 24 15:20:01 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator:     Niclas Zeising
>Release:        FreeBSD 9.0-RELEASE amd64
>Organization:
>Environment:
System: FreeBSD vincent.daemonic.se 9.0-RELEASE FreeBSD 9.0-RELEASE #0 r232364: Fri Mar 2 01:14:23 CET 2012 root@vincent.daemonic.se:/usr/obj/usr/src/sys/VINCENT amd64


	
>Description:
	The parts in the handbook configuration chapter (chapter 12) about configuring syslogd and newsyslog are very short and barely contain any information.
>How-To-Repeat:
	
>Fix:

	Attached patch adds a new part that discusses how to configure syslogd and newsyslogd in more in-depth detail. It is a complete rewrite and removes the old part about the same subject.

--- handbook.config.chapter.syslog.sgml.diff begins here ---
Index: head/en_US.ISO8859-1/books/handbook/config/chapter.sgml
===================================================================
--- head/en_US.ISO8859-1/books/handbook/config/chapter.sgml	(revision 38878)
+++ head/en_US.ISO8859-1/books/handbook/config/chapter.sgml	(working copy)
@@ -1415,6 +1415,273 @@
 
   </sect1>
 
+  <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 logs 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 by
+	default on startup.  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 filed 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 does 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 <application>newsyslog</application>
+	  manages and 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
+# &dollar;&os;&dollar;
+#
+# 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 seen 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> is how many rotated log files that
+	  should be kept.  The <literal>size</literal> and
+	  <literal>when</literal> fields tells
+	  <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 specifies
+	  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>
+
+
   <sect1 id="configtuning-configfiles">
     <title>Configuration Files</title>
 
@@ -1618,106 +1885,6 @@
       </sect3>
     </sect2>
 
-    <sect2>
-      <title>Log File Configuration</title>
-
-      <indexterm><primary>log files</primary></indexterm>
-
-      <sect3>
-	<title><filename>syslog.conf</filename></title>
-
-	<indexterm><primary>syslog.conf</primary></indexterm>
-
-	<para><filename>syslog.conf</filename> is the configuration
-	  file for the &man.syslogd.8; program.  It indicates which
-	  types of <command>syslog</command> messages are logged to
-	  particular log files.</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 syslog.conf(5) manual page.
-*.err;kern.debug;auth.notice;mail.crit          /dev/console
-*.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
-security.*                                      /var/log/security
-mail.info                                       /var/log/maillog
-lpr.info                                        /var/log/lpd-errs
-cron.*                                          /var/log/cron
-*.err                                           root
-*.notice;news.err                               root
-*.alert                                         root
-*.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
-#*.*                                            /var/log/all.log
-# uncomment this to enable logging to a remote log host 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
-!startslip
-*.*                                             /var/log/slip.log
-!ppp
-*.*                                             /var/log/ppp.log</programlisting>
-
-	<para>Consult the &man.syslog.conf.5; manual page for more
-	  information.</para>
-      </sect3>
-
-      <sect3>
-	<title><filename>newsyslog.conf</filename></title>
-
-	<indexterm><primary>newsyslog.conf</primary></indexterm>
-
-	<para><filename>newsyslog.conf</filename> is the configuration
-	  file for &man.newsyslog.8;, a program that is normally
-	  scheduled to run by &man.cron.8;.  &man.newsyslog.8;
-	  determines when log files require archiving or rearranging.
-	  <filename>logfile</filename> is moved to
-	  <filename>logfile.0</filename>,
-	  <filename>logfile.0</filename> is moved to
-	  <filename>logfile.1</filename>, and so on.  Alternatively,
-	  the log files may be archived in &man.gzip.1; format causing
-	  them to be named: <filename>logfile.0.gz</filename>,
-	  <filename>logfile.1.gz</filename>, and so on.</para>
-
-	<para><filename>newsyslog.conf</filename> indicates which log
-	  files are to be managed, how many are to be kept, and when
-	  they are to be touched.  Log files can be rearranged and/or
-	  archived when they have either reached a certain size, or at
-	  a certain periodic time/date.</para>
-
-	<programlisting># configuration file for newsyslog
-# &dollar;&os;&dollar;
-#
-# filename          [owner:group]    mode count size when [ZB] [/pid_file] [sig_num]
-/var/log/cron                           600  3     100  *     Z
-/var/log/amd.log                        644  7     100  *     Z
-/var/log/kerberos.log                   644  7     100  *     Z
-/var/log/lpd-errs                       644  7     100  *     Z
-/var/log/maillog                        644  7     *    @T00  Z
-/var/log/sendmail.st                    644  10    *    168   B
-/var/log/messages                       644  5     100  *     Z
-/var/log/all.log                        600  7     *    @T00  Z
-/var/log/slip.log                       600  3     100  *     Z
-/var/log/ppp.log                        600  3     100  *     Z
-/var/log/security                       600  10    100  *     Z
-/var/log/wtmp                           644  3     *    @01T05 B
-/var/log/daily.log                      640  7     *    @T00  Z
-/var/log/weekly.log                     640  5     1    $W6D0 Z
-/var/log/monthly.log                    640  12    *    $M1D0 Z
-/var/log/console.log                    640  5     100  *     Z</programlisting>
-
-	<para>Consult the &man.newsyslog.8; manual page for more
-	  information.</para>
-      </sect3>
-    </sect2>
-
     <sect2 id="configtuning-sysctlconf">
       <title><filename>sysctl.conf</filename></title>
 
--- handbook.config.chapter.syslog.sgml.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted:



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205241516.q4OFGmuu075183>