summaryrefslogtreecommitdiffstats
path: root/doc/man_rsyslogd.html
diff options
context:
space:
mode:
authorRainer Gerhards <rgerhards@adiscon.com>2007-10-16 08:27:09 +0000
committerRainer Gerhards <rgerhards@adiscon.com>2007-10-16 08:27:09 +0000
commit2357d1442991dbe0e154870437b11e17be72e427 (patch)
tree71874f7cf337abfd06e1d40f0f6b088eec9d60fb /doc/man_rsyslogd.html
parent054f7665409170c0c6b8cd9f6e5e29b85ca35d8e (diff)
downloadrsyslog-2357d1442991dbe0e154870437b11e17be72e427.tar.gz
rsyslog-2357d1442991dbe0e154870437b11e17be72e427.tar.xz
rsyslog-2357d1442991dbe0e154870437b11e17be72e427.zip
added new rsyslogd man page in html format (thanks to man2html)
Diffstat (limited to 'doc/man_rsyslogd.html')
-rw-r--r--doc/man_rsyslogd.html438
1 files changed, 438 insertions, 0 deletions
diff --git a/doc/man_rsyslogd.html b/doc/man_rsyslogd.html
new file mode 100644
index 00000000..fab309db
--- /dev/null
+++ b/doc/man_rsyslogd.html
@@ -0,0 +1,438 @@
+<BODY><PRE>
+RSYSLOGD(8) Linux System Administration RSYSLOGD(8)
+
+
+
+<B>NAME</B>
+ rsyslogd - reliable and extended syslogd
+
+<B>SYNOPSIS</B>
+ <B>rsyslogd </B>[ <B>-4 </B>] [ <B>-6 </B>] [ <B>-A </B>] [ <B>-a </B><I>socket </I>] [ <B>-d </B>] [ <B>-e </B>]
+ [ <B>-f </B><I>config file </I>] [ <B>-h </B>] [ <B>-i </B><I>pid file </I>] [ <B>-l </B><I>hostlist </I>]
+ [ <B>-m </B><I>interval </I>] [ <B>-n </B>] [ <B>-o </B>] [ <B>-p </B><I>socket </I>]
+ [ <B>-r </B><I>[port] </I>] [ <B>-s </B><I>domainlist </I>] [ <B>-t </B><I>port,max-nbr-of-sessions </I>]
+ [ <B>-v </B>] [ <B>-w </B>] [ <B>-x </B>]
+
+
+<B>DESCRIPTION</B>
+ <B>Rsyslogd </B>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 (via UDP and TCP).
+
+ <B>Rsyslogd</B>(8) is derived from the sysklogd package which in turn is
+ derived from the stock BSD sources.
+
+ <B>Rsyslogd </B>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>rsyslogd </B>sources have been heavily modified a couple of notes
+ are in order. First of all there has been a systematic attempt to
+ insure that rsyslogd follows its default, standard BSD behavior. Of
+ course, some configuration file changes are necessary in order to sup-
+ port 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 con-
+ figuration 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 stan-
+ dard 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 </I>or an alternative file,
+ given with the <B>-f </B>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.
+
+ For details and configuration examples, see the <B>rsyslog.conf (5) </B>man
+ page.
+
+
+
+<B>OPTIONS</B>
+ <B>-A </B>When sending UDP messages, there are potentially multiple pathes
+ to the target destination. By default, <B>rsyslogd </B>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.
+
+ <B>-4 </B>Causes <B>rsyslogd </B>to listen to IPv4 addresses only. If neither -4
+ nor -6 is given, <B>rsyslogd </B>listens to all configured addresses of
+ the system.
+
+ <B>-6 </B>Causes <B>rsyslogd </B>to listen to IPv6 addresses only. If neither -4
+ nor -6 is given, <B>rsyslogd </B>listens to all configured addresses of
+ the system.
+
+ <B>-a </B><I>socket</I>
+ Using this argument you can specify additional sockets from that
+ <B>rsyslogd </B>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 </B>within the sys-
+ logd.c source file. An example for a chroot() daemon is
+ described by the people from OpenBSD at
+ http://www.psionic.com/papers/dns.html.
+
+ <B>-d </B>Turns on debug mode. Using this the daemon will not proceed a
+ <B>fork</B>(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.
+
+ <B>-e </B>Set the default of $RepeatedMsgReduction config option to "off".
+ Hine: "e" like "every message". For further information, see
+ there.
+
+ <B>-f </B><I>config file</I>
+ Specify an alternative configuration file instead of <I>/etc/rsys-</I>
+ <I>log.conf</I>, which is the default.
+
+ <B>-h </B>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.
+
+ <B>-i </B><I>pid file</I>
+ 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.
+
+ <B>-l </B><I>hostlist</I>
+ 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.
+
+ <B>-m </B><I>interval</I>
+ The <B>rsyslogd </B>logs a mark timestamp regularly. The default
+ <I>interval </I>between two <I>-- MARK -- </I>lines is 20 minutes. This can
+ be changed with this option. Setting the <I>interval </I>to zero turns
+ it off entirely.
+
+ <B>-n </B>Avoid auto-backgrounding. This is needed especially if the
+ <B>rsyslogd </B>is started and controlled by <B>init</B>(8).
+
+ <B>-o </B>Omit reading the standard local log socket. This option is most
+ useful for running multiple instances of rsyslogd on a single
+ machine. When specified, no local log socket is opened at all.
+
+ <B>-p </B><I>socket</I>
+ You can specify an alternative unix domain socket instead of
+ <I>/dev/log</I>.
+
+ <B>-r </B><I>["port"]</I>
+ Activates the syslog/udp listener service. The listener will
+ listen to the specified port. If no port is specified, 0 is
+ used as port number, which in turn will lead to a lookup of the
+ system default syslog port. If there is no system default, 514
+ is used. Please note that the port must immediately follow the
+ -r option. Thus "-r514" is valid while "-r 514" is invalid (note
+ the space).
+
+ <B>-s </B><I>domainlist</I>
+ Specify a domainname that should be stripped off before logging.
+ Multiple domains may be specified using the colon (‘‘:’’) sepa-
+ rator. Please be advised that no sub-domains may be specified
+ but only entire domains. For example if <B>-s north.de </B>is speci-
+ fied and the host logging resolves to satu.infodrom.north.de no
+ domain would be cut, you will have to specify two domains like:
+ <B>-s north.de:infodrom.north.de</B>.
+
+ <B>-t </B><I>port,max-nbr-of-sessions</I>
+ Activates the syslog/tcp listener service. The listener will
+ listen to the specified port. If max-nbr-of-sessions is speci-
+ fied, that becomes the maximum number of concurrent tcp ses-
+ sions. If not specified, the default is 200. Please note that
+ syslog/tcp is not standardized, but the implementation in rsys-
+ logd follows common practice and is compatible with e.g. Cisco
+ PIX, syslog-ng and MonitorWare (Windows). Please note that the
+ port must immediately follow the -t option. Thus "-t514" is
+ valid while "-t 514" is invalid (note the space).
+
+ <B>-v </B>Print version and exit.
+
+ <B>-w </B>Supress warnings issued when messages are received from non-
+ authorized machines (those, that are in no AllowedSender list).
+
+ <B>-x </B>Disable DNS for remote messages.
+
+
+<B>SIGNALS</B>
+ <B>Rsyslogd </B>reacts to a set of signals. You may easily send a signal to
+ <B>rsyslogd </B>using the following:
+
+ kill -SIGNAL ‘cat /var/run/rsyslogd.pid‘
+
+
+ <B>SIGHUP </B>This lets <B>rsyslogd </B>perform a re-initialization. All open files
+ are closed, the configuration file (default is <I>/etc/rsys-</I>
+ <I>log.conf</I>) will be reread and the <B>rsyslog</B>(3) facility is started
+ again.
+
+ <B>SIGTERM</B>
+ <B>Rsyslogd </B>will die.
+
+ <B>SIGINT</B>, <B>SIGQUIT</B>
+ If debugging is enabled these are ignored, otherwise <B>rsyslogd</B>
+ will die.
+
+ <B>SIGUSR1</B>
+ Switch debugging on/off. This option can only be used if <B>rsys-</B>
+ <B>logd </B>is started with the <B>-d </B>debug option.
+
+ <B>SIGCHLD</B>
+ Wait for childs if some were born, because of wall’ing messages.
+
+
+<B>SUPPORT FOR REMOTE LOGGING</B>
+ <B>Rsyslogd </B>provides network support to the syslogd facility. Network
+ support means that messages can be forwarded from one node running
+ rsyslogd to another node running rsyslogd (or a compatible syslog
+ implementation) where they will be actually logged to a disk file.
+
+ To enable this you have to specify either the <B>-r </B>or <B>-t </B>option on the
+ command line. The default behavior is that <B>rsyslogd </B>won’t listen to
+ the network. You can also combine these two options if you want rsys-
+ logd to listen to both TCP and UDP messages.
+
+ 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 rsyslogd listens on the standard syslog port for messages
+ forwarded from other hosts. To have this work correctly the <B>ser-</B>
+ <B>vices</B>(5) files (typically found in <I>/etc</I>) must have the following entry:
+
+ syslog 514/udp
+
+ If this entry is missing <B>rsyslogd </B>will use the well known port of 514
+ (so in most cases, it’s not really needed).
+
+ To cause messages to be forwarded to another host replace the normal
+ file line in the <I>rsyslog.conf </I>file with the name of the host to which
+ the messages is to be sent prepended with an @ (for UDP delivery) or
+ the sequence @@ (for TCP delivery). The host name can also be followed
+ by a colon and a port number, in which case the message is sent to the
+ specified port on the remote host.
+
+ For example, to forward <B>ALL </B>messages to a remote host use the
+ following <I>rsyslog.conf </I>entry:
+
+ # Sample rsyslogd configuration file to
+ # messages to a remote host forward all.
+ *.* @hostname
+ More samples can be found in sample.conf.
+
+ If the remote hostname cannot be resolved at startup, because
+ the name-server might not be accessible (it may be started after
+ rsyslogd) you don’t have to worry. <B>Rsyslogd </B>will retry to
+ resolve the name ten times and then complain. Another possibil-
+ ity to avoid this is to place the hostname in <I>/etc/hosts</I>.
+
+ With normal <B>syslogd</B>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).
+
+ To avoid this no messages that were received from a remote host
+ are sent out to another (or the same) remote host. You can dis-
+ able this feature by the <B>-h </B>option.
+
+ If the remote host is located in the same domain as the host,
+ <B>rsyslogd </B>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 net-
+ work 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 </B>of this server.
+ You can tell <B>rsyslogd </B>to strip off several domains other than
+ the one the server is located in and only log simple hostnames.
+
+ Using the <B>-l </B>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.
+
+
+<B>OUTPUT TO DATABASES</B>
+ <B>Rsyslogd </B>has support for writing data to MySQL database tables. The
+ exact specifics are described in the <B>rsyslog.conf (5) </B>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 sim-
+ ilar large volume when writing to a database table.
+
+
+<B>OUTPUT TO NAMED PIPES (FIFOs)</B>
+ <B>Rsyslogd </B>has support for logging output to named pipes (fifos). A fifo
+ or named pipe can be used as a destination for log messages by prepend-
+ ing 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 <B>rsyslogd </B>is started.
+
+ The following configuration file routes debug messages from the
+ kernel to a fifo:
+
+ # Sample configuration to route kernel debugging
+ # messages ONLY to /usr/adm/debug which is a
+ # named pipe.
+ kern.=debug |/usr/adm/debug
+
+
+<B>INSTALLATION CONCERNS</B>
+ There is probably one important consideration when installing rsyslogd.
+ It is dependent on proper formatting of messages by the syslog func-
+ tion. 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 </I>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
+ 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.
+
+ The <B>rsyslogd</B>(8) can be run from <B>init</B>(8) or started as part of the rc.*
+ sequence. If it is started from init the option <I>-n </I>must be set, other-
+ wise you’ll get tons of syslog daemons started. This is because
+ <B>init</B>(8) depends on the process ID.
+
+
+<B>SECURITY THREATS</B>
+ 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:
+
+ 1. Implement kernel firewalling to limit which hosts or networks
+ have access to the 514/UDP socket.
+
+ 2. Logging can be directed to an isolated or non-root filesystem
+ which, if filled, will not impair the machine.
+
+ 3. The ext2 filesystem can be used which can be configured to limit
+ a certain percentage of a filesystem to usage by root only.
+ <B>NOTE </B>that this will require rsyslogd to be run as a non-root
+ process. <B>ALSO NOTE </B>that this will prevent usage of remote log-
+ ging since rsyslogd will be unable to bind to the 514/UDP
+ socket.
+
+ 4. Disabling inet domain sockets will limit risk to the local
+ machine.
+
+ 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. — 3/4, 7/8 or 1in. hardened steel rod, male
+ threaded on each end. Primary use in the oil industry in West-
+ ern 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 bel-
+ ligerent individual.
+
+ <B>Message replay and spoofing</B>
+ 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.
+
+
+<B>DEBUGGING</B>
+ When debugging is turned on using <B>-d </B>option then <B>rsyslogd </B>will be very
+ verbose by writing much of what it does on stdout. Whenever the con-
+ figuration file is reread and re-parsed you’ll see a tabular, corre-
+ sponding to the internal data structure. This tabular consists of four
+ fields:
+
+ <I>number </I>This field contains a serial number starting by zero. This num-
+ ber 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 <I>/etc/rsyslog.conf</I>.
+
+ <I>pattern</I>
+ This field is tricky and represents the internal structure
+ exactly. Every column stands for a facility (refer to <B>sys-</B>
+ <B>log</B>(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 <B>syslog</B>(3)).
+
+ <I>action </I>This field describes the particular action that takes place
+ whenever a message is received that matches the pattern. Refer
+ to the <B>syslog.conf</B>(5) manpage for all possible actions.
+
+ <I>arguments</I>
+ 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-log-
+ ging this is the used console; for tty-logging this is the spec-
+ ified tty; wall has no additional arguments.
+
+
+ <B>templates</B>
+ 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.
+
+<B>FILES</B>
+ <I>/etc/rsyslog.conf</I>
+ Configuration file for <B>rsyslogd</B>. See <B>rsyslog.conf</B>(5) for exact
+ information.
+ <I>/dev/log</I>
+ The Unix domain socket to from where local syslog messages are
+ read.
+ <I>/var/run/rsyslogd.pid</I>
+ The file containing the process id of <B>rsyslogd</B>.
+
+<B>BUGS</B>
+ Please review the file BUGS for up-to-date information on known bugs
+ and annouyances.
+
+<B>Further Information</B>
+ Please visit <B>http://www.rsyslog.com/doc </B>for additional information,
+ tutorials and a support forum.
+
+<B>SEE ALSO</B>
+ <B>rsyslog.conf</B>(5), <B>logger</B>(1), <B>syslog</B>(2), <B>syslog</B>(3), <B>services</B>(5),
+ <B>savelog</B>(8)
+
+
+<B>COLLABORATORS</B>
+ <B>rsyslogd </B>is derived from sysklogd sources, which in turn was taken from
+ the BSD sources. Special thanks to Greg Wettstein (greg@wind.enjel-
+ lic.com) and Martin Schulze (joey@linux.de) for the fine sysklogd pack-
+ age.
+
+ Rainer Gerhards
+ Adiscon GmbH
+ Grossrinderfeld, Germany
+ rgerhards@adiscon.com
+
+ Michael Meckelein
+ Adiscon GmbH
+ mmeckelein@adiscon.com
+
+
+
+Version 1.16.1 (devel) 17 July 2007 RSYSLOGD(8)
+</PRE></BODY>