Attachment 124800 Details for Bug 168305 – handbook.config.chapter.syslog.sgml.diff

[patch] handbook.config.chapter.syslog.sgml.diff

handbook.config.chapter.syslog.sgml.diff (text/plain), 19.61 KB, created by Niclas Zeising on 2012-05-24 16:20:01 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Niclas Zeising

Created: 2012-05-24 16:20:01 UTC

Size: 19.61 KB

patch

obsolete

>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>
>+	  
>+	</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>

Actions: View | Diff

Attachments on bug 168305: 124800 | 124801 | 124802