Documentation update

syslog.conf.5

@@ -1,5 +1,5 @@
 .\" syslog.conf - syslogd(8) configuration file
-.\" Copyright (c) 1995-2007  Martin Schulze <joey@infodrom.org>
+.\" Copyright (c) 1995-2009  Martin Schulze <joey@infodrom.org>
 .\" 
 .\" This file is part of the sysklogd package, a kernel and system log daemon.
 .\" 
@@ -17,13 +17,13 @@
 .\" along with this program; if not, write to the Free Software
 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
 .\"
-.TH SYSLOG.CONF 5 "30 November 2006" "Version 1.3" "Linux System Administration"
+.TH SYSLOG.CONF 5 "27 November 2009" "Version 1.5" "Linux System Administration"
 .SH NAME
 syslog.conf \- syslogd(8) configuration file
 .SH DESCRIPTION
 The
 .I syslog.conf
-file is the main configuration file for the
+file is the main configuration file for
 .BR syslogd (8)
 which logs system messages on *nix systems.  This file specifies rules
 for logging.  For special features see the
@@ -40,20 +40,24 @@ priorities belonging to the specified action.
 
 Lines starting with a hash mark (``#'') and empty lines are ignored.
 
-This release of
+This variant of
 .B syslogd
-is able to understand an extended syntax.  One rule can be divided
+is able to understand a slightly extended syntax compared to the
+original BSD syslogd.
+One rule may be divided
 into several lines if the leading line is terminated with an backslash
 (``\\'').
 .SH SELECTORS
-The selector field itself again consists of two parts, a
+The selector field consists of two parts, a
 .I facility
 and a 
 .IR priority ,
 separated by a period (``.'').
 Both parts are case insensitive and can also be specified as decimal
-numbers, but don't do that, you have been warned.  Both facilities and
+numbers corresponding to the definitions in
-priorities are described in 
+.IR /usr/include/syslog.h .
+It is safer to use symbolic names rather than decimal numbers.
+Both facilities and priorities are described in 
 .BR syslog (3).
 The names mentioned below correspond to the similar 
 .BR LOG_ -values
@@ -68,15 +72,14 @@ is one of the following keywords:
 .BR syslog ", " user ", " uucp " and " local0 " through " local7 .
 The keyword 
 .B security
-should not be used anymore and
+is deprecated and
 .B mark
 is only for internal use and therefore should not be used in
-applications.  Anyway, you may want to specify and redirect these
+applications.  The
-messages here.  The
 .I facility
-specifies the subsystem that produced the message, i.e. all mail
+specifies the subsystem that produced the message, e.g. all mail
 programs log with the mail facility
-.BR "" ( LOG_MAIL )
+.RB ( LOG_MAIL )
 if they log using syslog.
 
 In most cases anyone can log to any facility, so we rely on convention
@@ -112,18 +115,17 @@ all facilities or all priorities, depending on where it is used
 .B none
 stands for no priority of the given facility.
 
-You can specify multiple facilities with the same priority pattern in
+Multiple facilities may be specified for a single priority pattern in
-one statement using the comma (``,'') operator.  You may specify as
+one statement using the comma (``,'') operator to separate the
-many facilities as you want.  Please note that only the facility part from
+facilities.  You may specify as many facilities as you want.
-such a statement is taken, a priority part would be skipped.
+Please note that only the facility part from
+such a statement is taken, a priority part would be ignored.
 
 Multiple selectors may be specified for a single
 .I action
-using the semicolon (``;'') separator.  Please note that each selector in
+using the semicolon (``;'') separator.  Selectors are processed from
-the 
+left to right, with each selector being able to overwrite preceding ones.
-.I selector
+Using this behavior you are able to exclude some priorities from the pattern.
-field is capable of overwriting the preceding ones.  Using this
-behavior you can exclude some priorities from the pattern.
 
 This 
 .BR syslogd (8)
@@ -151,12 +153,12 @@ The action field of a rule describes the abstract term
 provides the following actions.
 
 .SS Regular File
-Typically messages are logged to real files.  The file has to be
+Typically messages are logged to real files.
-specified with full pathname, beginning with a slash ``/''.
+The filename is specified with an absolute pathname.
 
-You may prefix each entry with the minus ``-'' sign to omit syncing
+You may prefix each entry with a minus sign (``-'') to avoid syncing
-the file after every logging.  Note that you might lose information if
+the file after each log message.  Note that you might lose information if
-the system crashes right behind a write attempt.  Nevertheless this
+the system crashes right after a write attempt.  Nevertheless this
 might give you back some performance, especially if you run programs
 that use logging in a very verbose manner.
 
@@ -189,14 +191,21 @@ host won't forward the message again, it will just log them
 locally.  To forward messages to another host, prepend the hostname
 with the at sign (``@'').
 
-Using this feature you're able to control all syslog messages on one
+Using this feature you are able to collect all syslog messages on a
-host, if all other machines will log remotely to that.  This tears down
+central host, if all other machines log remotely to that one.  This
-administration needs.
+reduces administration needs.
+
+Using a named pipe log method, messages from remote hosts can be sent
+to a log program.  By reading log messages line by line such a program
+is able to sort log messages by host name or program name on the
+central log host.  This way it is possible to split the log into
+separate files.
 
 .SS List of Users
 Usually critical messages are also directed to ``root'' on that
-machine.  You can specify a list of users that shall get the message by
+machine.  You can specify a list of users that ought to receive the
-simply writing the username.  You may specify more than one user by
+log message on the terminal by writing their usernames.
+You may specify more than one user by
 separating the usernames with commas (``,'').  If they're logged in they
 will receive the log messages.
 
@@ -207,9 +216,11 @@ this
 .IR wall (1)-feature
 use an asterisk (``*'').
 .SH EXAMPLES
-Here are some example, partially taken from a real existing site and
+Here are some examples, partially taken from a real existing site and
-configuration.  Hopefully they rub out all questions on the
+configuration.  Hopefully they answer all questions about
-configuration, if not, drop me (Joey) a line.
+configuring this
+.BR syslogd (8) .
+If not, don't hesitate to contact the mailing list.
 .IP
 .nf
 # Store critical stuff in critical
@@ -217,16 +228,16 @@ configuration, if not, drop me (Joey) a line.
 *.=crit;kern.none            /var/adm/critical
 .fi
 .LP
-This will store all messages with the priority
+This will store all messages of priority
 .B crit
 in the file
 .IR /var/adm/critical ,
-except for any kernel message.
+with the exception of any kernel messages.
 
 .IP
 .nf
-# Kernel messages are first, stored in the kernel
+# Kernel messages are stored in the kernel file,
-# file, critical messages and higher ones also go
+# critical messages and higher ones also go
 # to another host and to the console
 #
 kern.*                       /var/adm/kernel
@@ -240,24 +251,32 @@ file
 .IR /var/adm/kernel .
 (But recall that only the kernel itself can log to this facility.)
 
-The second statement directs all kernel messages of the priority
+The second statement directs all kernel messages of priority
 .B crit
 and higher to the remote host finlandia.  This is useful, because if
 the host crashes and the disks get irreparable errors you might not be
 able to read the stored messages.  If they're on a remote host, too,
 you still can try to find out the reason for the crash.
 
-The third rule directs these messages to the actual console, so the
+The third rule directs kernel messages of priority crit and higher to
-person who works on the machine will get them, too.
+the actual console, so the person who works on the machine will get
+them, too.
 
 The fourth line tells the syslogd to save all kernel messages that
 come with priorities from
 .BR info " up to " warning
 in the file
 .IR /var/adm/kernel-info .
-Everything from
+
-.I err
+This is an example of the 2nd selector overwriting part of the first
-and higher is excluded.
+one.  The first selector selects kernel messages of priority
+.BR info
+and higher.  The second selector filters out kernel messages of
+priority
+.BR error
+and higher.  This leaves just priorities
+.BR info ", " notice " and " warning
+to get logged.
 
 .IP
 .nf
@@ -267,7 +286,7 @@ and higher is excluded.
 mail.=info                   /dev/tty12
 .fi
 .LP
-This directs all messages that uses 
+This directs all messages that use 
 .BR mail.info " (in source " LOG_MAIL " | " LOG_INFO )
 to
 .IR /dev/tty12 , 
