From owner-freebsd-doc@FreeBSD.ORG Thu May 24 15:20:01 2012 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id A95DD106564A for ; Thu, 24 May 2012 15:20:01 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 682E28FC0C for ; Thu, 24 May 2012 15:20:01 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.5/8.14.5) with ESMTP id q4OFK1jf054942 for ; Thu, 24 May 2012 15:20:01 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.5/8.14.5/Submit) id q4OFK1Ln054941; Thu, 24 May 2012 15:20:01 GMT (envelope-from gnats) Resent-Date: Thu, 24 May 2012 15:20:01 GMT Resent-Message-Id: <201205241520.q4OFK1Ln054941@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Niclas Zeising Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id D2A8C1065670 for ; Thu, 24 May 2012 15:17:00 +0000 (UTC) (envelope-from zeising@daemonic.se) Received: from mail.lysator.liu.se (mail.lysator.liu.se [IPv6:2001:6b0:17:f0a0::3]) by mx1.freebsd.org (Postfix) with ESMTP id E02F58FC08 for ; Thu, 24 May 2012 15:16:59 +0000 (UTC) Received: from mail.lysator.liu.se (localhost [127.0.0.1]) by mail.lysator.liu.se (Postfix) with ESMTP id 23BF840023 for ; Thu, 24 May 2012 17:16:59 +0200 (CEST) Received: by mail.lysator.liu.se (Postfix, from userid 1004) id 159BE40012; Thu, 24 May 2012 17:16:59 +0200 (CEST) Received: from mx.daemonic.se (h-45-105.a163.priv.bahnhof.se [94.254.45.105]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.lysator.liu.se (Postfix) with ESMTPSA id 62CCC40023 for ; Thu, 24 May 2012 17:16:57 +0200 (CEST) Received: from mailscanner.daemonic.se (mailscanner.daemonic.se [IPv6:2001:470:dca9:0:1::6]) by mx.daemonic.se (Postfix) with ESMTPS id 3VyvMY0RQkz8ggx for ; Thu, 24 May 2012 17:16:57 +0200 (CEST) Received: from mx.daemonic.se ([10.1.0.3]) (using TLS with cipher CAMELLIA256-SHA) by mailscanner.daemonic.se (mailscanner.daemonic.se [10.1.0.6]) (amavisd-new, port 10025) with ESMTPS id JPBPo92seqXd for ; Thu, 24 May 2012 17:16:49 +0200 (CEST) Received: from mail.daemonic.se (mail.daemonic.se [10.1.0.4]) by mx.daemonic.se (Postfix) with ESMTPS id 3VyvMP24MXz8ggv for ; Thu, 24 May 2012 17:16:49 +0200 (CEST) Received: from vincent.daemonic.se (login.daemonic.se [IPv6:2001:470:dca9:0:1::10]) by mail.daemonic.se (Postfix) with ESMTPS id 3VyvMP1V4Xz9Ctq for ; Thu, 24 May 2012 17:16:49 +0200 (CEST) Received: (from zeising@localhost) by vincent.daemonic.se (8.14.5/8.14.5/Submit) id q4OFGmuu075183; Thu, 24 May 2012 17:16:48 +0200 (CEST) (envelope-from zeising) Message-Id: <201205241516.q4OFGmuu075183@vincent.daemonic.se> Date: Thu, 24 May 2012 17:16:48 +0200 (CEST) From: Niclas Zeising To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/168305: [PATCH] rewrite of the syslogd and newsyslogd parts of the config chapter of the handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Niclas Zeising List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 24 May 2012 15:20:01 -0000 >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 @@ + + + + + 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 logs information to a system logging facility or + other log file. + This section will describe how to configure and use the &os; system + logger, syslogd as well as discuss log rotation + and log management using newsyslog. 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 by + default on startup. This is controlled by the variable + syslogd_enable in /etc/rc.conf. + There are numerous application arguments that affect the behavior of + syslogd. 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; + 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. + Configuring syslogd 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 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 (;). Using + * 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 + 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 +!* + + + + This line matches 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). + + + This line matches all messages from the mail + facility at level info or above, and logs the + messages to /var/log/maillog. + + + This line utilizes a comparison flag, = + to only match all messages at level debug, and + logs them in /var/log/debug.log. + + + 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 + ppp end up in + /var/log/ppp.log. + + + + 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: 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, refer to &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 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 + newsyslog 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, + newsyslog 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 lines, one per log file newsyslog + 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;: + # 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 + + 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, mode is the mode of the files + and count is how many rotated log files that + should be kept. The size and + when fields tells + newsyslog when to rotate the log file. + A log file is rotated once either its size is larger than the + size field specification, or when the time in the + when filed has passed. An asterisk, + * means that this field is ignored. The + flags field gives + newsyslog 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 PID-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 + newsyslog is run from + cron and can not rotate files more often + than when it is run from &man.cron.8;. + + + + + Configuration Files @@ -1618,106 +1885,6 @@ - - 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> --- handbook.config.chapter.syslog.sgml.diff ends here --- >Release-Note: >Audit-Trail: >Unformatted: