diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/imklog.html | 19 | ||||
| -rw-r--r-- | doc/imtcp.html | 10 | ||||
| -rw-r--r-- | doc/man_rsyslogd.html | 438 | ||||
| -rw-r--r-- | doc/manual.html | 20 | ||||
| -rw-r--r-- | doc/multi_ruleset.html | 275 | ||||
| -rw-r--r-- | doc/omoracle.html | 122 | ||||
| -rw-r--r-- | doc/queues.html | 6 | ||||
| -rw-r--r-- | doc/rsyslog_conf_global.html | 43 | ||||
| -rw-r--r-- | doc/v4compatibility.html | 77 |
10 files changed, 552 insertions, 461 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 0703b8fc..3dfc8d3a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -13,7 +13,6 @@ html_files = \ ipv6.html \ log_rotation_fix_size.html \ manual.html \ - man_rsyslogd.html \ modules.html \ property_replacer.html \ rsyslog_ng_comparison.html \ @@ -91,6 +90,7 @@ html_files = \ rsconf1_resetconfigvariables.html \ rsconf1_umask.html \ v3compatibility.html \ + v4compatibility.html \ im3195.html \ netstream.html \ ns_gtls.html \ @@ -111,6 +111,7 @@ html_files = \ rsyslog_conf_templates.html \ rsyslog_conf_nomatch.html \ queues_analogy.html \ + multi_ruleset.html \ src/classes.dia grfx_files = \ diff --git a/doc/imklog.html b/doc/imklog.html index 9166bae6..5bfab5ce 100644 --- a/doc/imklog.html +++ b/doc/imklog.html @@ -34,9 +34,9 @@ handled. The default is "off", in which case these messages are ignored. Switch it to on to submit non-kernel messages to rsyslog processing.<span style="font-weight: bold;"></span></li> <li><span style="font-weight: bold;"></span>$DebugPrintKernelSymbols -(imklog) [on/<b>off</b>]<br> +[on/<b>off</b>]<br> Linux only, ignored on other platforms (but may be specified)</li> -<li>$klogSymbolLookup (imklog) [on/<b>off</b>] -- +<li>$klogSymbolLookup [on/<b>off</b>] -- disables imklog kernel symbol translation (former klogd -x option). NOTE that this option is counter-productive on recent kernels (>= 2.6) because the kernel already does the symbol translation and this option breaks the information.<br> @@ -44,10 +44,19 @@ kernel already does the symbol translation and this option breaks the informatio it except if you have a very good reason. If you have one, let us know because otherwise new versions will no longer support it.<br> Linux only, ignored on other platforms (but may be specified)</li> -<li>$klogUseSyscallInterface (imklog) [on/<b>off</b>] +<li><b>$klogConsoleLogLevel</b> [<i>number</i>] +(former klogd -c option) -- sets the console log level. If specified, only messages with +up to the specified level are printed to the console. The default is -1, which means that +the current settings are not modified. To get this behavior, do not specify +$klogConsoleLogLevel in the configuration file. Note that this is a global parameter. Each time +it is changed, the previous definition is re-set. The one activate will be that one that is +active when imklog actually starts processing. In short words: do not specify this +directive more than once! +<br><b>Linux only</b>, ignored on other platforms (but may be specified)</li> +<li><b>$klogUseSyscallInterface</b> [on/<b>off</b>] -- former klogd -s option<br> Linux only, ignored on other platforms (but may be specified)</li> -<li>$klogSymbolsTwice (imklog) [on/<b>off</b>] -- +<li>$klogSymbolsTwice [on/<b>off</b>] -- former klogd -2 option<br> Linux only, ignored on other platforms (but may be specified)<br style="font-weight: bold;"> </li> @@ -69,7 +78,7 @@ is needed to start pulling kernel messages.<br> <p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a> project.<br> -Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer +Copyright © 2008-2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 3 or higher.</font></p> diff --git a/doc/imtcp.html b/doc/imtcp.html index 9ea7efa1..5217634e 100644 --- a/doc/imtcp.html +++ b/doc/imtcp.html @@ -43,15 +43,19 @@ can be found at the <a href="http://www.rsyslog.com/Article321.phtml">Cisco tcp page. <li>$InputTCPServerRun <port><br> Starts a TCP server on selected port</li> -<li><ul><li>$InputTCPMaxSessions <number></li></ul> -Sets the maximum number of sessions supported</li><li>$InputTCPServerStreamDriverMode <number><br> +<li>$InputTCPMaxListeners <number><br> +Sets the maximum number of listeners (server ports) supported. Default is 20. This must be set before the first $InputTCPServerRun directive.</li> +<li>$InputTCPMaxSessions <number><br> +Sets the maximum number of sessions supported. Default is 200. This must be set before the first $InputTCPServerRun directive</li> +<li>$InputTCPServerStreamDriverMode <number><br> Sets the driver mode for the currently selected <a href="netstream.html">network stream driver</a>. <number> is driver specifc.</li> <li>$InputTCPServerInputName <name><br> Sets a name for the inputname property. If no name is set "imtcp" is used by default. Setting a name is not strictly necessary, but can be useful to apply filtering based on which input the message was received from. <li>$InputTCPServerStreamDriverAuthMode <mode-string><br> -Sets the authentication mode for the currently selected <a href="netstream.html">network stream driver</a>. <mode-string> is driver specifc.</li><li>$InputTCPServerStreamDriverPermittedPeer <id-string><br> +Sets the authentication mode for the currently selected <a href="netstream.html">network stream driver</a>. <mode-string> is driver specifc.</li> +<li>$InputTCPServerStreamDriverPermittedPeer <id-string><br> Sets permitted peer IDs. Only these peers are able to connect to the listener. <id-string> semantics depend on the currently selected AuthMode and <a href="netstream.html">network stream driver</a>. PermittedPeers may not be set in anonymous modes.</li> diff --git a/doc/man_rsyslogd.html b/doc/man_rsyslogd.html deleted file mode 100644 index d18fd88a..00000000 --- a/doc/man_rsyslogd.html +++ /dev/null @@ -1,438 +0,0 @@ -<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 original 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 paths - 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 duplication. 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 perception 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 annoyances. - -<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> diff --git a/doc/manual.html b/doc/manual.html index 19332b33..e1f7480e 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -19,21 +19,22 @@ rsyslog support</a> available directly from the source!</p> <p><b>Please visit the <a href="http://www.rsyslog.com/sponsors">rsyslog sponsor's page</a> to honor the project sponsors or become one yourself!</b> We are very grateful for any help towards the project goals.</p> -<p><b>This documentation is for version 4.4.1 (v4-stable) of rsyslog.</b> -Visit the <i> <a href="http://www.rsyslog.com/doc-status.html">rsyslog status page</a></i></b> to obtain current -version information and project status. +<p><b>This documentation is for version 4.5.2 (v4-beta branch) of rsyslog.</b> +Visit the <i><a href="http://www.rsyslog.com/doc-status.html">rsyslog status page</a></i></b> +to obtain current version information and project status. </p><p><b>If you like rsyslog, you might want to lend us a helping hand. </b>It doesn't require a lot of time - even a single mouse click helps. Learn <a href="how2help.html">how to help the rsyslog project</a>. Due to popular demand, there is now a <a href="rsyslog_ng_comparison.html">side-by-side comparison between rsyslog and syslog-ng</a>.</p> <p>If you are upgrading from rsyslog v2 or stock sysklogd, -<a href="v3compatibility.html">be -sure to read the rsyslog v3 compatibility document!</a> It will work even +<a href="v3compatibility.html">be sure to read the rsyslog v3 compatibility document</a>, +and if you are upgrading from v3, read the +<a href="v4compatibility.html">rsyslog v4 compatibility document</a>. +<p>Rsyslog will work even if you do not read the doc, but doing so will definitely improve your experience.</p> -<p><span style="font-weight: bold;"></span><b>Follow -the links below for the</b><br></p><ul> - +<p><b>Follow the links below for the</b></p> +<ul> <li><a href="troubleshoot.html">troubleshooting rsyslog problems</a></li> <li><a href="rsyslog_conf.html">configuration file syntax (rsyslog.conf)</a></li> <li><a href="http://www.rsyslog.com/tool-regex">a regular expression checker/generator tool for rsyslog</a></li> @@ -42,7 +43,7 @@ the links below for the</b><br></p><ul> <li><a href="bugs.html">rsyslog bug list</a></li> <li><a href="rsyslog_packages.html"> rsyslog packages</a></li> <li><a href="generic_design.html">backgrounder on -generic syslog application design</a><!-- not good as it currently is ;) <li><a href="contributors.html">contributor "Hall of Fame"</a>--></li> +generic syslog application design</a> <li><a href="modules.html">description of rsyslog modules</a></li> </ul> <p><b>We have some in-depth papers on</b></p> @@ -51,6 +52,7 @@ generic syslog application design</a><!-- not good as it currently is ;) <li><a <li><a href="build_from_repo.html">obtaining rsyslog from the source repository</a></li> <li><a href="ipv6.html">rsyslog and IPv6</a> (which is fully supported)</li> <li><a href="rsyslog_secure_tls.html">native TLS encryption for syslog</a></li> +<li><a href="multi_ruleset.html">using multiple rule sets in rsyslog</a></li> <li><a href="rsyslog_stunnel.html">ssl-encrypting syslog with stunnel</a></li> <li><a href="rsyslog_mysql.html">writing syslog messages to MySQL (and other databases as well)</a></li> <li><a href="rsyslog_high_database_rate.html">writing massive amounts of syslog messages to a database</a></li> diff --git a/doc/multi_ruleset.html b/doc/multi_ruleset.html new file mode 100644 index 00000000..8d8c614f --- /dev/null +++ b/doc/multi_ruleset.html @@ -0,0 +1,275 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head> +<title>Multiple Rulesets in rsyslog</title></head> +<body> +<h1>Multiple Rulesets in rsyslog</h1> +<p>Starting with version 4.5.0 and 5.1.1, <a href="http://www.rsyslog.com">rsyslog</a> supports +multiple rulesets within a single configuration. +This is especially useful for routing the recpetion of remote messages to a set of specific rules. +Note that the input module must support binding to non-standard rulesets, so the functionality +may not be available with all inputs. +<p>In this document, I am using <a href="imtcp.html">imtcp</a>, an input module +that supports binding to non-standard rulesets since rsyslog started to support them. +<h2>What is a Ruleset?</h2> +If you have worked with (r)syslog.conf, you know that it is made up of what I call rules (others +tend to call them selectors, a sysklogd term). Each rule consist of a filter and one or more +actions to be carried out when the filter evaluates to true. A filter may be as simple as a +traditional +syslog priority based filter (like "*.*" or "mail.info" or a as complex as a +script-like expression. Details on that are covered in the config file documentation. After the +filter come action specifiers, and an action is something that does something to a message, e.g. +write it to a file or forward it to a remote logging server. + +<p>A traditional configuration file is made up of one or more of these rules. When a new +message arrives, its processing starts with the first rule (in order of appearance in +rsyslog.conf) and continues for each rule until either all rules have been processed or +a so-called "e;discard" action happens, in which case processing stops and the +message is thrown away (what also happens after the last rule has been processed). + +<p>The <b>multi-ruleset</b> support now permits to specify more than one such rule sequence. +You can think of a traditional config file just as a single default rule set, which is +automatically bound to each of the inputs. This is even what actually happens. When +rsyslog.conf is processed, the config file parser looks for the directive + +<pre>$RuleSet <name> +</pre> + +<p>Where name is any name the user likes (but must not start with "RSYSLOG_", which +is the name space reserved for rsyslog use). If it finds this directive, it begins a new +rule set (if the name was not yet know) or switches to an already-existing one (if the name +was known). All rules defined between this $RuleSet directive and the next one are appended +to the named ruleset. Note that the reserved name "RSYSLOG_DefaultRuleset" is used to +specify rsyslogd's default ruleset. You can use that name whereever you can use a ruleset name, +including when binding an input to it. + +<p>Inside a ruleset, messages are processed as described above: they start with the first rule +and rules are processed in the order of appearance of the configuration file until either +there are no more rules or the discard action is executed. Note that with multiple rulesets +no longer <b>all</b> rsyslog.conf rules are executed but <b>only</b> those that are +contained within the specific ruleset. + +<p>Inputs must explicitely bind to rulesets. If they don't do, the default ruleset is bound. + +<p>This brings up the next question: + +<h2>What does "To bind to a Ruleset" mean?</h2> +<p>This term is used in the same sense as "to bind an IP address to an interface": +it means that a specific input, or part of an input (like a tcp listener) will use a specific +ruleset to "pass its messages to". So when a new message arrives, it will be processed +via the bound ruleset. Rule from all other rulesets are irrelevant and will never be processed. +<p>This makes multiple rulesets very handy to process local and remote message via +seperate means: bind the respective receivers to different rule sets, and you do not need +to seperate the messages by any other method. + +<p>Binding to rulesets is input-specifc. For imtcp, this is done via the + +<pre>$InputTCPServerBindRuleset <name> +</pre> + +directive. Note that "name"e; must be the name of a ruleset that is already defined +at the time the bind directive is given. There are many ways to make sure this happens, but +I personally think that it is best to define all rule sets at the top of rsyslog.conf and +define the inputs at the bottom. This kind of reverses the traditional recommended ordering, but +seems to be a really useful and straightforward way of doing things. +<h2>Can I use a different Ruleset as the default?</h2> +<p>This is possible by using the + +<pre>$DefaultRuleset <name> +</pre> + +Directive. Please note, however, that this directive is actually global: that is, it does not +modify the ruleset to which the next input is bound but rather provides a system-wide +default rule set for those inputs that did not explicitly bind to one. As such, the directive +can not be used as a work-around to bind inputs to non-default rulesets that do not support +ruleset binding. +<h2>Examples</h2> +<h3>Split local and remote logging</h3> +<p>Let's say you have a pretty standard system that logs its local messages to the usual +bunch of files that are specified in the default rsyslog.conf. As an example, your rsyslog.conf +might look like this: + +<pre> +# ... module loading ... +# The authpriv file has restricted access. +authpriv.* /var/log/secure +# Log all the mail messages in one place. +mail.* /var/log/maillog +# Log cron stuff +cron.* /var/log/cron +# Everybody gets emergency messages +*.emerg * +... more ... +</pre> + +<p>Now, you want to add receive messages from a remote system and log these to +a special file, but you do not want to have these messages written to the files +specified above. The traditional approach is to add a rule in front of all others that +filters on the message, processes it and then discards it: + +<pre> +# ... module loading ... +# process remote messages +:fromhost-ip, isequal, "192.0.2.1" /var/log/remotefile +& ~ +# only messages not from 192.0.21 make it past this point + +# The authpriv file has restricted access. +authpriv.* /var/log/secure +# Log all the mail messages in one place. +mail.* /var/log/maillog +# Log cron stuff +cron.* /var/log/cron +# Everybody gets emergency messages +*.emerg * +... more ... +</pre> + +<p>Note the tilde character, which is the discard action!. Also note that we assume that +192.0.2.1 is the sole remote sender (to keep it simple). + +<p>With multiple rulesets, we can simply define a dedicated ruleset for the remote reception +case and bind it to the receiver. This may be written as follows: + +<pre> +# ... module loading ... +# process remote messages +# define new ruleset and add rules to it: +$RuleSet remote +*.* /var/log/remotefile +# only messages not from 192.0.21 make it past this point + +# bind ruleset to tcp listener +$InputTCPServerBindRuleset remote +# and activate it: +$InputTCPServerRun 10514 + +# switch back to the default ruleset: +$RuleSet RSYSLOG_DefaultRuleset +# The authpriv file has restricted access. +authpriv.* /var/log/secure +# Log all the mail messages in one place. +mail.* /var/log/maillog +# Log cron stuff +cron.* /var/log/cron +# Everybody gets emergency messages +*.emerg * +... more ... +</pre> + +<p>Here, we need to switch back to the default ruleset after we have defined our custom +one. This is why I recommend a different ordering, which I find more intuitive. The sample +below has it, and it leads to the same results: + +<pre> +# ... module loading ... +# at first, this is a copy of the unmodified rsyslog.conf +# The authpriv file has restricted access. +authpriv.* /var/log/secure +# Log all the mail messages in one place. +mail.* /var/log/maillog +# Log cron stuff +cron.* /var/log/cron +# Everybody gets emergency messages +*.emerg * +... more ... +# end of the "regular" rsyslog.conf. Now come the new definitions: + +# process remote messages +# define new ruleset and add rules to it: +$RuleSet remote +*.* /var/log/remotefile + +# bind ruleset to tcp listener +$InputTCPServerBindRuleset remote +# and activate it: +$InputTCPServerRun 10514 +</pre> + +<p>Here, we do not switch back to the default ruleset, because this is not needed as it is +completely defined when we begin the "remote" ruleset. + +<p>Now look at the examples and compare them to the single-ruleset solution. You will notice +that we do <b>not</b> need a real filter in the multi-ruleset case: we can simply use +"*.*" as all messages now means all messages that are being processed by this +rule set and all of them come in via the TCP receiver! This is what makes using multiple +rulesets so much easier. + +<h3>Split local and remote logging for three different ports</h3> +<p>This example is almost like the first one, but it extends it a little bit. While it is +very similar, I hope it is different enough to provide a useful example why you may want +to have more than two rulesets. + +<p>Again, we would like to use the "regular" log files for local logging, only. But +this time we set up three syslog/tcp listeners, each one listening to a different +port (in this example 10514, 10515, and 10516). Logs received from these receivers shall go into +different files. Also, logs received from 10516 (and only from that port!) with +"mail.*" priority, shall be written into a specif file and <b>not</b> be +written to 10516's general log file. + +<p>This is the config: + +<pre> +# ... module loading ... +# at first, this is a copy of the unmodified rsyslog.conf +# The authpriv file has restricted access. +authpriv.* /var/log/secure +# Log all the mail messages in one place. +mail.* /var/log/maillog +# Log cron stuff +cron.* /var/log/cron +# Everybody gets emergency messages +*.emerg * +... more ... +# end of the "regular" rsyslog.conf. Now come the new definitions: + +# process remote messages + +#define rulesets first +$RuleSet remote10514 +*.* /var/log/remote10514 + +$RuleSet remote10515 +*.* /var/log/remote10515 + +$RuleSet remote10516 +mail.* /var/log/mail10516 +& ~ +# note that the discard-action will prevent this messag from +# being written to the remote10516 file - as usual... +*.* /var/log/remote10516 + +# and now define listners bound to the relevant ruleset +$InputTCPServerBindRuleset remote10514 +$InputTCPServerRun 10514 + +$InputTCPServerBindRuleset remote10515 +$InputTCPServerRun 10515 + +$InputTCPServerBindRuleset remote10516 +$InputTCPServerRun 10516 +</pre> + +<p>Note that the "mail.*" rule inside the "remote10516"e; ruleset does +not affect processing inside any other rule set, including the default rule set. + + +<h2>Performance</h2> +<p>No rule processing can be faster than not processing a rule at all. As such, it is useful +for a high performance system to identify disjunct actions and try to split these off to +different rule sets. In the example section, we had a case where three different tcp listeners +need to write to three different files. This is a perfect example of where multiple rule sets +are easier to use and offer more performance. The performance is better simply because there +is no need to check the reception service - instead messages are automatically pushed to the +right rule set and can be processed by very simple rules (maybe even with +"*.*"-filters, the fastest ones available). + +<p>In the long term, multiple rule sets will probably lay the foundation for even better +optimizations. So it is not a bad idea to get aquainted with them. + +<p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> +<p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a> +project.<br> +Copyright © 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and +<a href="http://www.adiscon.com/">Adiscon</a>. +Released under the GNU GPL version 3 or higher.</font></p> +</body></html> diff --git a/doc/omoracle.html b/doc/omoracle.html index 40f6360f..cfcf277f 100644 --- a/doc/omoracle.html +++ b/doc/omoracle.html @@ -67,6 +67,128 @@ it is suggested to post questions to the need to define the properties on the template in the correct order you want them passed to the statement! </pre> +<p>Some additional documentation contributed by Ronny Egner: +<pre> +REQUIREMENTS: +-------------- + +- Oracle Instantclient 10g (NOT 11g) Base + Devel + (if you´re on 64-bit linux you should choose the 64-bit libs!) +- JDK 1.6 (not neccessary for oracle plugin but "make" didd not finsished successfully without it) + +- "oracle-instantclient-config" script + (seems to shipped with instantclient 10g Release 1 but i was unable to find it for 10g Release 2 so here it is) + + +====================== /usr/local/bin/oracle-instantclient-config ===================== +#!/bin/sh +# +# Oracle InstantClient SDK config file +# Jean-Christophe Duberga - Bordeaux 2 University +# + +# just adapt it to your environment +incdirs="-I/usr/include/oracle/10.2.0.4/client64" +libdirs="-L/usr/lib/oracle/10.2.0.4/client64/lib" + +usage="\ +Usage: oracle-instantclient-config [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version] [--cflags] [--libs] [--static-libs]" + +if test $# -eq 0; then + echo "${usage}" 1>&2 + exit 1 +fi + +while test $# -gt 0; do + case "$1" in + -*=*) optarg=`echo "$1" | sed 's/[-_a-zA-Z0-9]*=//'` ;; + *) optarg= ;; + esac + + case $1 in + --prefix=*) + prefix=$optarg + if test $exec_prefix_set = no ; then + exec_prefix=$optarg + fi + ;; + --prefix) + echo $prefix + ;; + --exec-prefix=*) + exec_prefix=$optarg + exec_prefix_set=yes + ;; + --exec-prefix) + echo ${exec_prefix} + ;; + --version) + echo ${version} + ;; + --cflags) + echo ${incdirs} + ;; + --libs) + echo $libdirs -lclntsh -lnnz10 -locci -lociei -locijdbc10 + ;; + --static-libs) + echo "No static libs" 1>&2 + exit 1 + ;; + *) + echo "${usage}" 1>&2 + exit 1 + ;; + esac + shift +done + +=============== END ============== + + + + +COMPILING RSYSLOGD +------------------- + + +./configure --enable-oracle + + + + +RUNNING +------- + +- make sure rsyslogd is able to locate the oracle libs (either via LD_LIBRARY_PATH or /etc/ld.so.conf) +- set TNS_ADMIN to point to your tnsnames.ora +- create a tnsnames.ora and test you are able to connect to the database + +- create user in oracle as shown in the following example: + create user syslog identified by syslog default tablespace users quota unlimited on users; + grant create session to syslog; + create role syslog_role; + grant syslog_role to syslog; + grant create table to syslog_role; + grant create sequence to syslog_role; + +- create tables as needed + +- configure rsyslog as shown in the following example + $ModLoad omoracle + + $OmoracleDBUser syslog + $OmoracleDBPassword syslog + $OmoracleDB syslog + $OmoracleBatchSize 1 + $OmoracleBatchItemSize 4096 + + $OmoracleStatementTemplate OmoracleStatement + $template OmoracleStatement,"insert into foo(hostname,message) values (:host,:message)" + $template TestStmt,"%hostname%%msg%" + *.* :omoracle:;TestStmt + (you guess it: username = password = database = "syslog".... see $rsyslogd_source/plugins/omoracle/omoracle.c for me info) +</pre> <p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> <p><font size="2">This documentation is part of the diff --git a/doc/queues.html b/doc/queues.html index 4a9509a0..45ce1bd1 100644 --- a/doc/queues.html +++ b/doc/queues.html @@ -115,7 +115,11 @@ isolation. This is currently selected by specifying different <i>$WorkDirectory< config directives before the queue creation statement.</p> <p>To create a disk queue, use the "<i>$<object>QueueType Disk</i>" config directive. Checkpoint intervals can be specified via "<i>$<object>QueueCheckpointInterval</i>", -with 0 meaning no checkpoints. </p> +with 0 meaning no checkpoints. Note that disk-based queues can be made very reliable +by issuing a (f)sync after each write operation. Starting with version 4.3.2, this can +be requested via "<i><object>QueueSyncQueueFiles on/off</i> with the +default being off. Activating this option has a performance penalty, so it should +not be turned on without reason.</p> <h2>In-Memory Queues</h2> <p>In-memory queue mode is what most people have on their mind when they think about computing queues. Here, the enqueued data elements are held in memory. diff --git a/doc/rsyslog_conf_global.html b/doc/rsyslog_conf_global.html index 7dda046f..50d83a50 100644 --- a/doc/rsyslog_conf_global.html +++ b/doc/rsyslog_conf_global.html @@ -99,6 +99,13 @@ netstream drivers. For all others, it will be ignored. <li>$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer. Note that this directive requires TLS netstream drivers. For all others, it will be ignored. (driver-specific) -<span style="font-weight: bold;"> directive may go away</span>!</li> +<li><b>$ActionSendTCPRebindInterval</b> nbr</a>- [available since 4.5.1] - instructs the TCP send +action to close and re-open the connection to the remote host every nbr of messages sent. +Zero, the default, means that no such processing is done. This directive is useful for +use with load-balancers. Note that there is some performance overhead associated with it, +so it is advisable to not too often "rebind" the connection (what +"too often" actually means depends on your configuration, a rule of thumb is +that it should be not be much more often than once per second).</li> <li><b>$ActionSendUDPRebindInterval</b> nbr</a>- [available since 4.3.2] - instructs the UDP send action to rebind the send socket every nbr of messages sent. Zero, the default, means that no rebind is done. This directive is useful for use with load-balancers.</li> @@ -111,6 +118,10 @@ that no rebind is done. This directive is useful for use with load-balancers.</l <li>$DefaultNetstreamDriver <drivername>, the default <a href="netstream.html">network stream driver</a> to use. Defaults to ptcp.$DefaultNetstreamDriverCAFile </path/to/cafile.pem></li> <li>$DefaultNetstreamDriverCertFile </path/to/certfile.pem></li> <li>$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem></li> +<li><b>$DefaultRuleset</b> <i>name</i> - changes the default ruleset for unbound inputs to +the provided <i>name</i> (the default default ruleset is named +"RSYSLOG_DefaultRuleset"). It is advised to also read +our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li> <li><b>$CreateDirs</b> [<b>on</b>/off] - create directories on an as-needed basis</li> <li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li> <li><a href="rsconf1_dirgroup.html">$DirGroup</a></li> @@ -128,11 +139,15 @@ that no rebind is done. This directive is useful for use with load-balancers.</l <li><a href="rsconf1_gssforwardservicename.html">$GssForwardServiceName</a></li> <li><a href="rsconf1_gsslistenservicename.html">$GssListenServiceName</a></li> <li><a href="rsconf1_gssmode.html">$GssMode</a></li> -<li>$HUPisRestart [<b>on</b>/off] - if set to on, a HUP is a full daemon restart. This means any queued messages are discarded (depending +<li>$HUPisRestart [on/<b>off</b>] - if set to on, a HUP is a full daemon restart. This means any queued messages are discarded (depending on queue configuration, of course) all modules are unloaded and reloaded. This mode keeps compatible with sysklogd, but is -not recommended for use with rsyslog. To do a full restart, simply stop and start the daemon. The default is "on" for -compatibility reasons. If it is set to "off", a HUP will only close open files. This is a much quicker action and usually -the only one that is needed e.g. for log rotation. <b>It is recommended to set the setting to "off".</b></li> +not recommended for use with rsyslog. To do a full restart, simply stop and start the daemon. The default (since 4.5.1) is "off". +If it is set to "off", a HUP will only close open files. This is a much quicker action and usually +the only one that is needed e.g. for log rotation. <b>Restart-type HUPs (value "on") are depricated</b> +and will go away in rsyslog v5. So it is a good idea to change anything that needs it, now. +Usually that should not be a big issue, as the restart-type HUP can easily be replaced by +something along the lines of "/etc/init.d/rsyslog restart". +</li> <li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li><li>MainMsgQueueCheckpointInterval <number></li> <li>$MainMsgQueueDequeueSlowdown <number> [number is timeout in <i> micro</i>seconds (1000000us is 1sec!), @@ -192,6 +207,20 @@ supported in order to be compliant to the upcoming new syslog RFC series. <li><a href="rsconf1_maxopenfiles.html">$MaxOpenFiles</a></li> <li><a href="rsconf1_moddir.html">$ModDir</a></li> <li><a href="rsconf1_modload.html">$ModLoad</a></li> +<li><b>$OMFileZipLevel</b> 0..9 [default 0] - if greater 0, turns on gzip compression +of the output file. The higher the number, the better the compression, but also the +more CPU is required for zipping.</li> +<li><b>$OMFileIOBufferSize</b> <size_nbr>, default 4k, size of the buffer used to writing output data. The larger the buffer, the potentially better performance is. The default of 4k is quite conservative, it is useful to go up to 64k, and 128K if you used gzip compression (then, even higher sizes may make sense)</li> +<li><b>$OMFileFlushOnTXEnd</b> <[<b>on</b>/off]>, default on. Omfile has the +capability to +writes output using a buffered writer. Disk writes are only done when the buffer is +full. So if an error happens during that write, data is potentially lost. In cases where +this is unacceptable, set $OMFileFlushOnTXEnd to on. Then, data is written at the end +of each transaction (for pre-v5 this means after <b>each</b> log message) and the usual +error recovery thus can handle write errors without data loss. Note that this option +severely reduces the effect of zip compression and should be switched to off +for that use case. Note that the default -off- is primarily an aid to preserve +the traditional syslogd behaviour.</li> <li><b>$RepeatedMsgContainsOriginalMsg</b> [on/<b>off</b>] - "last message repeated n times" messages, if generated, have a different format that contains the message that is being repeated. Note that only the first "n" characters are included, with n to be at least 80 characters, most @@ -200,6 +229,12 @@ line is that n is large enough to get a good idea which message was repeated but large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.</li> <li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li> <li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li> +<li><b>$Ruleset</b> <i>name</i> - starts a new ruleset or switches back to one already defined. +All following actions belong to that new rule set. +the <i>name</i> does not yet exist, it is created. To swith back to rsyslog's +default ruleset, specify "RSYSLOG_DefaultRuleset") as the name. +All following actions belong to that new rule set. It is advised to also read +our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a>.</li> <li><b>$OptimizeForUniprocessor</b> [on/<b>off</b>] - turns on optimizatons which lead to better performance on uniprocessors. If you run on multicore-machiens, turning this off lessens CPU load. The default may change as uniprocessor systems become less common. [available since 4.1.0]</li> diff --git a/doc/v4compatibility.html b/doc/v4compatibility.html new file mode 100644 index 00000000..5d877af1 --- /dev/null +++ b/doc/v4compatibility.html @@ -0,0 +1,77 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>Compatibility notes for rsyslog v4</title> +</head> +<body> +<h1>Compatibility Notes for rsyslog v4</h1> +<p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> +(2009-07-15)</i></small></p> +<p>The changes introduced in rsyslog v4 are numerous, but not very intrusive. +This document describes things to keep in mind when moving from v3 to v4. It +does not list enhancements nor does it talk about compatibility concerns introduced +by v3 (for this, see the <a href="v3compatibility.html">rsyslog v3 compatibility notes</a>). +<h2>HUP processing</h2> +<p>With v3 and below, rsyslog used the traditional HUP behaviour. That meant that +all output files are closed and the configuration file is re-read and the new configuration +applied. +<p>With a program as simple and static as sysklogd, this was not much of an issue. The +most important config settings (like udp reception) of a traditional syslogd can not be +modified via the configuration file. So a config file reload only meant setting up a new set of filters. It also didn't account as problem that while doing so messages may be lost - without +any threading and queuing model, a traditional syslogd will potentially always loose +messages, so it is irrelevant if this happens, too, during the short config re-read +phase. +<p>In rsyslog, things are quite different: the program is more or less a framework into +which loadable modules are loaded as needed for a particular configuration. The software +that will acutally be running is taylored via the config file. Thus, a re-read of +the config file requires a full, very heavy restart, because the software acutally +running with the new config can be totally different from what ran with the old config. +<p>Consequently, the traditional HUP is a very heavy operation and may even cause some +data loss because queues must be shut down, listeners stopped and so on. Some of these +operations (depending on their configuration) involve intentional message loss. The operation +also takes up a lot of system resources and needs quite some time (maybe seconds) to be +completed. During this restart period, the syslog subsytem is not fully available. +<p>From the software developer's point of view, the full restart done by a HUP is rather complex, +especially if user-timeout limits set on action completion are taken into consideration (for +those in the know: at the extreme ends this means we need to cancel threads as a last resort, +but than we need to make sure that such cancellation does not happen at points where it +would be fatal for a restart). A regular restart, where the process is actually terminated, is +much less complex, because the operating system does a full cleanup after process termination, +so rsyslogd does not need to take care for exotic cleanup cases and leave that to the OS. +In the end result, restart-type HUPs clutter the code, increase complexity (read: add bugs) +and cost performance. +<p>On the contrary, a HUP is typically needed for log rotation, and the real desire is +to close files. This is a non-disruptive and very lightweigth operation. +<p>Many people have said that they are used to HUP the syslogd to apply configuration +changes. This is true, but it is questionable if that really justifies all the cost that +comes with it. After all, it is the difference between typing +<pre> +$ kill -HUP `cat /var/run/rsyslogd.pid` +</pre> +versus +<pre> +$ /etc/init.d/rsyslog restart +</pre> +Semantically, both is mostly the same thing. The only difference is that with the restart +command rsyslogd can spit config error message to stderr, so that the user is able to see +any problems and fix them. With a HUP, we do not have access to stderr and thus can log +error messages only to their configured destinations; exprience tells that most users +will never find them there. What, by the way, is another strong argument against +restarting rsyslogd by HUPing it. +<p>So a restart via HUP is not strictly necessary +and most other deamons require that a restart command is typed in if a restart is required. +<p>Rsyslog will follow this paradigm in the next versions, resulting in many benefits. In v4, +we provide some support for the old-style semantics. We introduced a setting $HUPisRestart +which may be set to "on" (tradional, heavy operationg) +or "off" (new, lightweight "file close only" operation). +The initial versions had the default set to traditional behavior, but starting with 4.5.1 +we are now using the new behavior as the default. +<p>Most importantly, <b>this may break some scripts</b>, but my sincere belief is that +there are very few scripts that automatically <b>change</b> rsyslog's config and then do a +HUP to reload it. Anyhow, if you have some of these, it may be a good idea to change +them now instead of turning restart-type HUPs on. Other than that, one mainly needs +to change the habit of how to restart rsyslog after a configuration change. +<p><b>Please note that restart-type HUP is depricated and will go away in rsyslog v5.</b> +So it is a good idea to become ready for the new version now and also enjoy some of the +benefits of the "real restart", like the better error-reporting capability. +<p>Note that code complexity reduction (and thus performance improvement) needs the restart-type +HUP code to be removed, so these changes can (and will) only happen in version 5. +</body></html> |