@@ -277,7 +296,7 @@ uses this as its default.
 
 .IP
 .nf
-# Store all mail concerning stuff in a file
+# Write all mail related logs to a file
 #
 mail.*;mail.!=info           /var/adm/mail
 .fi
@@ -357,7 +376,7 @@ is the wall action.
 *.alert                      root,joey
 .fi
 .LP
-This rule directs all messages with a priority of
+This rule directs all messages of priority
 .B alert
 or higher to the terminals of the operator, i.e. of the users ``root''
 and ``joey'' if they're logged in.
@@ -392,6 +411,22 @@ The effects of multiple selectors are sometimes not intuitive.  For
 example ``mail.crit,*.err'' will select ``mail'' facility messages at
 the level of ``err'' or higher, not at the level of ``crit'' or
 higher.
+
+Also, if you specify a selector with an exclamation mark in it
+which isn't preceded by a corresponding selector without an
+exclamation mark, nothing will be logged.  Intuitively, the
+selector ``ftp.!alert'' on its own will select all ftp messages
+with priorities less than alert.  In fact it selects nothing.
+Similarly ``ftp.!=alert'' might reasonably be expected to select
+all ftp messages other than those with priority alert, but again
+it selects nothing.  It seems the selectors with exclamation
+marks in them should only be used as `filters' following
+selectors without exclamation marks.
+
+Finally, using a backslash to divide a line into two doesn't
+work if the backslash is used immediately after the end of the
+selector, without intermediate whitespace.
+
 .SH SEE ALSO
 .BR sysklogd (8),
 .BR klogd (8),