rsyslogd man page added, default config file name changed to rsyslog.conf

1 files changed, 130 insertions, 229 deletions

diff --git a/rsyslogd.8 b/rsyslogd.8
index 777757d2..4b697f96 100644
--- a/rsyslogd.8
+++ b/rsyslogd.8
@@ -1,11 +1,11 @@
 .\" Copyright 2004 Rainer Gerhards and Adiscon for the rsyslog modifications
 .\" May be distributed under the GNU General Public License
 .\"
-.TH RSYSLOGD 8 "24 November 2004" "Version 0.8" "Linux System Administration"
+.TH RSYSLOGD 8 "18 March 2005" "Version 0.8" "Linux System Administration"
 .SH NAME
-rsyslog \- reliable and extended syslogd 
+rsyslogd \- reliable and extended syslogd 
 .SH SYNOPSIS
-.B syslogd
+.B rsyslogd
 .RB [ " \-a "
 .I socket
 ]
@@ -31,21 +31,17 @@ rsyslog \- reliable and extended syslogd
 .RB [ " \-v " ]
 .LP
 .SH DESCRIPTION
-.B rsyslogd
-provides two system utilities which provide support for
-system logging and kernel message trapping.  Support of both internet and
-unix domain sockets enables this utility package to support both local
+.B Rsyslogd
+is a system utility providing support for message logging.
+Support of both internet and
+unix domain sockets enables this utility to support both local
 and remote logging.
 
-System logging is provided by a version of 
-.BR syslogd (8)
-derived from the sysklogd package which in turn is derived from the
-stock BSD sources.  Support for kernel logging is provided by the
-.BR klogd (8)
-utility which allows kernel logging to be conducted in either a
-standalone fashion or as a client of syslogd.
+.BR Rsyslogd (8)
+is derived from the sysklogd package which in turn is derived from the
+stock BSD sources.
 
-.B Syslogd
+.B Rsyslogd
 provides a kind of logging that many modern programs use.  Every logged
 message contains at least a time and a hostname field, normally a
 program name field, too, but that depends on how trusty the logging
@@ -55,36 +51,39 @@ to MySQL databases. If the database option is used, tools like phpLogCon can
 be used to view the log data.
 
 While the
-.B syslogd
+.B rsyslogd
 sources have been heavily modified a couple of notes
 are in order.  First of all there has been a systematic attempt to
-insure that syslogd follows its default, standard BSD behavior. Of course,
+insure that rsyslogd follows its default, standard BSD behavior. Of course,
 some configuration file changes are necessary in order to support the
-template system. However, rsyslog should be able to use a standard
+template system. However, rsyslogd should be able to use a standard
 syslog.conf and act like the orginal syslogd. However, an original syslogd
 will not work correctly with a rsyslog-enhanced configuration file. At
 best, it will generate funny looking file names.
-The second important concept to note is that this version of syslogd
+The second important concept to note is that this version of rsyslogd
 interacts transparently with the version of syslog found in the
 standard libraries.  If a binary linked to the standard shared
 libraries fails to function correctly we would like an example of the
 anomalous behavior.
 
 The main configuration file
