diff options
Diffstat (limited to 'rsyslogd.8')
| -rw-r--r-- | rsyslogd.8 | 615 |
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 |