diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/design.tex | 74 | ||||
| -rw-r--r-- | doc/imfile.html | 11 | ||||
| -rw-r--r-- | doc/imklog.html | 5 | ||||
| -rw-r--r-- | doc/impstats.html | 8 | ||||
| -rw-r--r-- | doc/imptcp.html | 26 | ||||
| -rw-r--r-- | doc/imrelp.html | 9 | ||||
| -rw-r--r-- | doc/imtcp.html | 9 | ||||
| -rw-r--r-- | doc/imuxsock.html | 46 | ||||
| -rw-r--r-- | doc/manual.html | 19 | ||||
| -rw-r--r-- | doc/mmsnmptrapd.html | 9 | ||||
| -rw-r--r-- | doc/omlibdbi.html | 56 | ||||
| -rw-r--r-- | doc/ommysql.html | 46 | ||||
| -rw-r--r-- | doc/pmlastmsg.html | 7 | ||||
| -rw-r--r-- | doc/property_replacer.html | 66 | ||||
| -rw-r--r-- | doc/rsconf1_omfileforcechown.html | 5 | ||||
| -rw-r--r-- | doc/rsyslog_conf_global.html | 18 | ||||
| -rw-r--r-- | doc/rsyslog_conf_templates.html | 4 | ||||
| -rw-r--r-- | doc/rsyslog_ng_comparison.html | 235 | ||||
| -rw-r--r-- | doc/v6compatibility.html | 131 | ||||
| -rw-r--r-- | doc/version_naming.html | 4 |
20 files changed, 606 insertions, 182 deletions
diff --git a/doc/design.tex b/doc/design.tex index a3ec8f45..1def3fb7 100644 --- a/doc/design.tex +++ b/doc/design.tex @@ -811,10 +811,80 @@ b) we push the failed message back to the main queue, but with an indication that it failed in an action. This is harder to implement and most importantly harder to understand/configure, but more flexible +\section{Configuration System} +The configration system found in all versions up to v5 is based on sysklogd's +legacy. It does not have any clear distinction between config load and +activation. Starting with v6, a new config system is build. That new system +offers the necessary distinction. In the long term, the configuration language +will be enhanced towards the more flexible and easy to use RainerScript idea. + +\section{Plugin Interface} +This section describes some aspects of the plugin interface. +\subsection{Configuration Related} +To support the new v2 config system, plugins need to publish a number of entry +points that will be called by the rsyslog configuration section at various +stages of the configration load, activation and deactivation process. This list +may be extended as the configuration interface evolves. + +Plugins must not necessarily implement support for the v2 config system. If +they do, the ``beginCnfLoad'' entry point serves as a flag telling that support +is available. In that case, all other entry points need to be defined as well. +If a module does not support the v2 config system, it can still be run, but be +configured only via the legacy config system. Note that with the old system +there are also problems with droping privileges. So a legacy module may not +work correctly if privileges are dropped. + +The following entry points are available: +\begin{enumerate} + \item \emph{beginCnfLoad} -- called when a new config load begins. Only one +config load can be active at one time (no concurrent loads). + \item \emph{endCnfLoad} -- called when config load ends. This gives the module +a chance to do final changes and some cleanup. + \item \emph{checkCnf} -- called by the framework to verify a configuration. + \item \emph{activateCnfPrePrivDrop} -- called by the framework to activate a +configuration before privileges are dropped. This is an optional entry point +that shall only be implemented by plugins that need the do some processing +before rsyslog drops privileges. Processing inside this entry point should be +limited to what is absolutely necessary. The main activation work should be +done in activateCnf() as usual. + \item \emph{activateCnf} -- called by the framework to activate a +configuration. +\item \emph{freeCnf} -- called by the framework to free +(deallocate) a configuration. +\end{enumerate} + +In the current implementation, entry points are sequentially called as given +above. However, this will change. It is guaranteed that +\begin{itemize} + \item beginCnfLoad() will be followed by a matching endCnfLoad() and there +will be no new call to beginCnfLoad() before endCnfLoad() has been called. This +means no nested config load needs to be supported, + \item checkCnf() may be called at any time, even during a config load phase. +However, the config to check is a fully loaded one. + \item activateCnfPrePrivDrop(), if provided, will always be called before +activateCnf() is called. No other config-related calls will be made in between. +\end{itemize} + +\subsubsection{Output Modules} +The v1 config load system for output modules seems to provide all functionality +necessary to support the v2 system as well. As such, we currently do not +require output modules to implement the new calls to be fully supported by the +v2 system. + \section{Network Stream Subsystem} -The idea of network streams was introduced when we implemented RFC5425 (syslog over TLS) in 2008. The core idea is to encapsulate all stream-oriented network data transfer into a single transport layer and make the upper layers independent of actual transport being used. This is in line with the traditional layer approaches in communication systems. +The idea of network streams was introduced when we implemented RFC5425 (syslog +over TLS) in 2008. The core idea is to encapsulate all stream-oriented network +data transfer into a single transport layer and make the upper layers +independent of actual transport being used. This is in line with the traditional +layer approaches in communication systems. + +Under this system, the upper layer provides plugins to send and receive streams +of syslog data. Framing is provided by the upper layer. The upper layer itself +is integrated in input and output plugins, which then are used to provide +application-level syslog message objects to and from the rsyslog core. To these +upper layers, the netstream layer provides reliable and sequenced message +delivery with much of the same semantics as a usual TCP stream. -Under this system, the upper layer provides plugins to send and receive streams of syslog data. Framing is provided by the upper layer. The upper layer itself is integrated in input and output plugins, which then are used to provide application-level syslog message objects to and from the rsyslog core. To these upper layers, the netstream layer provides reliable and sequenced message delivery with much of the same semantics as a usual TCP stream. \begin{figure} \begin{center} diff --git a/doc/imfile.html b/doc/imfile.html index c44171df..7961729b 100644 --- a/doc/imfile.html +++ b/doc/imfile.html @@ -100,9 +100,16 @@ performance, especially when set to a low value. Frequently writing the state file is very time consuming. <li><b>$InputFileReadMode</b> [mode]</b><br> Available in 5.7.5+ +<li><b>$InputFileMaxLinesAtOnce</b> [number]</b><br> +Available in 5.9.0+ <br> -Mode to be used when reading lines. 0 (the default) means that each line is forwarded -as its own log message. +This is useful if multiple files need to be monitored. If set to 0, each file +will be fully processed and then processing switches to the next file +(this was the default in previous versions). If it is set, a maximum of +[number] lines is processed in sequence for each file, and then the file is +switched. This provides a kind of mutiplexing the load of multiple files and +probably leads to a more natural distribution of events when multiple busy files +are monitored. The default is 10240. <li>$InputFileBindRuleset <ruleset><br> Available in 5.7.5+, 6.1.5+ Binds the listener to a specific <a href="multi_ruleset.html">ruleset</a>.</li> diff --git a/doc/imklog.html b/doc/imklog.html index f273753f..2e3b3bc2 100644 --- a/doc/imklog.html +++ b/doc/imklog.html @@ -36,6 +36,11 @@ processing.<span style="font-weight: bold;"></span></li> <li><span style="font-weight: bold;"></span>$DebugPrintKernelSymbols [on/<b>off</b>]<br> Linux only, ignored on other platforms (but may be specified)</li> +<li><b>$klogLocalIPIF</b> [interface name] - (available since 5.9.6) - if provided, the IP of the specified +interface (e.g. "eth0") shall be used as fromhost-ip for imklog-originating messages. +If this directive is not given OR the interface cannot be found (or has no IP address), +the default of "127.0.0.1" is used. +</li> <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 diff --git a/doc/impstats.html b/doc/impstats.html index cede4874..64b04a30 100644 --- a/doc/impstats.html +++ b/doc/impstats.html @@ -18,7 +18,9 @@ prepared to change your trending scripts when you upgrade to a newer rsyslog ver output is periodic, with the interval being configurable (default is 5 minutes). Be sure that your configuration records the counter messages (default is syslog.info). <p>Note that loading this module has impact on rsyslog performance. Depending on -settings, this impact may be severe (for high-load environments). +settings, this impact may be noticable (for high-load environments). +<p>The rsyslog website has an updated overview of available +<a href="http://rsyslog.com/rsyslog-statistic-counter/">rsyslog statistic counters</a>. </p> <p><b>Configuration Directives</b>:</p> <ul> @@ -34,6 +36,10 @@ is 5 (syslog).This is useful for filtering messages.</li> <li>$PStatSeverity <numerical severity><br> The numerical syslog severity code to be used for generated messages. Default is 6 (info).This is useful for filtering messages.</li> +<li>$PStatJSON <on/<b>off</b>> (rsyslog v6.3.8+ only)<br> +If set to on, stats messages are emitted as structured cee-enhanced syslog. If +set to off, legacy format is used (which is compatible with pre v6-rsyslog). +</li> </ul> <b>Caveats/Known Bugs:</b> <ul> diff --git a/doc/imptcp.html b/doc/imptcp.html index c7a0e599..4307c603 100644 --- a/doc/imptcp.html +++ b/doc/imptcp.html @@ -43,9 +43,33 @@ very limited interest in fixing this issue. This directive <b>can not</b> fix th That would require much more code changes, which I was unable to do so far. Full details can be found at the <a href="http://www.rsyslog.com/Article321.phtml">Cisco tcp syslog anomaly</a> page. +<li><b>$InputPTCPSupportOctetCountedFraming</b> <<b>on</b>|off><br> +If set to "on", the legacy octed-counted framing (similar to RFC5425 framing) is +activated. This is the default and should be left unchanged until you know +very well what you do. It may be useful to turn it off, if you know this framing +is not used and some senders emit multi-line messages into the message stream. +</li> <li>$InputPTCPServerNotifyOnConnectionClose [on/<b>off</b>]<br> instructs imptcp to emit a message if the remote peer closes a connection.<br> -<li>$InputPTCPServerRun <port><br> +<li><b>$InputPTCPServerKeepAlive</b> <on/<b>off</b>><br> +enable of disable keep-alive packets at the tcp socket layer. The default is +to disable them.</li> +<li><b>$InputPTCPServerKeepAlive_probes</b> <number><br> +The number of unacknowledged probes to send before considering the connection dead and notifying the application layer. +The default, 0, means that the operating system defaults are used. This has only +effect if keep-alive is enabled. The functionality may not be available on +all platforms. +<li><b>$InputPTCPServerKeepAlive_intvl</b> <number><br> +The interval between subsequential keepalive probes, regardless of what the connection has exchanged in the meantime. +The default, 0, means that the operating system defaults are used. This has only +effect if keep-alive is enabled. The functionality may not be available on +all platforms. +<li><b>$InputPTCPServerKeepAlive_time</b> <number><br> +The interval between the last data packet sent (simple ACKs are not considered data) and the first keepalive probe; after the connection is marked to need keepalive, this counter is not used any further. +The default, 0, means that the operating system defaults are used. This has only +effect if keep-alive is enabled. The functionality may not be available on +all platforms. +<li><b>$InputPTCPServerRun</b> <port><br> Starts a TCP server on selected port</li> <li>$InputPTCPServerInputName <name><br> Sets a name for the inputname property. If no name is set "imptcp" is used by default. Setting a diff --git a/doc/imrelp.html b/doc/imrelp.html index 2cf9c1f7..d83b2a15 100644 --- a/doc/imrelp.html +++ b/doc/imrelp.html @@ -29,6 +29,8 @@ syslog and so it is highly suggested to use RELP instead of plain tcp. Clients send messages to the RELP server via omrelp.</p> <p><b>Configuration Directives</b>:</p> <ul> +<li>InputRELPServerBindRuleset <name> (available in 6.3.6+)</br> +Binds the specified ruleset to all RELP listeners. <li>InputRELPServerRun <port><br> Starts a RELP server on selected port</li> </ul> @@ -38,6 +40,8 @@ Starts a RELP server on selected port</li> <li>To obtain the remote system's IP address, you need to have at least librelp 1.0.0 installed. Versions below it return the hostname instead of the IP address.</li> +<li>Contrary to other inputs, the ruleset can only be bound to all listeners, +not specific ones. This is due to a currently existing limitation in librelp. </ul> <p><b>Sample:</b></p> <p>This sets up a RELP server on port 20514.<br> @@ -48,9 +52,8 @@ $InputRELPServerRun 20514 <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 -<a href="http://www.rsyslog.com/">rsyslog</a> -project.<br> -Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer +<a href="http://www.rsyslog.com/">rsyslog</a> project.<br> +Copyright © 2008-2011 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 b0aaa3c1..649b08f8 100644 --- a/doc/imtcp.html +++ b/doc/imtcp.html @@ -55,6 +55,9 @@ so be prepared to wrangle with that! instructs imtcp to emit a message if the remote peer closes a connection.<br> <b>Important:</b> This directive is global to all listeners and must be given right after loading imtcp, otherwise it may have no effect.</li> +<li><b>$InputTCPServerKeepAlive</b> <on/<b>off</b>><br> +enable of disable keep-alive packets at the tcp socket layer. The default is +to disable them.</li> <li><b>$InputTCPServerRun</b> <port><br> Starts a TCP server on selected port</li> <li><b>$InputTCPFlowControl</b> <<b>on</b>/off><br> @@ -83,6 +86,12 @@ 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> <li><b>$InputTCPServerBindRuleset</b> <ruleset><br> Binds the listener to a specific <a href="multi_ruleset.html">ruleset</a>.</li> +<li><b>$InputTCPSupportOctetCountedFraming</b> <<b>on</b>|off><br> +If set to "on", the legacy octed-counted framing (similar to RFC5425 framing) is +activated. This is the default and should be left unchanged until you know +very well what you do. It may be useful to turn it off, if you know this framing +is not used and some senders emit multi-line messages into the message stream. +</li> </ul> <b>Caveats/Known Bugs:</b> <ul> diff --git a/doc/imuxsock.html b/doc/imuxsock.html index ee5db22d..34a696d9 100644 --- a/doc/imuxsock.html +++ b/doc/imuxsock.html @@ -49,6 +49,15 @@ are places as quickly as possible into the processing queues. If you would like flow control, you need to enable it via the $SystemLogSocketFlowControl and $InputUnixListenSocketFlowControl config directives. Just make sure you thought about the implications. Note that for many systems, turning on flow control does not hurt. +<p>Starting with rsyslog 5.9.4, +<b><a href="http://www.rsyslog.com/what-are-trusted-properties/">trusted syslog properties</a> +are available</b>. These require a recent enough Linux Kernel and access to the /proc file +system. In other words, this may not work on all platforms and may not work fully when +privileges are dropped (depending on how they are dropped). Note that trusted properties +can be very useful, but also typically cause the message to grow rather large. Also, the +format of log messages is obviously changed by adding the trusted properties at the end. +For these reasons, the feature is <b>not enabled by default</b>. If you want to use it, +you must turn it on (via $SystemLogSocketAnnotate and $InputUnixListenSocketAnnotate). <p><b>Configuration Directives</b>:</p> <ul> <li><b>$InputUnixListenSocketIgnoreMsgTimestamp</b> [<b>on</b>/off] @@ -56,7 +65,10 @@ the implications. Note that for many systems, turning on flow control does not h <li><b>$InputUnixListenSocketFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied to the next socket.</li> <li><b>$IMUXSockRateLimitInterval</b> [number] - specifies the rate-limiting -interval in seconds. Default value is 5 seconds. Set it to 0 to turn rate limiting off. +interval in seconds. Default value is 0, which turns off rate limiting. Set it to a number +of seconds (5 recommended) to activate rate-limiting. The default of 0 has been choosen in 5.9.6+, +as people experienced problems with this feature activated by default. Now it needs an +explicit opt-in by setting this parameter. </li> <li><b>$IMUXSockRateLimitBurst</b> [number] - specifies the rate-limiting burst in number of messages. Default is 200. @@ -64,13 +76,27 @@ burst in number of messages. Default is 200. <li><b>$IMUXSockRateLimitSeverity</b> [numerical severity] - specifies the severity of messages that shall be rate-limited. </li> +<li><b>$IMUXSockLocalIPIF</b> [interface name] - (available since 5.9.6) - if provided, the IP of the specified +interface (e.g. "eth0") shall be used as fromhost-ip for imuxsock-originating messages. +If this directive is not given OR the interface cannot be found (or has no IP address), +the default of "127.0.0.1" is used. +</li> <li><b>$InputUnixListenSocketUsePIDFromSystem</b> [on/<b>off</b>] - specifies if the pid being logged shall be obtained from the log socket itself. If so, the TAG part of the message is rewritten. It is recommended to turn this option on, but the default is "off" to keep compatible with earlier versions of rsyslog. This option was introduced in 5.7.0.</li> +<li><b>$InputUnixListenSocketUseSysTimeStamp</b> [<b>on</b>/off] instructs imuxsock +to obtain message time from the system (via control messages) insted of using time +recorded inside the message. This may be most useful in combination with systemd. Note: +this option was introduced with version 5.9.1. Due to the usefulness of it, we +decided to enable it by default. As such, 5.9.1 and above behave slightly different +than previous versions. However, we do not see how this could negatively affect +existing environments.<br> <li><b>$SystemLogSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]<br> Ignore timestamps included in the messages, applies to messages received via the system log socket.</li> -<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] -- former -o option</li> +<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] -- former -o option; +do NOT listen for the local log socket. This is most useful if you run multiple +instances of rsyslogd where only one shall handle the system log socket.</li> <li><b>$SystemLogSocketName</b> <name-of-socket> -- former -p option</li> <li><b>$SystemLogFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied to the system log socket.</li> @@ -87,6 +113,7 @@ burst in number of messages. Default is 200. <li><b>$SystemLogRateLimitSeverity</b> [numerical severity] - specifies the severity of messages that shall be rate-limited. </li> +<li><b>$SystemLogUseSysTimeStamp</b> [<b>on</b>/off] the same as $InputUnixListenSocketUseSysTimeStamp, but for the system log socket. <li><b>$InputUnixListenSocketCreatePath</b> [on/<b>off</b>] - create directories in the socket path if they do not already exist. They are created with 0755 permissions with the owner being the process under which rsyslogd runs. The default is not to create directories. Keep in mind, though, that rsyslogd always @@ -105,7 +132,12 @@ shall be used inside messages taken from the <b>next</b> $AddUnixListenSocket so the hostname must be specified before the $AddUnixListenSocket configuration directive, and it will only affect the next one and then automatically be reset. This functionality is provided so that the local hostname can be overridden in cases where that is desired.</li> +<li><b>$InputUnixListenSocketAnnotate</b> <on/<b>off</b>> turn on annotation/trusted +properties for the non-system log socket in question.</li> +<li><b>$SystemLogSocketAnnotate</b> <on/<b>off</b>> turn on annotation/trusted +properties for the system log socket.</li> </ul> + <b>Caveats/Known Bugs:</b><br> <ul> <li>There is a compile-time limit of 50 concurrent sockets. If you need more, you need to @@ -141,16 +173,22 @@ $InputUnixListenSocketHostName /var/run/sshd/dev/log </textarea> <p>The following sample is used to turn off input rate limiting on the system log socket. -<textarea rows="6" cols="70">$ModLoad imuxsock # needs to be done just once +<textarea rows="4" cols="70">$ModLoad imuxsock # needs to be done just once $SystemLogRateLimitInterval 0 # turn off rate limiting </textarea> +<p>The following sample is used activate message annotation and thus trusted properties +on the system log socket. +<textarea rows="4" cols="70">$ModLoad imuxsock # needs to be done just once + +$SystemLogSocketAnnotate on +</textarea> <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 <a href="http://www.rsyslog.com/">rsyslog</a> project.<br> -Copyright © 2008-2010 by <a href="http://www.gerhards.net/rainer">Rainer +Copyright © 2008-2012 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/manual.html b/doc/manual.html index f2386314..de05d7ae 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -19,7 +19,7 @@ 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 6.2.2 (v6-stable branch) of rsyslog.</b> +<p><b>This documentation is for version 6.4.0 (stable branch) of rsyslog.</b> Visit the <i><a href="http://www.rsyslog.com/status">rsyslog status page</a></i></b> to obtain current version information and project status. </p><p><b>If you like rsyslog, you might @@ -30,15 +30,17 @@ 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 notes</a>, and if you are upgrading from v3, read the -<a href="v4compatibility.html">rsyslog v4 compatibility notes</a> and +<a href="v4compatibility.html">rsyslog v4 compatibility notes</a>, if you upgrade from v4, read the -<a href="v5compatibility.html">rsyslog v5 compatibility notes</a>. Ther currently is -no compatibility mode document for v6, as none is required right now. +<a href="v5compatibility.html">rsyslog v5 compatibility notes</a>, and +if you upgrade from v5, read the +<a href="v6compatibility.html">rsyslog v6 compatibility notes</a>. <p>Rsyslog will work even if you do not read the doc, but doing so will definitely improve your experience.</p> <p><b>Follow the links below for the</b></p> <ul> <li><a href="troubleshoot.html">troubleshooting rsyslog problems</a></li> +<li><a href="http://www.rsyslog.com/doc/node1.html">rsyslog.conf, new RainerScript-based format (v6+)</a></li> <li><a href="rsyslog_conf.html">configuration file format (rsyslog.conf)</a></li> <li><a href="http://www.rsyslog.com/tool-regex">a regular expression checker/generator tool for rsyslog</a></li> <li> <a href="property_replacer.html">property replacer, an important core component</a></li> @@ -47,8 +49,9 @@ if you do not read the doc, but doing so will definitely improve your experience <li><a href="generic_design.html">backgrounder on generic syslog application design</a></li> <li><a href="modules.html">description of rsyslog modules</a></li> <li><a href="rsyslog_packages.html">rsyslog packages</a></li> -<li><a href="http://cookbook.rsyslog.com">the rsyslog "cookbook"</a> - a set of configurations ready to use</li> </ul> +<p><b>To keep current on rsyslog development, follow +<a href="http://twitter.com/rgerhards">Rainer's twitter feed</a>.</b></p> <p><b>We have some in-depth papers on</b></p> <ul> <li><a href="install.html">installing rsyslog</a></li> @@ -104,14 +107,16 @@ online documentation (most current version only)</a></li> mailing list</a>. If you are interested in the "backstage", you may find <a href="http://www.gerhards.net/rainer">Rainer</a>'s -<a href="http://rgerhards.blogspot.com/">blog</a> an +<a href="http://blog.gerhards.net/">blog</a> an interesting read (filter on syslog and rsyslog tags). +Or meet <a href="http://www.facebook.com/people/Rainer-Gerhards/1349393098">Rainer Gerhards at Facebook</a> +or <a href="https://plus.google.com/112402185904751517878/posts">Google+</a>. If you would like to use rsyslog source code inside your open source project, you can do that without any restriction as long as your license is GPLv3 compatible. If your license is incompatible to GPLv3, you may even be still permitted to use rsyslog source code. However, then you need to look at the way <a href="licensing.html">rsyslog is licensed</a>.</p> <p>Feedback is always welcome, but if you have a support question, please do not mail Rainer directly (<a href="free_support.html">why not?</a>) - use the -<a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslogmailing list</a> +<a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a> or <a href="http://kb.monitorware.com/rsyslog-f40.html">rsyslog formum</a> instead. </body></html> diff --git a/doc/mmsnmptrapd.html b/doc/mmsnmptrapd.html index e69bc241..699049d3 100644 --- a/doc/mmsnmptrapd.html +++ b/doc/mmsnmptrapd.html @@ -51,8 +51,11 @@ to control output modules are also available to mmsnmptrapd. <ul> <li><b>$mmsnmptrapdTag</b> [tagname]<br> tells the module which start string inside the tag to look for. The default is -"snmptrap/" -<li><b>$mmsnmptrapdSevertiyMapping</b> [severtiymap]<br> +"snmptrapd". Note that a slash is automatically added to this tag when it comes to +matching incoming messages. It MUST not be given, except if two slashes are required +for whatever reasons (so "tag/" results in a check for "tag//" at the start of +the tag field). +<li><b>$mmsnmptrapdSeverityMapping</b> [severtiymap]<br> This specifies the severity mapping table. It needs to be specified as a list. Note that due to the current config system <b>no whitespace</b> is supported inside the list, so be sure not to use any whitespace inside it.<br> @@ -76,7 +79,7 @@ severities. The default tag is used.<br> # ... other module loads and listener setup ... *.* /path/to/file/with/orignalMessage # this file receives *un*modified messages $mmsnmptrapdSeverityMapping warning/4,error/3 -*.* ::mmsnmptrapd: # *now* message is modified +*.* :mmsnmptrapd: # *now* message is modified *.* /path/to/file/with/modifiedMessage # this file receives modified messages # ... rest of config ... </textarea> diff --git a/doc/omlibdbi.html b/doc/omlibdbi.html index ec1d01b6..008dcb81 100644 --- a/doc/omlibdbi.html +++ b/doc/omlibdbi.html @@ -54,32 +54,38 @@ dlopen()ed plugin (as omlibdbi is). So in short, you probably save you a lot of headache if you make sure you have at least libdbi version 0.8.3 on your system. </p> -<p><b>Configuration Directives</b>:</p> +<p><b>Action Parameters</b>:</p> <ul> -<li><span style="font-weight: bold;">$ActionLibdbiDriverDirectory /path/to/dbd/drivers</span><br>This -is a global setting. It points libdbi to its driver directory. Usually, -you do not need to set it. If you installed libdbi-driver's at a -non-standard location, you may need to specify the directory here. If -you are unsure, do <span style="font-weight: bold;">not</span> use this configuration directive. Usually, everything works just fine.<strong></strong></li><li><strong>$ActionLibdbiDriver drivername</strong><br> +<li><b>server</b><br>Name or address of the MySQL server +<li><b>db</b><br>Database to use +<li><b>uid</b><br>logon userid used to connect to server. Must have proper permissions. +<li><b>pwd</b><br>the user's password +<li><b>template</b><br>Template to use when submitting messages. +<li><b>driver</b><br> Name of the dbidriver to use, see libdbi-drivers documentation. As a quick excerpt, at least those were available at the time of this writiting "mysql" (suggest to use ommysql instead), "firebird" (Firbird and InterBase), "ingres", "msql", "Oracle", "sqlite", "sqlite3", "freetds" (for Microsoft SQL and Sybase) and "pgsql" (suggest to use ompgsql instead).</li> -<li><span style="font-weight: bold;">$ActionLibdbiHost -hostname</span><br> +<li><b>driverdirectory</b><br> +Path to the libdbi drivers. Usually, +you do not need to set it. If you installed libdbi-drivers at a +non-standard location, you may need to specify the directory here. If +you are unsure, do <b>not</b> use this configuration directive. +Usually, everything works just fine.</li> +</ul> +<p><b>Legacy (pre-v6) Configuration Directives</b>:</p> +<ul> +<li><b>$ActionLibdbiDriverDirectory /path/to/dbd/drivers</b> +- like the driverdirectory action parameter. +<li><strong>$ActionLibdbiDriver drivername</strong><br> - like the drivername action parameter. +<li><span style="font-weight: bold;">$ActionLibdbiHost hostname</span> - like the server action parameter The host to connect to.</li> -<li><span style="font-weight: bold;">$ActionLibdbiUserName -user</span><br> -The user used to connect to the database.</li> -<li><span style="font-weight: bold;">$ActionlibdbiPassword</span><br> -That user's password.</li> -<li><span style="font-weight: bold;">$ActionlibdbiDBName -db</span><br> -The database that shall be written to.</li> -<li><span style="font-weight: bold;">selector -line: :omlibdbi:<span style="font-style: italic;">;template</span></span><br> +<li><b>$ActionLibdbiUserName user</b> - like the uid action parameter +<li><b>$ActionlibdbiPassword</b> - like the pwd action parameter +<li><b>$ActionlibdbiDBName db</b> - like the db action parameter +<li><b>selector line: :omlibdbi:<i>;template</i></b><br> executes the recently configured omlibdbi action. The ;template part is optional. If no template is provided, a default template is used (which is currently optimized for MySQL - sorry, folks...)</li> @@ -108,7 +114,14 @@ database "syslog_db" on mysqlsever.example.com. The server is MySQL and being accessed under the account of "user" with password "pwd" (if you have empty passwords, just remove the $ActionLibdbiPassword line).<br> </p> -<textarea rows="15" cols="60">$ModLoad omlibdbi +<textarea rows="5" cols="60">$ModLoad omlibdbi +*.* action(type="omlibdbi" driver="mysql" + server="mysqlserver.example.com" db="syslog_db" + uid="user" pwd="pwd" +</textarea> +<p><b>Sample:</b></p> +<p>The same as above, but in legacy config format (pre rsyslog-v6): +<textarea rows="10" cols="60">$ModLoad omlibdbi $ActionLibdbiDriver mysql $ActionLibdbiHost mysqlserver.example.com $ActionLibdbiUserName user @@ -121,8 +134,7 @@ $ActionLibdbiDBName syslog_db <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 -Gerhards</a> and +Copyright © 2008-2012 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> +Released under the ASL 2.0.</font></p> </body></html> diff --git a/doc/ommysql.html b/doc/ommysql.html index daef9cab..7769fb86 100644 --- a/doc/ommysql.html +++ b/doc/ommysql.html @@ -15,28 +15,37 @@ <p>This module provides native support for logging to MySQL databases. It offers superior performance over the more generic <a href="omlibdbi.html">omlibdbi</a> module. </p> -<p><b>Configuration Directives</b>:</p> -<p>ommysql mostly uses the "old style" configuration, with almost everything on the -action line itself. A few newer features are being migrated to the new style-config -directive configuration system. +<p><b>Action Parameters</b>:</p> <ul> -<li><b>$ActionOmmysqlServerPort <port></b><br>Permits to select +<li><b>server</b><br>Name or address of the MySQL server +<li><b>serverport</b><br>Permits to select a non-standard port for the MySQL server. The default is 0, which means the -system default port is used. There is no need to specify this directive unless +system default port is used. There is no need to specify this parameter unless you know the server is running on a non-standard listen port. -<li><b>$OmMySQLConfigFile <file name></b><br>Permits the selection +<li><b>db</b><br>Database to use +<li><b>uid</b><br>logon userid used to connect to server. Must have proper permissions. +<li><b>pwd</b><br>the user's password +<li><b>template</b><br>Template to use when submitting messages. +<li><b>mysqlconfig.file</b><br>Permits the selection of an optional MySQL Client Library configuration file (my.cnf) for extended configuration functionality. The use of this configuration directive is necessary only if you have a non-standard environment or if fine-grained control over the database connection is desired.</li> -<li><b>$OmMySQLConfigSection <string></b><br>Permits the selection of the -section within the configuration file specified by the <b>$OmMySQLConfigFile</b> directive. +<li><b>mysqlconfig.section</b><br>Permits the selection of the +section within the configuration file specified by the <b>myselconfig.file</b> parameter. <br>This will likely only be used where the database administrator provides a single configuration file with multiple profiles. -<br>This configuration directive is ignored unless <b>$OmMySQLConfigFile</b> is also used -in the rsyslog configration file. +<br>This configuration parameter is ignored unless <b>mysqlconfig.file</b> is also used. <br>If omitted, the MySQL Client Library default of "client" will be used.</li> -<li>Action parameters: +</ul> +<p><b>Legacy (pre-v6) Configuration Directives</b>:</p> +<p>ommysql mostly uses the "very old style" (v0) configuration, with almost everything on the +action line itself. +<ul> +<li><b>$ActionOmmysqlServerPort <port></b> - like the "serverport" action parameter. +<li><b>$OmMySQLConfigFile <file name></b> - like the "mysqlconfig.file" action parameter. +<li><b>$OmMySQLConfigSection <string></b> - like the "mysqlconfig.file" action parameter. +<li>Action line: <br><b>:ommysql:database-server,database-name,database-userid,database-password</b> <br>All parameters should be filled in for a successful connect. </ul> @@ -57,15 +66,20 @@ database "syslog_db" on mysqlsever.example.com. The server is being accessed under the account of "user" with password "pwd". </p> <textarea rows="5" cols="80">$ModLoad ommysql +*.* action(type="ommysql" server="mysqlserver.example.com" serverport="1234" + db="syslog_db" uid="user" pwd="pwd") +</textarea> +<p><b>Legacy Sample:</b></p> +<p>The same as above, but in legacy config format (pre rsyslog-v6): +<textarea rows="5" cols="80">$ModLoad ommysql $ActionOmmysqlServerPort 1234 # use non-standard port *.* :ommysql:mysqlserver.example.com,syslog_db,user,pwd </textarea> <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 -<a href="http://www.rsyslog.com/">rsyslog</a> -project.<br> -Copyright © 2008, 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and +<a href="http://www.rsyslog.com/">rsyslog</a> project.<br> +Copyright © 2008-2012 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> +Released under the ASL 2.0.</font></p> </body></html> diff --git a/doc/pmlastmsg.html b/doc/pmlastmsg.html index 2abeac6a..fd26dbd5 100644 --- a/doc/pmlastmsg.html +++ b/doc/pmlastmsg.html @@ -27,6 +27,13 @@ parser chain</a>. It processes all those messages that contain a PRI, then none some spaces and then the exact text (case-insensitive) "last message repeated n times" where n must be an integer. All other messages are left untouched. +<p><b>Please note:</b> this parser module makes it possible that these messages +are properly detected. It does <b>not</b> drop them. If you intend to drop those +messages, you need to use the usual filter logic in combination with the discard +action. As a side-note, please keep on your mind that the sender discarded messages +when the "last message repeated n times" message is emited. You want to consider if +that really is what you intend to happen. If not, go change the sender. + <p><b>Configuration Directives</b>:</p> <p>There do not currently exist any configuration directives for this module. <p><b>Examples:</b></p> diff --git a/doc/property_replacer.html b/doc/property_replacer.html index f4c4238e..4c92bf4c 100644 --- a/doc/property_replacer.html +++ b/doc/property_replacer.html @@ -13,7 +13,7 @@ the value, e.g. by converting all characters to lower case.</p> <p>Syslog message properties are used inside templates. They are accessed by putting them between percent signs. Properties can be modified by the property replacer. The full syntax is as follows:</p> -<blockquote><b><code>%propname:fromChar:toChar:options%</code></b></blockquote> +<blockquote><b><code>%propname:fromChar:toChar:options:fieldname%</code></b></blockquote> <h2>Available Properties</h2> <p><b><code>propname</code></b> is the name of the property to access. It is case-insensitive (prior to 3.17.0, they were case-senstive). @@ -138,6 +138,25 @@ draft-ietf-syslog-protocol</td> <td>The contents of the MSGID field from IETF draft draft-ietf-syslog-protocol</td> </tr> +<tr> +<td><b>parsesuccess</b></td> +<td>This returns the status of the <b>last</b> called higher level parser, +like mmjsonparse. A higher level parser parses the actual message for additional +structured data and maintains an extra property table while doing so (this is +often referred to as "cee data" because the idea was originally rooted in the +cee effort, only (but has been extended since then). Note that higher level +parsers must explicitely support (and set) this property. So, depending on the +parser, it may not be set correctly. +<br>If the parser properly supports it, the value "OK" means that parsing was +successfull, while "FAIL" means the parser could not successfully obtain any data. +Failure state is not necessarily an error. For example, it may simple indicate +that the cee-enhanced syslog parser (mmjsonparse) did not detect cee-enhanced format, +what can be totally valid. Using this property, further processing of the message +can be directed based on this parsing outcome. If no parser has been called at the +time this property is accessed, it will contain "FAIL". +<br><b>This property is available since version 6.3.8.</b> +</td> +</tr> <td><b>inputname</b></td> <td>The name of the input module that generated the message (e.g. "imuxsock", "imudp"). Note that not all modules @@ -285,6 +304,15 @@ fields in the property is requested. The field number must be placed in the "ToChar" parameter. An example where the 3rd field (delimited by TAB) from the msg property is extracted is as follows: "%msg:F:3%". The same example with semicolon as delimiter is "%msg:F,59:3%".</p> +<p>The use of fields does not permit to select substrings, what is rather +unfortunate. To solve this issue, starting with 6.3.9, fromPos and toPos +can be specified for strings as well. However, the syntax is quite ugly, but +it was the only way to integrate this functonality into the already-existing +system. To do so, use ",fromPos" and ",toPos" during field extraction. +Let's assume you want to extract the substring from position 5 to 9 in the previous +example. Then, the syntax is as follows: "%msg:F,59,5:3,9%". As you can see, +"F,59" means field-mode, with semicolon delimiter and ",5" means starting +at position 5. Then "3,9" means field 3 and string extraction to position 9. <p>Please note that the special characters "F" and "R" are case-sensitive. Only upper case works, lower case will return an error. There are no white spaces permitted inside the sequence (that will lead @@ -327,6 +355,29 @@ case-insensitive. Currently, the following options are defined: <td>convert property text to uppercase only</td> </tr> <tr> +<td><b>json</b></td> +<td>encode the value so that it can be used inside a JSON field. This means +that several characters (according to the JSON spec) are being escaped, for +example US-ASCII LF is replaced by "\n". +The json option cannot be used together with either jsonf or csv options. +</td> +</tr> +<tr> +<td><b>jsonf</b></td> +<td><i>(available in 6.3.9+)</i> +This signifies that the property should be expressed as a json <b>f</b>ield. +That means not only the property is written, but rather a complete json field in +the format<br> +"fieldname"="value"</b> +where "filedname" is the assigend field name (or the property name if none was assigned) +and value is the end result of property replacer operation. Note that value supports +all property replacer options, like substrings, case converson and the like. +Values are properly json-escaped. However, field names are (currently) not. It is +expected that proper field names are configured. +The jsonf option cannot be used together with either json or csv options. +</td> +</tr> +<tr> <td valign="top"><b>csv</b></td> <td>formats the resulting field (after all modifications) in CSV format as specified in <a href="http://www.ietf.org/rfc/rfc4180.txt">RFC 4180</a>. @@ -335,6 +386,7 @@ text, you need to define a proper template. An example is this one: <br>$template csvline,"%syslogtag:::csv%,%msg:::csv%" <br>Most importantly, you need to provide the commas between the fields inside the template. +The csv option cannot be used together with either json or jsonf options. <br><i>This feature was introduced in rsyslog 4.1.6.</i> </td> </tr> @@ -369,6 +421,10 @@ option when forwarding to remote hosts - they may treat the date as invalid <td>format as RFC 3339 date</td> </tr> <tr> +<td><b>date-unixtimestamp</b></td> +<td>format as unix timestamp (seconds since epoch)</td> +</tr> +<tr> <td><b>date-subseconds</b></td> <td>just the subseconds of a timestamp (always 0 for a low precision timestamp)</td> </tr> @@ -436,13 +492,19 @@ Useful for secure pathname generation (with dynafiles). them. For example "escape-cc,sp-if-no-1st-sp". If you use conflicting options together, the last one will override the previous one. For example, using "escape-cc,drop-cc" will use drop-cc and "drop-cc,escape-cc" will use escape-cc mode. +<h2>Fieldname</h2> +<p><i>(available in 6.3.9+)</i> +<p>This field permits to specify a field name for structured-data emitting property replacer +options. It was initially introduced to support the "jsonf" option, for which it provides +the capability to set an alternative field name. If it is not specified, it defaults to +the property name. <h2>Further Links</h2> <ul> <li>Article on "<a href="rsyslog_recording_pri.html">Recording the Priority of Syslog Messages</a>" (describes use of templates to record severity and facility of a message)</li> <li><a href="rsyslog_conf.html">Configuration file -syntax</a>, this is where you actually use the property replacer.</li> +format</a>, this is where you actually use the property replacer.</li> </ul> <p>[<a href="manual.html">manual index</a>] [<a href="rsyslog_conf.html">rsyslog.conf</a>] diff --git a/doc/rsconf1_omfileforcechown.html b/doc/rsconf1_omfileforcechown.html index 7415a6f6..a680810b 100644 --- a/doc/rsconf1_omfileforcechown.html +++ b/doc/rsconf1_omfileforcechown.html @@ -8,7 +8,10 @@ <h2>$omfileForceChown</h2> <p><b>Type:</b> global configuration directive</p> <p><b>Parameter Values:</b> boolean (on/off, yes/no)</p> -<p><b>Available since:</b> 4.7.0+, 5.3.0+</p> +<p><b>Available:</b> 4.7.0+, 5.3.0-5.8.x, <b>NOT</b> available in 5.9.x or higher</p> +<p><b>Note: this directive has been removed and is no longer available. The +documentation is currently being retained for historical reaons.</b> Expect +it to go away at some later stage as well. <p><b>Default:</b> off</p> <p><b>Description:</b></p> <p>Forces rsyslogd to change the ownership for output files that already exist. Please note diff --git a/doc/rsyslog_conf_global.html b/doc/rsyslog_conf_global.html index 83eb876b..6c20f4c2 100644 --- a/doc/rsyslog_conf_global.html +++ b/doc/rsyslog_conf_global.html @@ -143,6 +143,7 @@ our paper on <a href="multi_ruleset.html">using multiple rule sets in rsyslog</a <li><a href="rsconf1_escape8bitcharsonreceive.html">$Escape8BitCharactersOnReceive</a></li> <li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li> <li><b>$EscapeControlCharactersOnReceive</b> [<b>on</b>|off] - escape USASCII HT character</li> +<li>$SpaceLFOnReceive [on/<b>off</b>] - instructs rsyslogd to replace LF with spaces during message reception (sysklogd compatibility aid)</li> <li>$ErrorMessagesToStderr [<b>on</b>|off] - direct rsyslogd error message to stderr (in addition to other targets)</li> <li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li> <li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li> @@ -292,9 +293,22 @@ the value, the less precise the timestamp. <li><b>$Sleep</b> <seconds> - puts the rsyslog main thread to sleep for the specified number of seconds immediately when the directive is encountered. You should have a good reason for using this directive!</li> +<li><b>$LocalHostIPIF</b> <interface name> - (available since 5.9.6) - if provided, the IP of the specified +interface (e.g. "eth0") shall be used as fromhost-ip for locall-originating messages. +If this directive is not given OR the interface cannot be found (or has no IP address), +the default of "127.0.0.1" is used. Note that this directive can be given only +once. Trying to reset will result in an error message and the new value will +be ignored. Please note that modules must have support for obtaining the local +IP address set via this directive. While this is the case for rsyslog-provided +modules, it may not always be the case for contributed plugins. +<br><b>Important:</b> This directive shall be placed <b>right at the top of +rsyslog.conf</b>. Otherwise, if error messages are triggered before this directive +is processed, rsyslog will fix the local host IP to "127.0.0.1", what than can +not be reset. +</li> <li><a href="rsconf1_umask.html">$UMASK</a></li> </ul> -<p><b>Where <size_nbr> is specified above,</b> +<p><b>Where <size_nbr> or integers are specified above,</b> modifiers can be used after the number part. For example, 1k means 1024. Supported are k(ilo), m(ega), g(iga), t(era), p(eta) and e(xa). Lower case letters refer to the traditional binary defintion (e.g. 1m @@ -302,7 +316,7 @@ equals 1,048,576) whereas upper case letters refer to their new 1000-based definition (e.g 1M equals 1,000,000).</p> <p>Numbers may include '.' and ',' for readability. So you can for example specify either "1000" or "1,000" with the same result. -Please note that rsyslogd simply ignores the punctuation. Form it's +Please note that rsyslogd simply ignores the punctuation. From it's point of view, "1,,0.0.,.,0" also has the value 1000. </p> <p>[<a href="manual.html">manual index</a>] diff --git a/doc/rsyslog_conf_templates.html b/doc/rsyslog_conf_templates.html index 23a02049..bd0b3253 100644 --- a/doc/rsyslog_conf_templates.html +++ b/doc/rsyslog_conf_templates.html @@ -146,6 +146,10 @@ with high-precision timestamps and timezone information</li> useful if you send messages to other syslogd's or rsyslogd below version 3.12.5.</li> +<li><span style="font-weight: bold;">RSYSLOG_SysklogdFileFormat</span> +- sysklogd compatible log file format. If used with options: $SpaceLFOnReceive on; +$EscapeControlCharactersOnReceive off; $DropTrailingLFOnReception off, +the log format will conform to sysklogd log format.</li> <li><span style="font-weight: bold;">RSYSLOG_ForwardFormat</span> - a new high-precision forwarding format very similar to the traditional one, but with high-precision timestamps and timezone diff --git a/doc/rsyslog_ng_comparison.html b/doc/rsyslog_ng_comparison.html index 7d12a4a7..44c895f7 100644 --- a/doc/rsyslog_ng_comparison.html +++ b/doc/rsyslog_ng_comparison.html @@ -4,24 +4,45 @@ <a href="features.html">back</a> <h1>rsyslog vs. syslog-ng</h1> <p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> -(2008-05-06)</i></small></p> -<p><i>Warning</i>: this comparison is a little outdated, take it with a grain -of salt and be sure to check the links at the bottom (both syslog-ng as well as -rsyslog features are missing, but our priority is on creating great software not -continously updating this comparison ;)). -<p>We have often been asked about a comparison sheet between -rsyslog and syslog-ng. Unfortunately, I do not know much about -syslog-ng, I did not even use it once. Also, there seems to be no -comprehensive feature sheet available for syslog-ng (that recently -changed, see below). So I started this -comparison, but it probably is not complete. For sure, I miss some -syslog-ng features. This is not an attempt to let rsyslog shine more -than it should. I just used the <a href="features.html">rsyslog -feature sheet</a> as a starting point, simply because it was -available. If you would like to add anything to the chart, or correct -it, please simply <a href="mailto:rgerhards@adiscon.com">drop -me a line</a>. I would love to see a real honest and up-to-date -comparison sheet, so please don't be shy ;)</p> +(2008-05-06), slightly updated 2012-01-09</i></small></p> +<p><b>This comparison page is rooted nearly 5 years in the past and has become severely +outdated since then.</b> It was unmaintained for several years and contained false +information on both syslog-ng and rsyslog as technology had advanced so much. +<p>This page was initially written because so many people asked about a comparison when +rsyslog was in its infancy. So I tried to create one, but it was hard to maintain as both +projects grew and added feature after feature. I have to admit we did not try hard to keep +it current -- there were many other priorities. I even had forgetten about this page, when I +saw that Peter Czanik blogged about its +<a href="http://blogs.balabit.com/2012/01/05/rsyslog-vs-syslog-ng/">incorrectness</a> (it must be noted +that Peter is wrong on RELP -- it is well alive). I now remember +that he asked me some time ago about this page, what I somehow lost... I guess he must have been +rather grumpy about that :-( +<p>Visiting this page after so many years is interesting, because it shows how much has changed since then. +Obviously, one of my main goals in regard to syslog-ng is reached: in 2007, I blogged that +<a href="http://blog.gerhards.net/2007/08/why-does-world-need-another-syslogd.html">the +world needs another syslogd</a> in order to have healthy competition and a greate feature +set in the free editions. In my opinion, the timeline clearly tells that rsyslog's competition +has driven more syslog-ng features from the commercial to the free edition. Also, I found +it interesting to see that syslog-ng has adapted rsyslog's licensing scheme, modular design and +multi-threadedness. On the other hand, the Balabit folks have obviously done a quicker and +better move on log normalization with what they call patterndb (it is very roughly equivalent +to what rsyslog has just recently introduced with the help of liblognorm). + +<p>To that account, I think the projects are closer together than 5 years ago. I should now +go ahead and create a new feature comparison. Given previous experience, I think this does not +work out. In the future, we will probably focus on some top features, as Balabit does. However, +that requires some time and I have to admit I do not like to drop this page that has a lot of +inbound links. So I think I do the useful thing by providing these notes and removing the +syslog-ng information. So it can't be wrong on syslog-ng any more. Note that it still contains +some incorrect information about rsyslog (it's the state it had 5 years ago!). The core idea is +to start with updating the <a href="features.html">rsyslog feature sheet</a> and from there +on work to a complete comparision. Of course, feel free to read on if you like to get some sense +of history (and inspiration on what you can still do -- but more ;)). +<br><br> +Thanks,<br> +Rainer Gerhards +<p> + <table border="1"> <tbody> <tr> @@ -37,50 +58,50 @@ comparison sheet, so please don't be shy ;)</p> <tr> <td valign="top">UNIX domain socket</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">UDP</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">TCP</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top"><a href="http://www.librelp.com">RELP</a></td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">RFC 3195/BEEP</td> <td valign="top">yes (via <a href="im3195.html">im3195</a>)</td> -<td valign="top">no</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">kernel log</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">file</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">mark message generator as an optional input</td> <td valign="top">yes</td> -<td valign="top">no (?)</td> +<td valign="top"></td> <td></td> </tr> <tr> @@ -89,8 +110,7 @@ optional input</td> <a href="http://www.eventreporter.com">EventReporter</a> or <a href="http://www.mwagent.com">MonitorWare Agent</a> (both commercial software, both fund rsyslog development)</td> -<td valign="top">via separate Windows agent, paid -edition only</td> +<td valign="top"></td> </tr> <tr> <td colspan="3" valign="top"><b><br> @@ -100,83 +120,82 @@ Network (Protocol) Support</b><br> <tr> <td valign="top">support for (plain) tcp based syslog</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for GSS-API</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to limit the allowed network senders (syslog ACLs)</td> <td valign="top">yes</td> -<td valign="top">yes (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for syslog-transport-tls based framing on syslog/tcp connections</td> <td valign="top">yes</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">udp syslog</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">syslog over RELP<br> truly reliable message delivery (<a href="http://blog.gerhards.net/2008/05/why-you-cant-build-reliable-tcp.html">Why is plain tcp syslog not reliable?</a>)</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">on the wire (zlib) message compression</td> <td valign="top">yes</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for receiving messages via reliable <a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC 3195</a> delivery</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for <a href="rsyslog_tls.html">TLS/SSL-protected syslog</a> </td> <td valign="top"><a href="rsyslog_tls.html">natively</a> (since 3.19.0)<br><a href="rsyslog_stunnel.html">via stunnel</a></td> -<td valign="top">via stunnel<br> -paid edition natively</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for IETF's new syslog-protocol draft</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for IETF's new syslog-transport-tls draft</td> <td valign="top">yes<br>(since 3.19.0 - world's first implementation)</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for IPv6</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">native ability to send SNMP traps</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to preserve the original hostname in NAT environments and relay chains</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td colspan="3" valign="top"><br> @@ -187,81 +206,81 @@ hostname in NAT environments and relay chains</td> <td valign="top">Filtering for syslog facility and priority</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">Filtering for hostname</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">Filtering for application</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">Filtering for message contents</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">Filtering for sending IP address</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">ability to filter on any other message field not mentioned above (including substrings and the like)</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td>support for complex filters, using full boolean algebra with and/or/not operators and parenthesis</td> <td>yes</td> -<td>yes</td> +<td></td> </tr> <tr> <td>Support for reusable filters: specify a filter once and use it in multiple selector lines</td> <td>no</td> -<td>yes</td> +<td></td> </tr> <tr> <td>support for arbritrary complex arithmetic and string expressions inside filters</td> <td>yes</td> -<td>no</td> +<td></td> </tr> <tr> <td valign="top">ability to use regular expressions in filters</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for discarding messages based on filters</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">ability to filter out messages based on sequence of appearing</td> <td valign="top">yes (starting with 3.21.3)</td> -<td valign="top">no</td> +<td valign="top"></td> <td></td> </tr> <tr> <td valign="top">powerful BSD-style hostname and program name blocks for easy multi-host support</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td></td> @@ -277,47 +296,47 @@ program name blocks for easy multi-host support</td> <td valign="top">MySQL</td> <td valign="top"><a href="rsyslog_mysql.html">yes</a> (native ommysql, <a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">yes (via libdibi)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">PostgreSQL</td> <td valign="top">yes (native ompgsql, <a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">yes (via libdibi)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">Oracle</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">yes (via libdibi)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">SQLite</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">yes (via libdibi)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">Microsoft SQL (Open TDS)</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">Sybase (Open TDS)</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">Firebird/Interbase</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">Ingres</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">mSQL</td> <td valign="top">yes (<a href="omlibdbi.html">omlibdbi</a>)</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td colspan="3" valign="top"><br> @@ -328,26 +347,26 @@ program name blocks for easy multi-host support</td> <td valign="top">support for on-demand on-disk spooling of messages</td> <td valign="top">yes</td> -<td valign="top">paid edition only</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to limit disk space used by spool files</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">each action can use its own, independant set of spool files</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">different sets of spool files can be placed on different disk</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to process spooled @@ -356,18 +375,18 @@ during off-peak hours, during peak hours they are enqueued only)</td> <td valign="top"><a href="http://wiki.rsyslog.com/index.php/OffPeakHours">yes</a><br> (can independently be configured for the main queue and each action queue)</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to configure backup syslog/database servers </td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td>Professional Support</td> <td><a href="professional_support.html">yes</a></td> -<td>yes</td> +<td></td> </tr> <tr> <td colspan="3" valign="top"><br> @@ -378,20 +397,20 @@ syslog/database servers </td> <td valign="top">config file format</td> <td valign="top">compatible to legacy syslogd but ugly</td> -<td valign="top">clean but not backwards compatible</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to include config file from within other config files</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td height="25" valign="top">ability to include all config files existing in a specific directory</td> <td height="25" valign="top">yes</td> -<td height="25" valign="top">no</td> +<td height="25" valign="top"></td> </tr> <tr> <td colspan="3" valign="top"><br> @@ -403,13 +422,13 @@ existing in a specific directory</td> loadable modules</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td valign="top">Support for third-party input plugins</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> </tr> @@ -417,7 +436,7 @@ plugins</td> <td valign="top">Support for third-party output plugins</td> <td valign="top">yes</td> -<td valign="top">no</td> +<td valign="top"></td> </tr> <tr> <td colspan="3" valign="top"><br> @@ -430,79 +449,78 @@ plugins</td> <td valign="top">ability to generate file names and directories (log targets) dynamically</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">control of log output format, including ability to present channel and priority as visible log data</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr><td valign="top">native ability to send mail messages</td> <td valign="top">yes (<a href="ommail.html">ommail</a>, introduced in 3.17.0)</td> -<td valign="top">no (only via piped external process)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">good timestamp format control; at a minimum, ISO 8601/RFC 3339 second-resolution UTC zone</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to reformat message contents and work with substrings</td> <td valign="top">yes</td> -<td valign="top">I think yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for log files larger than 2gb</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for log file size limitation and automatic rollover command execution</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">support for running multiple syslogd instances on a single machine</td> <td valign="top">yes</td> -<td valign="top">? (but I think yes)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to execute shell scripts on received messages</td> -<td valign="top">yes</td> +<td valign="top"></td> <td valign="top">yes</td> </tr> <tr> <td valign="top">ability to pipe messages to a continously running program</td> -<td valign="top">no</td> -<td valign="top">yes</td> +<td valign="top"></td> +<td valign="top"></td> </tr> <tr> <td valign="top">massively multi-threaded for tomorrow's multi-core machines</td> <td valign="top">yes</td> -<td valign="top">no (only multithreaded with -database destinations)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to control repeated line reduction ("last message repeated n times") on a per selector-line basis</td> <td valign="top">yes</td> -<td valign="top">yes (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">supports multiple actions per selector/filter condition</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> <td></td> </tr> <tr> @@ -510,24 +528,23 @@ selector/filter condition</td> <td valign="top"><a href="http://www.phplogcon.org">phpLogCon</a><br> [also works with <a href="http://freshmeat.net/projects/php-syslog-ng/"> php-syslog-ng</a>]</td> -<td valign="top"><a href="http://freshmeat.net/projects/php-syslog-ng/"> -php-syslog-ng</a></td> +<td valign="top"></td> </tr> <tr> <td valign="top">using text files as input source</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">rate-limiting output actions</td> <td valign="top">yes</td> -<td valign="top">yes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">discard low-priority messages under system stress</td> <td valign="top">yes</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td height="43" valign="top">flow control @@ -535,40 +552,39 @@ system stress</td> <td height="43" valign="top">yes (advanced, with multiple ways to slow down inputs depending on individual input capabilities, based on watermarks)</td> -<td height="43" valign="top">yes (limited? -"stops accepting messages")</td> +<td height="43" valign="top"></td> </tr> <tr> <td valign="top">rewriting messages</td> <td valign="top">yes</td> -<td valign="top">yes (at least I think so...)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">output data into various formats</td> <td valign="top">yes</td> -<td valign="top">yes (looks somewhat limited to me)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">ability to control "message repeated n times" generation</td> <td valign="top">yes</td> -<td valign="top">no (?)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">license</td> <td valign="top">GPLv3 (GPLv2 for v2 branch)</td> -<td valign="top">GPL (paid edition is closed source)</td> +<td valign="top"></td> </tr> <tr> <td valign="top">supported platforms</td> <td valign="top">Linux, BSD, anecdotical seen on Solaris; compilation and basic testing done on HP UX</td> -<td valign="top">many popular *nixes</td> +<td valign="top"></td> </tr> <tr> <td valign="top">DNS cache</td> -<td valign="top">no</td> -<td valign="top">yes</td> +<td valign="top"></td> +<td valign="top"></td> </tr> </tbody> </table> @@ -585,11 +601,6 @@ that vast experience and sometimes even on the code.</p> argument why it is good to have another strong syslogd besides syslog-ng</b>. You may want to read it at my blog at "<a href="http://rgerhards.blogspot.com/2007/08/why-does-world-need-another-syslogd.html">Why does the world need another syslogd?</a>".</p> -<p>Balabit, the vendor of syslog-ng, has just recently done a -feature sheet. I have not yet been able to fully work through it. In -the mean time, you may want to read it in parallel. It is available at -<a href="http://www.balabit.com/network-security/syslog-ng/features/detailed/">Balabit's -site</a>.</p> <p>[<a href="manual.html">manual index</a>] [<a href="rsyslog_conf.html">rsyslog.conf</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> diff --git a/doc/v6compatibility.html b/doc/v6compatibility.html index bc803d2a..1f830854 100644 --- a/doc/v6compatibility.html +++ b/doc/v6compatibility.html @@ -3,11 +3,14 @@ </head> <body> <h1>Compatibility Notes for rsyslog v6</h1> +<p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> +(2011-10-27)</i></small></p> <p> This document describes things to keep in mind when moving from v5 to v6. It does not list enhancements nor does it talk about compatibility concerns introduced -by earlier versions (for this, see their respective compatibility documents). -</p> +by earlier versions (for this, see their respective compatibility documents). Its focus +is primarily on what you need to know if you used a previous version and want to use the +current one without hassle. <p>Version 6 offers a better config language and some other improvements. As the config system has many ties into the rsyslog engine AND all plugins, the changes are somewhat intrusive. Note, however, that core processing has @@ -41,4 +44,128 @@ upgraded, so this compatibility issue is only of interest for you if you have custom plugins or use some user-contributed plugins from the rsyslog project that are not maintained by the project itself (omoracle is an example). Please expect some further plugin instablity during the initial v6 releases. +<h2>RainerScript based rsyslog.conf</h2> +<p>A better config format was the main release target for rsyslog v6. It comes in the +flavor of so-called RainerScript +(<a href="http://blog.gerhards.net/2008/02/introducing-rainerscript-and-some.html">why the +name RainerScript?</a>). RainerScript supports legacy syslog.conf format, much as you know it +from other syslogd's (like sysklogd or the BSD syslogd's) as well as previous versions +of rsyslog. Initial work on RainerScript began in v4, and the if-construct was already +supported in v4 and v5. Version 6 has now taken this further. After long discussions we +decided to use the legacy format as a basis, and lightly extend it by native RainerScript +constructs. The main goal was to make sure that previous knowledge and config systems +could still be used while offering a much more intuitive and powerful way of configuring +rsyslog. +<p>RainerScript has been implemented from scratch and with new tools (flex/bison, for those in the +know). Starting with 6.3.3, this new config file processor replaces the legacy one. Note that +the new processor handles all formats, extended RainerScript as well as legacy syslog.conf format. +There are some legacy construct that were especially hard to translate. You'll read about them in +other parts of this document (especially outchannels, which require a format change). + +<p>In v6, all legacy formats are supported. In the long term, we may remove some of the ugly +rsyslog-specific constructs. Good candidates are all configuration commands starting with +a dollar sign, like "$ActionFileDefaultTemplate"). However, this will not be the case before +rsyslog v7 or (much more likely) v8/9. Right now, you also need to use these commands, because +not all have already been converted to the new RainerScript format. + +<p>In 6.3.3, the new parser is used, but almost none of the extended RainerScript capabilities +are available. They will incrementally be introduced with the following releases. Note that for +some features (most importantly if-then-else nested blocks), the v6 core engine is not +capable enough. It is our aim to provide a much better config language to as many rsyslog +users as quickly as possible. As such, we refrain from doing big engine changes in v6. This +in turn means we cannot introduce some features into RainerScript that we really want to see. +These features will come up with rsyslog v7, which will have even better flow control +capabilities inside the core engine. Note that v7 will fully support v6 RainerScript. +Let us also say that the v6 version is not a low-end quick hack: it offers full-fledged +syslog message processing control, capable of doing the best you can find inside the +industry. We just say that v7 will come up with even more advanced capabilites. +<p>Please note that we tried hard to make the RainerScript parser compatible with +all legacy config files. However, we may have failed in one case or another. So if you +experience problems during config processing, chances are there may be a problem +on the rsyslog side. In that case, please let us know. + +<p>Please see the +<a href="http://blog.gerhards.net/2011/07/rsyslog-633-config-format-improvements.html">blog +post about rsyslog 6.3.3 config format</a> for details of what is currently supported. + +<h2>compatibility mode</h2> +<p>Compatibility mode (specified via -c option) has been removed. This was a migration aid from +sysklogd and very early versions of rsyslog. As all major distros now have rsyslog as their +default, and thus ship rsyslog-compliant config files, there is no longer a need for +compatibility mode. Removing it provides easier to maintain code. Also, practice has shown +that many users were confused by compatibility mode (and even some package maintainers got +it wrong). So this not only cleans up the code but rather removes a frequent source of +error. +<p>It must be noted, though, that this means rsyslog is no longer a 100% drop-in replacement +for sysklogd. If you convert an extremely old system, you need to checks its config and +probably need to apply some very mild changes to the config file. +<h2>abort on config errors</h2> +<p>Previous versions accepted some malformedness inside the config file without aborting. This +could lead to some uncertainty about which configuration was actually running. In v6 there +are some situations where config file errors can not be ignored. In these cases rsyslog +emits error messages to stderr, and then exists with a non-zero exit code. It is important +to check for those cases as this means log data is potentially lost. +Please note that +the root problem is the same for earlier versions as well. With them, it was just harder +to spot why things went wrong (and if at all). +<h2>Default Batch Sizes</h2> +<p>Due to their positive effect on performance and comparatively low overhead, +default batch sizes have been increased. Starting with 6.3.4, the action queues +have a default batch size of 128 messages. +<h2>outchannels</h2> +<p>Outchannels are a to-be-removed feature of rsyslog, at least as far as the config +syntax is concerned. Nevertheless, v6 still supports it, but a new syntax is required +for the action. Let's assume your outchannel is named "channel". The previous syntax was +<blockquote><code> +*.* $channel +</code> </blockquote> +This was deprecated in v5 and no longer works in v6. Instead, you need to specify +<blockquote><code> +*.* :omfile:$channel +</code></blockquote> +Note that this syntax is available starting with rsyslog v4. It is important to keep on your +mind that future versions of rsyslog will require different syntax and/or drop outchannel support +completely. So if at all possible, avoid using this feature. If you must use it, be prepared for +future changes and watch announcements very carefully. +<h2>omusrmsg</h2> +<p>The omusrmsg module is used to send messages to users. In legacy-legacy +config format (that is the very old sysklogd style), it was suffucient to use +just the user name to call this action, like in this example: +<blockquote><code> +*.* rgerhards +</code> </blockquote> +This format is very ambigious and causes headache (see +<a href="http://blog.gerhards.net/2011/07/why-omusrmsg-is-evil-and-how-it-is.html">blog post +on omusrmsg</a> for details). Thus the format has been superseded by this syntax +(which is legacy format ;-)): +<blockquote><code> +*.* :omusrmsg:rgerhards +</code> </blockquote> +That syntax is supported since later subversions of version 4. +<p>Rsyslog v6 still supports the legacy-legacy format, but in a very strict +sense. For example, if multiple users or templates are given, no spaces +must be included in the action line. For example, this works up to v5, but no +longer in v6: +<blockquote><code> +*.* rgerhards, bgerhards +</code> </blockquote> +To fix it in a way that is compatible with pre-v4, use (note the removed space!): +<blockquote><code> +*.* rgerhards,bgerhards +</code> </blockquote> +Of course, it probably is better to understand in native v6 format: +<blockquote><code> +*.* action(type="omusrmsg" users="rgerhards, bgerhards") +</code> </blockquote> +As you see, here you may include spaces between user names. +<p>In the long term, legacy-legacy format will most probably totally disappear, +so it is a wise decision to change config files at least to the legacy +format (with ":omusrmsg:" in front of the name). + +<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 © 2011 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 2 or higher.</font></p> </body></html> diff --git a/doc/version_naming.html b/doc/version_naming.html index 8c1b9187..3bfa19bb 100644 --- a/doc/version_naming.html +++ b/doc/version_naming.html @@ -105,7 +105,7 @@ versions. It applies to versions 1.0.0 and above. Versions below that are all unstable and have a different naming schema.</p> <p><b>Please note that version naming is currently being changed. There is a -<a href="http://rgerhards.blogspot.com/2007/08/on-rsyslog-versions.html">blog +<a href="http://blog.gerhards.net/2007/08/on-rsyslog-versions.html">blog post about future rsyslog versions</a>.</b></p> <p>The major version is incremented whenever a considerate, major features have been added. This is expected to happen quite infrequently.</p> @@ -127,4 +127,4 @@ expected to happen quite infrequently.</p> <p>In general, the unstable branch carries all new development. Once it concludes with a sufficiently-enhanced, quite stable version, a new major stable version is assigned.</p> -</body></html>
\ No newline at end of file +</body></html> |