Date: Sat, 2 Jun 2012 21:43:11 +0000 (UTC) From: Benedict Reuschling <bcr@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r38967 - head/en_US.ISO8859-1/books/handbook/config Message-ID: <201206022143.q52LhBiJ015607@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: bcr Date: Sat Jun 2 21:43:10 2012 New Revision: 38967 URL: http://svn.freebsd.org/changeset/doc/38967 Log: This change adds much more information about syslogd and newsyslog than we had before in the configuration chapter. It describes how the system logger can be configured, the rationale behind it and the most important field that the user should edit. PR: docs/168305 Submitted by: Niclas Zeising (zeising daemonic se) Reviewed by: wblock@, myself Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.sgml Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.sgml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/config/chapter.sgml Sat Jun 2 19:28:33 2012 (r38966) +++ head/en_US.ISO8859-1/books/handbook/config/chapter.sgml Sat Jun 2 21:43:10 2012 (r38967) @@ -1415,6 +1415,303 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n </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># $&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-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 +# $&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>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 +1915,6 @@ nameserver 147.11.100.30</programlisting </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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201206022143.q52LhBiJ015607>