-.I /etc/syslog.conf
+.I /etc/rsyslog.conf
 or an alternative file, given with the 
 .B "\-f"
 option, is read at startup.  Any lines that begin with the hash mark
 (``#'') and empty lines are ignored.  If an error occurs during parsing
-the error element is ignored. It is tried to parse the rest of the line
-and it most .
+the error element is ignored. It is tried to parse the rest of the line.
+
+For details and configuration examples, see the
+.B rsyslog.conf (5)
+man page.
 
 .LP
 .SH OPTIONS
 .TP
 .BI "\-a " "socket"
 Using this argument you can specify additional sockets from that
-.B syslogd
+.B rsyslogd
 has to listen to.  This is needed if you're going to let some daemon
 run within a chroot() environment.  You can use up to 19 additional
 sockets.  If your environment needs even more, you have to increase
@@ -103,11 +102,11 @@ DEBUGGING section for more information.
 .TP
 .BI "\-f " "config file"
 Specify an alternative configuration file instead of
-.IR /etc/syslog.conf ","
+.IR /etc/rsyslog.conf ","
 which is the default.
 .TP
 .BI "\-h "
-By default syslogd will not forward messages it receives from remote hosts.
+By default rsyslogd will not forward messages it receives from remote hosts.
 Specifying this switch on the command line will cause the log daemon to
 forward any remote messages it receives to forwarding hosts which have been
 defined.
@@ -116,20 +115,26 @@ defined.
 Specify a hostname that should be logged only with its simple hostname
 and not the fqdn.  Multiple hosts may be specified using the colon
 (``:'') separator.
+
+Note: At the moment, this option is only available for command
+line comptability. It has, however, NO effect and is ignored.
 .TP
 .BI "\-m " "interval"
 The
-.B syslogd
+.B rsyslogd
 logs a mark timestamp regularly.  The default
 .I interval
 between two \fI-- MARK --\fR lines is 20 minutes.  This can be changed
 with this option.  Setting the
 .I interval
 to zero turns it off entirely.
+
+Note: At the moment, this option is only available for command
+line comptability. It has, however, NO effect and is ignored.
 .TP
 .B "\-n"
 Avoid auto-backgrounding.  This is needed especially if the
-.B syslogd
+.B rsyslogd
 is started and controlled by
 .BR init (8).
 .TP
@@ -142,10 +147,6 @@ This option will enable the facility to receive message from the
 network using an internet domain socket with the syslog service (see 
 .BR services (5)).
 The default is to not receive any messages from the network.
-
-This option is introduced in version 1.3 of the sysklogd
-package.  Please note that the default behavior is the opposite of
-how older versions behave, so you might have to turn this on.
 .TP
 .BI "\-s " "domainlist"
 Specify a domainname that should be stripped off before
@@ -162,39 +163,38 @@ no domain would be cut, you will have to specify two domains like:
 Print version and exit.
 .LP
 .SH SIGNALS
-.B Syslogd
+.B Rsyslogd
 reacts to a set of signals.  You may easily send a signal to
-.B syslogd
+.B rsyslogd
 using the following:
 .IP
 .nf
-kill -SIGNAL `cat /var/run/syslogd.pid`
+kill -SIGNAL `cat /var/run/rsyslogd.pid`
 .fi
 .PP
 .TP
 .B SIGHUP
 This lets
-.B syslogd
+.B rsyslogd
 perform a re-initialization.  All open files are closed, the
 configuration file (default is 
-.IR /etc/syslog.conf ")"
+.IR /etc/rsyslog.conf ")"
 will be reread and the
-.BR syslog (3)
+.BR rsyslog (3)
 facility is started again.
 .TP
 .B SIGTERM
-The
-.B syslogd
+.B Rsyslogd
 will die.
 .TP
 .BR SIGINT ", " SIGQUIT
 If debugging is enabled these are ignored, otherwise 
-.B syslogd
+.B rsyslogd
 will die.
 .TP
 .B SIGUSR1
 Switch debugging on/off.  This option can only be used if
-.B syslogd
+.B rsyslogd
 is started with the
 .B "\-d"
 debug option.
@@ -202,111 +202,23 @@ debug option.
 .B SIGCHLD
 Wait for childs if some were born, because of wall'ing messages.
 .LP
-.SH CONFIGURATION FILE SYNTAX DIFFERENCES
-.B Syslogd
-uses a slightly different syntax for its configuration file than
-the original BSD sources.  Originally all messages of a specific priority
-and above were forwarded to the log file.
-.IP
-For example the following line caused ALL output from daemons using
-the daemon facilities (debug is the lowest priority, so every higher
-will also match) to go into 
-.IR /usr/adm/daemons :
-.IP
-.nf
-	# Sample syslog.conf
-	daemon.debug			/usr/adm/daemons
-.fi
-.PP
-Under the new scheme this behavior remains the same.  The difference
-is the addition of four new specifiers, the asterisk (\fB*\fR)
-wildcard, the equation sign (\fB=\fR), the exclamation mark
-(\fB!\fR), and the minus sign (\fB-\fR).
-
-The \fB*\fR specifies that all messages for the
-specified facility are to be directed to the destination.  Note that
-this behavior is degenerate with specifying a priority level of debug.
-Users have indicated that the asterisk notation is more intuitive.
-
-The \fB=\fR wildcard is used to restrict logging to the specified priority
-class.  This allows, for example, routing only debug messages to a
-particular logging source.
-.IP
-For example the following line in
-.I syslog.conf
-would direct debug messages from all sources to the
-.I /usr/adm/debug
-file.
-.IP
-.nf
-	# Sample syslog.conf
-	*.=debug			/usr/adm/debug
-.fi
-.PP
-.\" The \fB!\fR as the first character of a priority inverts the above
-.\" mentioned interpretation.
-The \fB!\fR is used to exclude logging of the specified
-priorities.  This affects all (!) possibilities of specifying priorities.
-.IP
-For example the following lines would log all messages of the facility
-mail except those with the priority info to the
-.I /usr/adm/mail 
-file.  And all messages from news.info (including) to news.crit
-(excluding) would be logged to the
-.I /usr/adm/news
-file.
-.IP
-.nf
-	# Sample syslog.conf
-	mail.*;mail.!=info		/usr/adm/mail
-	news.info;news.!crit	/usr/adm/news
-.fi
-.PP
-You may use it intuitively as an exception specifier.  The above
-mentioned interpretation is simply inverted.  Doing that you may use
-
-.nf
-	mail.none
-.fi
-or
-.nf
-	mail.!*
-.fi
-or
-.nf
-	mail.!debug
-.fi
-
-to skip every message that comes with a mail facility.  There is much
-room to play with it. :-)
-
-The \fB-\fR may only be used to prefix a filename if you want to omit
-sync'ing the file after every write to it.
-
-This may take some acclimatization for those individuals used to the
-pure BSD behavior but testers have indicated that this syntax is
-somewhat more flexible than the BSD behavior.  Note that these changes
-should not affect standard
-.BR syslog.conf (5)
-files.  You must specifically
-modify the configuration files to obtain the enhanced behavior.
-.LP
 .SH SUPPORT FOR REMOTE LOGGING
-These modifications provide network support to the syslogd facility.
+.B Rsyslogd
+provides network support to the syslogd facility.
 Network support means that messages can be forwarded from one node
-running syslogd to another node running syslogd where they will be
+running rsyslogd to another node running rsyslogd where they will be
 actually logged to a disk file.
 
 To enable this you have to specify the
 .B "\-r"
 option on the command line.  The default behavior is that
-.B syslogd
+.B rsyslogd
 won't listen to the network.
 
-The strategy is to have syslogd listen on a unix domain socket for
-locally generated log messages.  This behavior will allow syslogd to
+The strategy is to have rsyslogd listen on a unix domain socket for
+locally generated log messages.  This behavior will allow rsyslogd to
 inter-operate with the syslog found in the standard C library.  At the
-same time syslogd listens on the standard syslog port for messages
+same time rsyslogd listens on the standard syslog port for messages
 forwarded from other hosts.  To have this work correctly the
 .BR services (5)
 files (typically found in
@@ -319,15 +231,15 @@ entry:
 .fi
 .PP
 If this entry is missing
-.B syslogd
+.B rsyslogd
 neither can receive remote messages nor send them, because the UDP
 port cant be opened.  Instead 
-.B syslogd
+.B rsyslogd
 will die immediately, blowing out an error message.
 
 To cause messages to be forwarded to another host replace
 the normal file line in the
-.I syslog.conf
+.I rsyslog.conf
 file with the name of the host to which the messages is to be sent
 prepended with an @.
 .IP
@@ -335,29 +247,18 @@ For example, to forward
 .B ALL
 messages to a remote host use the
 following
-.I syslog.conf
+.I rsyslog.conf
 entry:
 .IP
 .nf
-	# Sample syslogd configuration file to
+	# Sample rsyslogd configuration file to
 	# messages to a remote host forward all.
 	*.*			@hostname
 .fi
-
-To forward all \fBkernel\fP messages to a remote host the
-configuration file would be as follows:
-.IP
-.nf
-	# Sample configuration file to forward all kernel
-	# messages to a remote host.
-	kern.*		@hostname
-.fi
-.PP
-
 If the remote hostname cannot be resolved at startup, because the
-name-server might not be accessible (it may be started after syslogd)
+name-server might not be accessible (it may be started after rsyslogd)
 you don't have to worry.
-.B Syslogd
+.B Rsyslogd
 will retry to resolve the name ten times and then complain.  Another
 possibility to avoid this is to place the hostname in
 .IR /etc/hosts .
@@ -366,17 +267,16 @@ With normal
 .BR syslogd s
 you would get syslog-loops if you send out messages that were received
 from a remote host to the same host (or more complicated to a third
-host that sends it back to the first one, and so on).  In my domain
-(Infodrom Oldenburg) we accidently got one and our disks filled up
-with the same single message. :-(
+host that sends it back to the first one, and so on).
 
-To avoid this in further times no messages that were received from a
-remote host are sent out to another (or the same) remote host
-anymore.  If there are scenarios where this doesn't make sense, please
-drop me (Joey) a line.
+To avoid this no messages that were received from a
+remote host are sent out to another (or the same) remote host. You can
+disable this feature by the
+.B \-h
+option.
 
 If the remote host is located in the same domain as the host, 
-.B syslogd
+.B rsyslogd
 is running on, only the simple hostname will be logged instead of
 the whole fqdn.
 
@@ -386,8 +286,8 @@ of different domains you don't have to complain about logging fully
 qualified names instead of simple hostnames.  You may want to use the
 strip-domain feature
 .B \-s
-of this server.  You can tell the
-.B syslogd
+of this server.  You can tell
+.B rsyslogd
 to strip off several domains other than the one the server is located
 in and only log simple hostnames.
 
@@ -397,17 +297,28 @@ option there's also a possibility to define single hosts as local
 machines.  This, too, results in logging only their simple hostnames
 and not the fqdns.
 
-The UDP socket used to forward messages to remote hosts or to receive
-messages from them is only opened when it is needed.  In releases
-prior to 1.3-23 it was opened every time but not opened for reading or
-forwarding respectively.
+.SH OUTPUT TO DATABASES
+.B Rsyslogd
+has support for writing data to MySQL database tables. The exact specifics
+are described in the
+.B rsyslog.conf (5)
+man page. Be sure to read it if you plan to use database logging.
+
+While it is often handy to have the data in a database, you must be aware
+of the implications. Most importantly, database logging takes far
+longer than logging to a text file. A system that can handle a large
+log volume when writing to text files can most likely not handle
+a similar large volume when writing to a database table.
 
 .SH OUTPUT TO NAMED PIPES (FIFOs)
-This version of syslogd has support for logging output to named pipes
+.B Rsyslogd
+has support for logging output to named pipes
 (fifos).  A fifo or named pipe can be used as a destination for log
 messages by prepending a pipy symbol (``|'') to the name of the
 file.  This is handy for debugging.  Note that the fifo must be created
-with the mkfifo command before syslogd is started.
+with the mkfifo command before
+.B rsyslogd
+is started.
 .IP
 The following configuration file routes debug messages from the
 kernel to a fifo:
@@ -420,14 +331,14 @@ kernel to a fifo:
 .fi
 .LP
 .SH INSTALLATION CONCERNS
-There is probably one important consideration when installing this
-version of syslogd.  This version of syslogd is dependent on proper
+There is probably one important consideration when installing
+rsyslogd.  It is dependent on proper
 formatting of messages by the syslog function.  The functioning of the
 syslog function in the shared libraries changed somewhere in the
 region of libc.so.4.[2-4].n.  The specific change was to
 null-terminate the message before transmitting it to the 
 .I /dev/log
-socket.  Proper functioning of this version of syslogd is dependent on
+socket.  Proper functioning of this version of rsyslogd is dependent on
 null-termination of the message.
 
 This problem will typically manifest itself if old statically linked
@@ -437,9 +348,9 @@ the message with the first character in the message removed.
 Relinking these binaries to newer versions of the shared libraries
 will correct this problem.
 
-Both the
-.BR syslogd "(8) and the " klogd (8)
-can either be run from
+The
+.BR rsyslogd (8)
+can be run from
 .BR init (8)
 or started as part of the rc.*
 sequence.  If it is started from init the option \fI\-n\fR must be set,
@@ -448,10 +359,9 @@ otherwise you'll get tons of syslog daemons started.  This is because
 depends on the process ID.
 .LP
 .SH SECURITY THREATS
-There is the potential for the syslogd daemon to be
-used as a conduit for a denial of service attack.  Thanks go to John
-Morrison (jmorriso@rflab.ee.ubc.ca) for alerting me to this potential.
-A rogue program(mer) could very easily flood the syslogd daemon with
+There is the potential for the rsyslogd daemon to be
+used as a conduit for a denial of service attack.
+A rogue program(mer) could very easily flood the rsyslogd daemon with
 syslog messages resulting in the log files consuming all the remaining
 space on the filesystem.  Activating logging over the inet domain
 sockets will of course expose a system to risks outside of programs or
@@ -467,9 +377,9 @@ if filled, will not impair the machine.
 .IP 3.
 The ext2 filesystem can be used which can be configured to limit a
 certain percentage of a filesystem to usage by root only.  \fBNOTE\fP
-that this will require syslogd to be run as a non-root process.
+that this will require rsyslogd to be run as a non-root process.
 \fBALSO NOTE\fP that this will prevent usage of remote logging since
-syslogd will be unable to bind to the 514/UDP socket.
+rsyslogd will be unable to bind to the 514/UDP socket.
 .IP 4.
 Disabling inet domain sockets will limit risk to the local machine.
 .IP 5.
@@ -482,12 +392,19 @@ threaded on each end.  Primary use in the oil industry in Western
 North Dakota and other locations to pump 'suck' oil from oil wells.
 Secondary uses are for the construction of cattle feed lots and for
 dealing with the occasional recalcitrant or belligerent individual.
+.SS Message replay and spoofing
+If remote logging is enabled, messages can easily be spoofed and replayed.
+As the messages are transmitted in clear-text, an attacker might use
+the information obtained from the packets for malicious things. Also, an
+attacker might reply recorded messages or spoof a sender's IP address,
+which could lead to a wrong preception of system activity. Be sure to think
+about syslog network security before enabling it.
 .LP
 .SH DEBUGGING
 When debugging is turned on using
 .B "\-d"
 option then
-.B syslogd
+.B rsyslogd
 will be very verbose by writing much of what it does on stdout.  Whenever
 the configuration file is reread and re-parsed you'll see a tabular,
 corresponding to the internal data structure.  This tabular consists of
@@ -498,7 +415,7 @@ This field contains a serial number starting by zero.  This number
 represents the position in the internal data structure (i.e. the
 array).  If one number is left out then there might be an error in the
 corresponding line in
-.IR /etc/syslog.conf .
+.IR /etc/rsyslog.conf .
 .TP
 .I pattern
 This field is tricky and represents the internal structure
@@ -522,27 +439,38 @@ user-logging this is a list of users; for remote logging this is the
 hostname of the machine to log to; for console-logging this is the
 used console; for tty-logging this is the specified tty; wall has no
 additional arguments.
+.TP
+.SS templates
+There will also be a second internal structure which lists all
+defined templates and there contents. This also enables you to see
+the internally-defined, hardcoded templates.
 .SH FILES
 .PD 0
 .TP
-.I /etc/syslog.conf
+.I /etc/rsyslog.conf
 Configuration file for
-.BR syslogd .
+.BR rsyslogd .
 See
-.BR syslog.conf (5)
+.BR rsyslog.conf (5)
 for exact information.
 .TP
 .I /dev/log
 The Unix domain socket to from where local syslog messages are read.
 .TP
-.I /var/run/syslogd.pid
+.I /var/run/rsyslogd.pid
 The file containing the process id of 
-.BR syslogd .
+.BR rsyslogd .
 .PD
 .SH BUGS
+This is an early release of
+.B Rsyslogd .
+As such, there are probably a number of bugs. Those that I know
+are described in the file BUGS that came with the package. Be sure
+to review it.
+
 If an error occurs in one line the whole rule is ignored.
 
-.B Syslogd
+.B Rsyslogd
 doesn't change the filemode of opened logfiles at any stage of
 process.  If a file is created it is world readable.  If you want to
 avoid this, you have to create it and change permissions on your own.
@@ -555,8 +483,7 @@ everybody is able to read auth.* messages as these might contain
 passwords.
 .LP
 .SH SEE ALSO
-.BR syslog.conf (5),
-.BR klogd (8),
+.BR rsyslog.conf (5),
 .BR logger (1),
 .BR syslog (2),
 .BR syslog (3),
@@ -564,52 +491,26 @@ passwords.
 .BR savelog (8)
 .LP
 .SH COLLABORATORS
-.B Syslogd
-is taken from BSD sources, Greg Wettstein (greg@wind.enjellic.com)
-performed the port to Linux, Martin Schulze (joey@linux.de)
-fixed some bugs and added several new features.
-.B Klogd 
-was originally written by Steve Lord (lord@cray.com), Greg Wettstein
-made major improvements.
+.B rsyslogd
+is derived from sysklogd sources, which in turn was taken from
+the BSD sources. Special thanks to Greg Wettstein (greg@wind.enjellic.com)
+and Martin Schulze (joey@linux.de) for the fine sysklogd package.
 
 .PD 0
 .TP
-Dr. Greg Wettstein
-.TP
-Enjellic Systems Development
-.TP
-Oncology Research Division Computing Facility
-.TP
-Roger Maris Cancer Center
-.TP
-Fargo, ND
+Rainer Gerhards
 .TP
-greg@wind.enjellic.com
-
-.TP
-Stephen Tweedie
-.TP
-Department of Computer Science
-.TP
-Edinburgh University, Scotland
-.TP
-sct@dcs.ed.ac.uk
-
-.TP
-Juha Virtanen
-.TP
-jiivee@hut.fi
-
+Adiscon GmbH
 .TP
-Shane Alderton
+Grossrinderfeld, Germany
 .TP
-shane@ion.apana.org.au
+rgerhards@adiscon.com
 
 .TP
-Martin Schulze
+Michael Meckelein
 .TP
-Infodrom Oldenburg
+Adiscon GmbH
 .TP
-joey@linux.de
+mmeckelein@adiscon.com
 .PD
 .zZ