diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2007-10-16 08:27:09 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2007-10-16 08:27:09 +0000 |
| commit | 2357d1442991dbe0e154870437b11e17be72e427 (patch) | |
| tree | 71874f7cf337abfd06e1d40f0f6b088eec9d60fb /doc | |
| parent | 054f7665409170c0c6b8cd9f6e5e29b85ca35d8e (diff) | |
| download | rsyslog-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')
| -rw-r--r-- | doc/man_rsyslogd.html | 438 |
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> |