summaryrefslogtreecommitdiffstats
path: root/rsyslogd.8
diff options
context:
space:
mode:
Diffstat (limited to 'rsyslogd.8')
-rw-r--r--rsyslogd.8615
1 files changed, 615 insertions, 0 deletions
diff --git a/rsyslogd.8 b/rsyslogd.8
new file mode 100644
index 00000000..777757d2
--- /dev/null
+++ b/rsyslogd.8
@@ -0,0 +1,615 @@
+.\" 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"
+.SH NAME
+rsyslog \- reliable and extended syslogd
+.SH SYNOPSIS
+.B syslogd
+.RB [ " \-a "
+.I socket
+]
+.RB [ " \-d " ]
+.RB [ " \-f "
+.I config file
+]
+.RB [ " \-h " ]
+.RB [ " \-l "
+.I hostlist
+]
+.RB [ " \-m "
+.I interval
+]
+.RB [ " \-n " ]
+.RB [ " \-p"
+.IB socket
+]
+.RB [ " \-r " ]
+.RB [ " \-s "
+.I domainlist
+]
+.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
+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.
+
+.B Syslogd
+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
+program is. The rsyslog package supports free definition of output formats
+via templates. It also supports precise timestamps and writing directly
+to MySQL databases. If the database option is used, tools like phpLogCon can
+be used to view the log data.
+
+While the
+.B syslogd
+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,
+some configuration file changes are necessary in order to support the
+template system. However, rsyslog 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
+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
+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 .
+
+.LP
+.SH OPTIONS
+.TP
+.BI "\-a " "socket"
+Using this argument you can specify additional sockets from that
+.B syslogd
+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
+the symbol
+.B MAXFUNIX
+within the syslogd.c source file. An example for a chroot() daemon is
+described by the people from OpenBSD at
+http://www.psionic.com/papers/dns.html.
+.TP
+.B "\-d"
+Turns on debug mode. Using this the daemon will not proceed a
+.BR fork (2)
+to set itself in the background, but opposite to that stay in the
+foreground and write much debug information on the current tty. See the
+DEBUGGING section for more information.
+.TP
+.BI "\-f " "config file"
+Specify an alternative configuration file instead of
+.IR /etc/syslog.conf ","
+which is the default.
+.TP
+.BI "\-h "
+By default syslogd 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.
+.TP
+.BI "\-l " "hostlist"
+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.
+.TP
+.BI "\-m " "interval"
+The
+.B syslogd
+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.
+.TP
+.B "\-n"
+Avoid auto-backgrounding. This is needed especially if the
+.B syslogd
+is started and controlled by
+.BR init (8).
+.TP
+.BI "\-p " "socket"
+You can specify an alternative unix domain socket instead of
+.IR /dev/log "."
+.TP
+.B "\-r"
+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
+logging. Multiple domains may be specified using the colon (``:'')
+separator.
+Please be advised that no sub-domains may be specified but only entire
+domains. For example if
+.B "\-s north.de"
+is specified and the host logging resolves to satu.infodrom.north.de
+no domain would be cut, you will have to specify two domains like:
+.BR "\-s north.de:infodrom.north.de" .
+.TP
+.B "\-v"
+Print version and exit.
+.LP
+.SH SIGNALS
+.B Syslogd
+reacts to a set of signals. You may easily send a signal to
+.B syslogd
+using the following:
+.IP
+.nf
+kill -SIGNAL `cat /var/run/syslogd.pid`
+.fi
+.PP
+.TP
+.B SIGHUP
+This lets
+.B syslogd
+perform a re-initialization. All open files are closed, the
+configuration file (default is
+.IR /etc/syslog.conf ")"
+will be reread and the
+.BR syslog (3)
+facility is started again.
+.TP
+.B SIGTERM
+The
+.B syslogd
+will die.
+.TP
+.BR SIGINT ", " SIGQUIT
+If debugging is enabled these are ignored, otherwise
+.B syslogd
+will die.
+.TP
+.B SIGUSR1
+Switch debugging on/off. This option can only be used if
+.B syslogd
+is started with the
+.B "\-d"
+debug option.
+.TP
+.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.
+Network support means that messages can be forwarded from one node
+running syslogd to another node running syslogd 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
+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
+inter-operate with the syslog found in the standard C library. At the
+same time syslogd 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
+.IR /etc )
+must have the following
+entry:
+.IP
+.nf
+ syslog 514/udp
+.fi
+.PP
+If this entry is missing
+.B syslogd
+neither can receive remote messages nor send them, because the UDP
+port cant be opened. Instead
+.B syslogd
+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
+file with the name of the host to which the messages is to be sent
+prepended with an @.
+.IP
+For example, to forward
+.B ALL
+messages to a remote host use the
+following
+.I syslog.conf
+entry:
+.IP
+.nf
+ # Sample syslogd 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)
+you don't have to worry.
+.B Syslogd
+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 .
+
+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. :-(
+
+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.
+
+If the remote host is located in the same domain as the host,
+.B syslogd
+is running on, only the simple hostname will be logged instead of
+the whole fqdn.
+
+In a local network you may provide a central log server to have all
+the important information kept on one machine. If the network consists
+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
+to strip off several domains other than the one the server is located
+in and only log simple hostnames.
+
+Using the
+.B \-l
+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 NAMED PIPES (FIFOs)
+This version of syslogd 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.
+.IP
+The following configuration file routes debug messages from the
+kernel to a fifo:
+.IP
+.nf
+ # Sample configuration to route kernel debugging
+ # messages ONLY to /usr/adm/debug which is a
+ # named pipe.
+ kern.=debug |/usr/adm/debug
+.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
+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
+null-termination of the message.
+
+This problem will typically manifest itself if old statically linked
+binaries are being used on the system. Binaries using old versions of
+the syslog function will cause empty lines to be logged followed by
+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
+.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,
+otherwise you'll get tons of syslog daemons started. This is because
+.BR init (8)
+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
+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
+individuals on the local machine.
+
+There are a number of methods of protecting a machine:
+.IP 1.
+Implement kernel firewalling to limit which hosts or networks have
+access to the 514/UDP socket.
+.IP 2.
+Logging can be directed to an isolated or non-root filesystem which,
+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.
+\fBALSO NOTE\fP that this will prevent usage of remote logging since
+syslogd 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.
+Use step 4 and if the problem persists and is not secondary to a rogue
+program/daemon get a 3.5 ft (approx. 1 meter) length of sucker rod*
+and have a chat with the user in question.
+
+Sucker rod def. \(em 3/4, 7/8 or 1in. hardened steel rod, male
+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.
+.LP
+.SH DEBUGGING
+When debugging is turned on using
+.B "\-d"
+option then
+.B syslogd
+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
+four fields:
+.TP
+.I number
+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 .
+.TP
+.I pattern
+This field is tricky and represents the internal structure
+exactly. Every column stands for a facility (refer to
+.BR syslog (3)).
+As you can see, there are still some facilities left free for former
+use, only the left most are used. Every field in a column represents
+the priorities (refer to
+.BR syslog (3)).
+.TP
+.I action
+This field describes the particular action that takes place whenever a
+message is received that matches the pattern. Refer to the
+.BR syslog.conf (5)
+manpage for all possible actions.
+.TP
+.I arguments
+This field shows additional arguments to the actions in the last
+field. For file-logging this is the filename for the logfile; for
+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.
+.SH FILES
+.PD 0
+.TP
+.I /etc/syslog.conf
+Configuration file for
+.BR syslogd .
+See
+.BR syslog.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
+The file containing the process id of
+.BR syslogd .
+.PD
+.SH BUGS
+If an error occurs in one line the whole rule is ignored.
+
+.B Syslogd
+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.
+This could be done in combination with rotating logfiles using the
+.BR savelog (8)
+program that is shipped in the
+.B smail
+3.x distribution. Remember that it might be a security hole if
+everybody is able to read auth.* messages as these might contain
+passwords.
+.LP
+.SH SEE ALSO
+.BR syslog.conf (5),
+.BR klogd (8),
+.BR logger (1),
+.BR syslog (2),
+.BR syslog (3),
+.BR services (5),
+.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.
+
+.PD 0
+.TP
+Dr. Greg Wettstein
+.TP
+Enjellic Systems Development
+.TP
+Oncology Research Division Computing Facility
+.TP
+Roger Maris Cancer Center
+.TP
+Fargo, ND
+.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
+
+.TP
+Shane Alderton
+.TP
+shane@ion.apana.org.au
+
+.TP
+Martin Schulze
+.TP
+Infodrom Oldenburg
+.TP
+joey@linux.de
+.PD
+.zZ