Date: Thu, 24 May 2012 17:16:48 +0200 (CEST) From: Niclas Zeising <zeising@daemonic.se> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/168305: [PATCH] rewrite of the syslogd and newsyslogd parts of the config chapter of the handbook Message-ID: <201205241516.q4OFGmuu075183@vincent.daemonic.se> Resent-Message-ID: <201205241520.q4OFK1Ln054941@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 168305
>Category: docs
>Synopsis: [PATCH] rewrite of the syslogd and newsyslogd parts of the config chapter of the handbook
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: update
>Submitter-Id: current-users
>Arrival-Date: Thu May 24 15:20:01 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator: Niclas Zeising
>Release: FreeBSD 9.0-RELEASE amd64
>Organization:
>Environment:
System: FreeBSD vincent.daemonic.se 9.0-RELEASE FreeBSD 9.0-RELEASE #0 r232364: Fri Mar 2 01:14:23 CET 2012 root@vincent.daemonic.se:/usr/obj/usr/src/sys/VINCENT amd64
>Description:
The parts in the handbook configuration chapter (chapter 12) about configuring syslogd and newsyslog are very short and barely contain any information.
>How-To-Repeat:
>Fix:
Attached patch adds a new part that discusses how to configure syslogd and newsyslogd in more in-depth detail. It is a complete rewrite and removes the old part about the same subject.
--- handbook.config.chapter.syslog.sgml.diff begins here ---
Index: head/en_US.ISO8859-1/books/handbook/config/chapter.sgml
===================================================================
--- head/en_US.ISO8859-1/books/handbook/config/chapter.sgml (revision 38878)
+++ head/en_US.ISO8859-1/books/handbook/config/chapter.sgml (working copy)
@@ -1415,6 +1415,273 @@
</sect1>
+ <sect1 id="configtuning-syslog">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Niclas</firstname>
+ <surname>Zeising</surname>
+ <contrib>Contributed by </contrib>
+ <!-- 24 May 2012 -->
+ </author>
+ </authorgroup>
+ </sect1info>
+
+ <title>Configuring the system logger <application>syslogd</application></title>
+
+ <indexterm><primary>system logging</primary></indexterm>
+ <indexterm><primary>syslog</primary></indexterm>
+ <indexterm><primary>syslogd</primary></indexterm>
+
+ <para>System logging is an important aspect of system administration.
+ It is used both to detect hardware and software issues and errors in
+ the system, as well as playing a very important role in security
+ auditing and incident response. System daemons without a controlling
+ terminal also usually logs information to a system logging facility or
+ other log file.</para>
+ <para>This section will describe how to configure and use the &os; system
+ logger, <application>syslogd</application> as well as discuss log rotation
+ and log management using <application>newsyslog</application>. Focus
+ will be on setting up and using <application>syslogd</application> on
+ a local machine. For more advanced setups using a separate loghost, see
+ <xref linkend="network-syslogd">.</para>
+
+ <sect2>
+ <title>Using <application>syslogd</application></title>
+ <para>In the default &os; configuration &man.syslogd.8; is started by
+ default on startup. This is controlled by the variable
+ <literal>syslogd_enable</literal> in <filename>/etc/rc.conf</filename>.
+ There are numerous application arguments that affect the behavior of
+ <application>syslogd</application>. To change them, use
+ <literal>syslogd_flags</literal> in <filename>/etc/rc.conf</filename>.
+ Refer to &man.syslogd.8; for more information on the arguments, and
+ &man.rc.conf.5;, <xref linkend="configtuning-core-configuration">
+ and <xref linkend="configtuning-rcd"> for more information about
+ <filename>/etc/rc.conf</filename> and the &man.rc.8; subsystem.</para>
+ </sect2>
+
+ <sect2>
+ <title>Configuring <application>syslogd</application></title>
+
+ <indexterm><primary>syslog.conf</primary></indexterm>
+
+ <para>The configuration file, by default
+ <filename>/etc/syslog.conf</filename>, controls what &man.syslogd.8;
+ should do with the log entries once they are received. There are
+ several parameters to control the handling of incoming events, of
+ which the most basic are facility and level. The facility describes
+ which subsystem generated the message, such as the kernel or a daemon,
+ and the level describes the severity of the event that occurred. This
+ makes it possible to log the message to different log files, or
+ discard it, depending on the facility and level. It is also possible
+ to take action depending on the application that sent the message, and
+ in the case of remote logging, also the host of the machine generating
+ the logging event.</para>
+ <para>Configuring <application>syslogd</application> is quite straight
+ forward. The configuration file contains one line per action, and
+ the syntax for each line is a selector field followed by an action
+ field. The syntax of the selector field is
+ <literal>facility.level</literal> and this will match log messages
+ from <literal>facility</literal> at level <literal>level</literal> or
+ higher. It is also possible to add an optional comparison flag
+ before the level to be able to specify more exact what is logged.
+ Multiple selector fields can be used for the same action, and are
+ separated with a semicolon (<literal>;</literal>). Using
+ <literal>*</literal> will match everything.
+ The action filed is where to send the log message, e.g. a file or
+ a remote log host. As an example, here is the default
+ <filename>syslog.conf</filename> from &os;:</para>
+ <programlisting># $&os;$
+#
+# 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
+# $&os;$
+#
+# Entries which do not specify the '/pid_file' field will cause the
+# syslogd process to be signalled when that log file is rotated. This
+# action is only appropriate for log files which are written to by the
+# syslogd process (ie, files listed in /etc/syslog.conf). If there
+# is no process which needs to be signalled when a given log file is
+# rotated, then the entry for that file should include the 'N' flag.
+#
+# The 'flags' field is one or more of the letters: BCDGJNUXZ or a '-'.
+#
+# Note: some sites will want to select more restrictive protections than the
+# defaults. In particular, it may be desirable to switch many of the 644
+# entries to 640 or 600. For example, some sites will consider the
+# contents of maillog, messages, and lpd-errs to be confidential. In the
+# future, these defaults may change to more conservative ones.
+#
+# logfilename [owner:group] mode count size when flags [/pid_file] [sig_num]
+/var/log/all.log 600 7 * @T00 J
+/var/log/amd.log 644 7 100 * J
+/var/log/auth.log 600 7 100 @0101T JC
+/var/log/console.log 600 5 100 * J
+/var/log/cron 600 3 100 * JC
+/var/log/daily.log 640 7 * @T00 JN
+/var/log/debug.log 600 7 100 * JC
+/var/log/init.log 644 3 100 * J
+/var/log/kerberos.log 600 7 100 * J
+/var/log/lpd-errs 644 7 100 * JC
+/var/log/maillog 640 7 * @T00 JC
+/var/log/messages 644 5 100 @0101T JC
+/var/log/monthly.log 640 12 * $M1D0 JN
+/var/log/pflog 600 3 100 * JB /var/run/pflogd.pid
+/var/log/ppp.log root:network 640 3 100 * JC
+/var/log/security 600 10 100 * JC
+/var/log/sendmail.st 640 10 * 168 B
+/var/log/utx.log 644 3 * @01T05 B
+/var/log/weekly.log 640 5 1 $W6D0 JN
+/var/log/xferlog 600 7 100 * JC</programlisting>
+
+ <para>As 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># $&os;$
-#
-# 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
-# $&os;$
-#
-# filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
-/var/log/cron 600 3 100 * Z
-/var/log/amd.log 644 7 100 * Z
-/var/log/kerberos.log 644 7 100 * Z
-/var/log/lpd-errs 644 7 100 * Z
-/var/log/maillog 644 7 * @T00 Z
-/var/log/sendmail.st 644 10 * 168 B
-/var/log/messages 644 5 100 * Z
-/var/log/all.log 600 7 * @T00 Z
-/var/log/slip.log 600 3 100 * Z
-/var/log/ppp.log 600 3 100 * Z
-/var/log/security 600 10 100 * Z
-/var/log/wtmp 644 3 * @01T05 B
-/var/log/daily.log 640 7 * @T00 Z
-/var/log/weekly.log 640 5 1 $W6D0 Z
-/var/log/monthly.log 640 12 * $M1D0 Z
-/var/log/console.log 640 5 100 * Z</programlisting>
-
- <para>Consult the &man.newsyslog.8; manual page for more
- information.</para>
- </sect3>
- </sect2>
-
<sect2 id="configtuning-sysctlconf">
<title><filename>sysctl.conf</filename></title>
--- handbook.config.chapter.syslog.sgml.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205241516.q4OFGmuu075183>