diff options
Diffstat (limited to 'tools/rsyslogd.8')
| -rw-r--r-- | tools/rsyslogd.8 | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/tools/rsyslogd.8 b/tools/rsyslogd.8 new file mode 100644 index 0000000..fd7a537 --- /dev/null +++ b/tools/rsyslogd.8 @@ -0,0 +1,383 @@ +.\" Copyright 2004-2008 Rainer Gerhards and Adiscon for the rsyslog modifications +.\" May be distributed under the GNU General Public License +.\" +.TH RSYSLOGD 8 "11 July 2008" "Version 3.18.0" "Linux System Administration" +.SH NAME +rsyslogd \- reliable and extended syslogd +.SH SYNOPSIS +.B rsyslogd +.RB [ " \-4 " ] +.RB [ " \-6 " ] +.RB [ " \-A " ] +.RB [ " \-d " ] +.RB [ " \-f " +.I config file +] +.br +.RB [ " \-i " +.I pid file +] +.RB [ " \-l " +.I hostlist +] +.RB [ " \-n " ] +.br +.RB [ " \-q " ] +.RB [ " \-Q " ] +.RB [ " \-s " +.I domainlist +] +.RB [ " \-v " ] +.RB [ " \-w " ] +.RB [ " \-x " ] +.LP +.SH DESCRIPTION +.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. + +.B Note that this version of rsyslog ships with extensive documentation in html format. +This is provided in the ./doc subdirectory and probably +in a separate package if you installed rsyslog via a packaging system. +To use rsyslog's advanced features, you +.B need +to look at the html documentation, because the man pages only cover +basic aspects of operation. +.B For details and configuration examples, see the rsyslog.conf (5) +.B man page and the online documentation at http://www.rsyslog.com/doc + +.BR Rsyslogd (8) +is derived from the sysklogd package which in turn is derived from the +stock BSD sources. + +.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 +program is. The rsyslog package supports free definition of output formats +via templates. It also supports precise timestamps and writing directly +to databases. If the database option is used, tools like phpLogCon can +be used to view the log data. + +While the +.B rsyslogd +sources have been heavily modified a couple of notes +are in order. First of all there has been a systematic attempt to +ensure that rsyslogd follows its default, standard BSD behavior. Of course, +some configuration file changes are necessary in order to support the +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 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/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. + +.LP +.SH OPTIONS +.B Note that in version 3 of rsyslog a number of command line options +.B have been deprecated and replaced with config file directives. The +.B -c option controls the backward compatibility mode in use. +.TP +.BI "\-A" +When sending UDP messages, there are potentially multiple pathes to +the target destination. By default, +.B rsyslogd +only sends to the first target it can successfully send to. If -A +is given, messages are sent to all targets. This may improve +reliability, but may also cause message duplicaton. This option +should enabled only if it is fully understood. +.TP +.BI "\-4" +Causes +.B rsyslogd +to listen to IPv4 addresses only. +If neither -4 nor -6 is given, +.B rsyslogd +listens to all configured addresses of the system. +.TP +.BI "\-6" +Causes +.B rsyslogd +to listen to IPv6 addresses only. +If neither -4 nor -6 is given, +.B rsyslogd +listens to all configured addresses of the system. +.TP +.BI "\-c " "version" +Selects the desired backward compatibility mode. It must always be the +first option on the command line, as it influences processing of the +other options. To use the rsyslog v3 native interface, specify -c3. To +use compatibility mode , either do not use -c at all or use +-c<version> where +.IR version +is the rsyslog version that it shall be +compatible with. Using -c0 tells rsyslog to be command-line compatible +to sysklogd, which is the default if -c is not given. +.B Please note that rsyslogd issues warning messages if the -c3 +.B command line option is not given. +This is to alert you that your are running in compatibility +mode. Compatibility mode interfers with you rsyslog.conf commands and +may cause some undesired side-effects. It is meant to be used with a +plain old rsyslog.conf - if you use new features, things become +messy. So the best advice is to work through this document, convert +your options and config file and then use rsyslog in native mode. In +order to aid you in this process, rsyslog logs every +compatibility-mode config file directive it has generated. So you can +simply copy them from your logfile and paste them to the config. +.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/rsyslog.conf "," +which is the default. +.TP +.BI "\-i " "pid file" +Specify an alternative pid file instead of the default one. +This option must be used if multiple instances of rsyslogd should +run on a single machine. +.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 +.B "\-n" +Avoid auto-backgrounding. This is needed especially if the +.B rsyslogd +is started and controlled by +.BR init (8). +.TP +.BI "\-q " "add hostname if DNS fails during ACL processing" +During ACL processing, hostnames are resolved to IP addreses for +performance reasons. If DNS fails during that process, the hostname +is added as wildcard text, which results in proper, but somewhat +slower operation once DNS is up again. +.TP +.BI "\-Q " "do not resolve hostnames during ACL processing" +Do not resolve hostnames to IP addresses during ACL processing. +.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. +.TP +.B "\-w" +Supress warnings issued when messages are received from non-authorized +machines (those, that are in no AllowedSender list). +.TP +.B "\-x" +Disable DNS for remote messages. +.LP +.SH SIGNALS +.B Rsyslogd +reacts to a set of signals. You may easily send a signal to +.B rsyslogd +using the following: +.IP +.nf +kill -SIGNAL $(cat /var/run/syslogd.pid) +.fi +.PP +Note that -SIGNAL must be replaced with the actual signal +you are trying to send, e.g. with HUP. So it then becomes: +.IP +.nf +kill -HUP $(cat /var/run/syslogd.pid) +.fi +.PP +.TP +.B HUP +This lets +.B rsyslogd +perform a re-initialization. All open files are closed, the +configuration file (default is +.IR /etc/rsyslog.conf ")" +will be reread and the +.BR rsyslog (3) +facility is started again. +Note that this means a full rsyslogd restart is done. This has, among others, +the consequence that TCP and other connections are torn down. Also, if any +queues are not running in disk assisted mode or are not set to persist data +on shutdown, queue data is lost. HUPing rsyslogd is an extremely expensive +operation and should only be done when actually necessary. Actually, it is +a rsyslgod stop immediately followed by a restart. Future versions will probably +include a special handling which only closes files, but will not cause any +of the other effects. +.TP +.B TERM ", " INT ", " QUIT +.B Rsyslogd +will die. +.TP +.B USR1 +Switch debugging on/off. This option can only be used if +.B rsyslogd +is started with the +.B "\-d" +debug option. +.TP +.B CHLD +Wait for childs if some were born, because of wall'ing messages. +.LP +.SH SECURITY THREATS +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 +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 rsyslogd to be run as a non-root process. +\fBALSO NOTE\fP that this will prevent usage of remote logging on the default port since +rsyslogd will be unable to bind to the 514/UDP socket. +.IP 4. +Disabling inet domain sockets will limit risk to the local machine. +.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 replay recorded messages or spoof a sender's IP address, +which could lead to a wrong perception of system activity. These can +be prevented by using GSS-API authentication and encryption. 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 rsyslogd +will be very verbose by writing much of what it does on stdout. +.SH FILES +.PD 0 +.TP +.I /etc/rsyslog.conf +Configuration file for +.BR rsyslogd . +See +.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/rsyslogd.pid +The file containing the process id of +.BR rsyslogd . +.TP +.I prefix/lib/rsyslog +Default directory for +.B rsyslogd +modules. The +.I prefix +is specified during compilation (e.g. /usr/local). +.SH ENVIRONMENT +.TP +.B RSYSLOG_DEBUG +Controls runtime debug support.It contains an option string with the +following options possible (all are case insensitive): + +.RS +.IP LogFuncFlow +Print out the logical flow of functions (entering and exiting them) +.IP FileTrace +Specifies which files to trace LogFuncFlow. If not set (the +default), a LogFuncFlow trace is provided for all files. Set to +limit it to the files specified.FileTrace may be specified multiple +times, one file each (e.g. export RSYSLOG_DEBUG="LogFuncFlow +FileTrace=vm.c FileTrace=expr.c" +.IP PrintFuncDB +Print the content of the debug function database whenever debug +information is printed (e.g. abort case)! +.IP PrintAllDebugInfoOnExit +Print all debug information immediately before rsyslogd exits +(currently not implemented!) +.IP PrintMutexAction +Print mutex action as it happens. Useful for finding deadlocks and +such. +.IP NoLogTimeStamp +Do not prefix log lines with a timestamp (default is to do that). +.IP NoStdOut +Do not emit debug messages to stdout. If RSYSLOG_DEBUGLOG is not +set, this means no messages will be displayed at all. +.IP Help +Display a very short list of commands - hopefully a life saver if +you can't access the documentation... +.RE + +.TP +.B RSYSLOG_DEBUGLOG +If set, writes (allmost) all debug message to the specified log file +in addition to stdout. +.TP +.B RSYSLOG_MODDIR +Provides the default directory in which loadable modules reside. +.PD +.SH BUGS +Please review the file BUGS for up-to-date information on known +bugs and annouyances. +.SH Further Information +Please visit +.BR http://www.rsyslog.com/doc +for additional information, tutorials and a support forum. +.SH SEE ALSO +.BR rsyslog.conf (5), +.BR logger (1), +.BR syslog (2), +.BR syslog (3), +.BR services (5), +.BR savelog (8) +.LP +.SH COLLABORATORS +.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 +Rainer Gerhards +.TP +Adiscon GmbH +.TP +Grossrinderfeld, Germany +.TP +rgerhards@adiscon.com +.PD |