From zeising@daemonic.se  Thu May 24 15:17:00 2012
Return-Path: <zeising@daemonic.se>
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id D2A8C1065670
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 15:17:00 +0000 (UTC)
	(envelope-from zeising@daemonic.se)
Received: from mail.lysator.liu.se (mail.lysator.liu.se [IPv6:2001:6b0:17:f0a0::3])
	by mx1.freebsd.org (Postfix) with ESMTP id E02F58FC08
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 15:16:59 +0000 (UTC)
Received: from mail.lysator.liu.se (localhost [127.0.0.1])
	by mail.lysator.liu.se (Postfix) with ESMTP id 23BF840023
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 17:16:59 +0200 (CEST)
Received: by mail.lysator.liu.se (Postfix, from userid 1004)
	id 159BE40012; Thu, 24 May 2012 17:16:59 +0200 (CEST)
Received: from mx.daemonic.se (h-45-105.a163.priv.bahnhof.se [94.254.45.105])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mail.lysator.liu.se (Postfix) with ESMTPSA id 62CCC40023
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 17:16:57 +0200 (CEST)
Received: from mailscanner.daemonic.se (mailscanner.daemonic.se [IPv6:2001:470:dca9:0:1::6])
	by mx.daemonic.se (Postfix) with ESMTPS id 3VyvMY0RQkz8ggx
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 17:16:57 +0200 (CEST)
Received: from mx.daemonic.se ([10.1.0.3]) (using TLS with cipher CAMELLIA256-SHA)
	by mailscanner.daemonic.se (mailscanner.daemonic.se [10.1.0.6]) (amavisd-new, port 10025)
	with ESMTPS id JPBPo92seqXd for <FreeBSD-gnats-submit@freebsd.org>;
	Thu, 24 May 2012 17:16:49 +0200 (CEST)
Received: from mail.daemonic.se (mail.daemonic.se [10.1.0.4])
	by mx.daemonic.se (Postfix) with ESMTPS id 3VyvMP24MXz8ggv
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 17:16:49 +0200 (CEST)
Received: from vincent.daemonic.se (login.daemonic.se [IPv6:2001:470:dca9:0:1::10])
	by mail.daemonic.se (Postfix) with ESMTPS id 3VyvMP1V4Xz9Ctq
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 24 May 2012 17:16:49 +0200 (CEST)
Received: (from zeising@localhost)
	by vincent.daemonic.se (8.14.5/8.14.5/Submit) id q4OFGmuu075183;
	Thu, 24 May 2012 17:16:48 +0200 (CEST)
	(envelope-from zeising)
Message-Id: <201205241516.q4OFGmuu075183@vincent.daemonic.se>
Date: Thu, 24 May 2012 17:16:48 +0200 (CEST)
From: Niclas Zeising <zeising@daemonic.se>
Reply-To: Niclas Zeising <zeising@daemonic.se>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] rewrite of the syslogd and newsyslogd parts of the config chapter of the handbook
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>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:    bcr
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu May 24 15:20:01 UTC 2012
>Closed-Date:    Sat Jun 02 21:58:53 UTC 2012
>Last-Modified:  Sun Mar 17 18:36:26 UTC 2013
>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:
Responsible-Changed-From-To: freebsd-doc->bcr
Responsible-Changed-By: bcr 
Responsible-Changed-When: Thu May 24 16:49:05 UTC 2012 
Responsible-Changed-Why:  


http://www.freebsd.org/cgi/query-pr.cgi?pr=168305 

From: Niclas Zeising <zeising@daemonic.se>
To: bug-followup@FreeBSD.org, zeising@daemonic.se
Cc:  
Subject: Re: docs/168305: [PATCH] rewrite of the syslogd and newsyslogd parts
 of the config chapter of the handbook
Date: Thu, 24 May 2012 22:24:04 +0200

 This is a multi-part message in MIME format.
 --------------030205010503040704080904
 Content-Type: text/plain; charset=ISO-8859-1; format=flowed
 Content-Transfer-Encoding: 7bit
 
 Here is an updated patch with changes based on comments from bcr@.
 Regards!
 -- 
 Niclas Zeising
 
 --------------030205010503040704080904
 Content-Type: text/plain;
  name="handbook.config.chapter.syslog.sgml.diff"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment;
  filename="handbook.config.chapter.syslog.sgml.diff"
 
 Index: head/en_US.ISO8859-1/books/handbook/config/chapter.sgml
 ===================================================================
 --- head/en_US.ISO8859-1/books/handbook/config/chapter.sgml	(revision 38879)
 +++ head/en_US.ISO8859-1/books/handbook/config/chapter.sgml	(working copy)
 @@ -1415,6 +1415,275 @@
  
    </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 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
 +# &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 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>
 +
 +
    <sect1 id="configtuning-configfiles">
      <title>Configuration Files</title>
  
 @@ -1618,106 +1887,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>
  
 
 --------------030205010503040704080904--

From: Niclas Zeising <zeising@daemonic.se>
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/168305: [PATCH] rewrite of the syslogd and newsyslogd parts
 of the config chapter of the handbook
Date: Wed, 30 May 2012 22:57:42 +0200

 This is a multi-part message in MIME format.
 --------------090004030403090707090404
 Content-Type: text/plain; charset=ISO-8859-1; format=flowed
 Content-Transfer-Encoding: 7bit
 
 Here is another version of the patch, thanks to Warren Block for the 
 comments!
 Regards!
 -- 
 Niclas Zeising
 
 --------------090004030403090707090404
 Content-Type: text/plain;
  name="handbook.config.chapter.syslog.sgml.diff"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment;
  filename="handbook.config.chapter.syslog.sgml.diff"
 
 Index: head/en_US.ISO8859-1/books/handbook/config/chapter.sgml
 ===================================================================
 --- head/en_US.ISO8859-1/books/handbook/config/chapter.sgml	(revision 38946)
 +++ head/en_US.ISO8859-1/books/handbook/config/chapter.sgml	(working copy)
 @@ -1415,6 +1415,281 @@
  
    </sect1>
  
 +  <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
 +# &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>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>
 +
 +
    <sect1 id="configtuning-configfiles">
      <title>Configuration Files</title>
  
 @@ -1618,106 +1893,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>
  
 
 --------------090004030403090707090404--
State-Changed-From-To: open->closed 
State-Changed-By: bcr 
State-Changed-When: Sat Jun 2 21:54:35 UTC 2012 
State-Changed-Why:  
Reviewed patch committed. Thanks for doing the intial work, Niclas, as well as  
the updates based on mine and wblock's suggestions. PR closed!  


http://www.freebsd.org/cgi/query-pr.cgi?pr=168305 
>Unformatted:
