Attachment 124802 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.43 KB, created by Niclas Zeising on 2012-05-30 21:57:42 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Niclas Zeising

Created: 2012-05-30 21:57:42 UTC

Size: 19.43 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 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>
>+	  
>+	</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>
>

Actions: View | Diff

Attachments on bug 168305: 124800 | 124801 | 124802