From owner-svn-doc-head@FreeBSD.ORG Sat Jun 2 21:43:11 2012 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 94C43106564A; Sat, 2 Jun 2012 21:43:11 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 7D27F8FC12; Sat, 2 Jun 2012 21:43:11 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q52LhBpZ015609; Sat, 2 Jun 2012 21:43:11 GMT (envelope-from bcr@svn.freebsd.org) Received: (from bcr@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q52LhBiJ015607; Sat, 2 Jun 2012 21:43:11 GMT (envelope-from bcr@svn.freebsd.org) Message-Id: <201206022143.q52LhBiJ015607@svn.freebsd.org> From: Benedict Reuschling Date: Sat, 2 Jun 2012 21:43:11 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r38967 - head/en_US.ISO8859-1/books/handbook/config X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 02 Jun 2012 21:43:11 -0000 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 + + + + + Niclas + Zeising + Contributed by + + + + + Configuring the system logger + <application>syslogd</application> + + system logging + syslog + syslogd + + 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. + + 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 syslogd on + a local machine. For more advanced setups using a separate + loghost, see . + + + Using <application>syslogd</application> + + In the default &os; configuration &man.syslogd.8; is + started at boot. This is controlled by the variable + syslogd_enable in + /etc/rc.conf. There are numerous + application arguments that affect the behavior of + &man.syslogd.8;. To change them, use + syslogd_flags in + /etc/rc.conf. Refer to &man.syslogd.8; + for more information on the arguments, and &man.rc.conf.5;, + and for more information about + /etc/rc.conf and the &man.rc.8; + subsystem. + + + + Configuring <application>syslogd</application> + + syslog.conf + + The configuration file, by default + /etc/syslog.conf, 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 + 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 hostname of the machine generating + the logging event. + + 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 + facility.level and this will match + log messages from facility at level + level 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 (;). Using + * 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 syslog.conf from &os;: + + # $&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 +*.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 +lpr.info /var/log/lpd-errs +ftp.info /var/log/xferlog +cron.* /var/log/cron +*.=debug /var/log/debug.log +*.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 +*.* /var/log/ppp.log +!* + + + + Match all messages with a level of + err or higher, as well as + kern.warning, + auth.notice and + mail.crit, and sends these log messages + to the console (/dev/console). + + + + Match all messages from the mail + facility at level info or above, and + logs the messages to + /var/log/maillog. + + + + This line uses a comparison flag, = + to only match messages at level debug, + and logs them in + /var/log/debug.log. + + + + Here is an example usage of a + program specification. 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 + ppp, but no other programs, end up in + /var/log/ppp.log. + + + + This example shows that there are plenty of levels and + subsystems. The levels are, in order from most to least + critical: emerg, alert, + crit, err, + warning, notice, + info and debug. + + The facilities are, in no particular order: + auth, authpriv, + console, cron, + daemon, ftp, + kern, lpr, + mail, mark, + news, security, + syslog, user, + uucp and local0 through + local7. Be aware that other operating + systems might have different facilities. + + With this knowledge it is easy to add a new line to + /etc/syslog.conf to log everything from + the different daemons on level notice and + higher to /var/log/daemon.log. Just add + the following: + + daemon.notice /var/log/daemon.log + + For more information about the different levels and + facilities, refer to &man.syslog.3; and &man.syslogd.8;. + For more information about syslog.conf, + its syntax and more advanced usage examples, see + &man.syslog.conf.5; and . + + + + Log management and rotation with + <application>newsyslog</application> + + newsyslog + newsyslog.conf + log rotation + log management + + 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 newsyslog is normally run from + &man.cron.8; and is not a system daemon. In the default + configuration it is run every hour. + + + Configuring + <application>newsyslog</application> + + To know what actions to take, &man.newsyslog.8; reads + its configuration file, by default + /etc/newsyslog.conf. 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;: + + # 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 + + 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, mode is the mode of the + files and count denotes how many rotated + log files should be kept. The size and + when fields tell + newsyslog when to rotate the file. + A log file is rotated when either its size is larger than + the size field, or when the time in the + when filed has passed. + * means that this field is ignored. The + flags 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 PID-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 + newsyslog is run from + cron and can not rotate files more + often than it is run from &man.cron.8;. + + + + Configuration Files @@ -1618,106 +1915,6 @@ nameserver 147.11.100.30 - - Log File Configuration - - log files - - - <filename>syslog.conf</filename> - - syslog.conf - - syslog.conf is the configuration - file for the &man.syslogd.8; program. It indicates which - types of syslog messages are logged to - particular log files. - - # $&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 - - Consult the &man.syslog.conf.5; manual page for more - information. - - - - <filename>newsyslog.conf</filename> - - newsyslog.conf - - newsyslog.conf 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. - logfile is moved to - logfile.0, - logfile.0 is moved to - logfile.1, and so on. Alternatively, - the log files may be archived in &man.gzip.1; format causing - them to be named: logfile.0.gz, - logfile.1.gz, and so on. - - newsyslog.conf 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. - - # 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 - - Consult the &man.newsyslog.8; manual page for more - information. - - - <filename>sysctl.conf</filename>