diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2008-02-19 16:16:09 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2008-02-19 16:16:09 +0000 |
| commit | b5a09481faa2eda03b568839ed724970bc8a1adc (patch) | |
| tree | c0f12e58fedc0b90bfdbafd00f5c2c2cd5e6ce01 /doc/rsyslog_conf.html | |
| parent | 47aab374d40c05cbb7a4ceb2a4236cb65a399c3a (diff) | |
| download | rsyslog-b5a09481faa2eda03b568839ed724970bc8a1adc.tar.gz rsyslog-b5a09481faa2eda03b568839ed724970bc8a1adc.tar.xz rsyslog-b5a09481faa2eda03b568839ed724970bc8a1adc.zip | |
implemented initial tokenizer (stage work for expr parser)
Diffstat (limited to 'doc/rsyslog_conf.html')
| -rw-r--r-- | doc/rsyslog_conf.html | 1568 |
1 files changed, 857 insertions, 711 deletions
diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html index 6ced74fc..b87cf66d 100644 --- a/doc/rsyslog_conf.html +++ b/doc/rsyslog_conf.html @@ -1,166 +1,219 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head> -<title>rsyslog.conf file</title></head> +<html><head><title>rsyslog.conf file</title> + +</head> <body> <h1>rsyslog.conf configuration file</h1> -<p><b>This document is currently being enhanced. Please pardon its current -appearance.</b></p> -<p><b>Rsyslogd is configured via the rsyslog.conf file</b>, typically found in -/etc. By default, rsyslogd reads the file /etc/rsyslog.conf. This may be changed -by a command line option.</p> +<p><b>This document is currently being enhanced. Please +pardon its current appearance.</b></p> +<p><b>Rsyslogd is configured via the rsyslog.conf file</b>, +typically found in /etc. By default, rsyslogd reads the file +/etc/rsyslog.conf. This may be changed by a command line option.</p> <p><a href="http://wiki.rsyslog.com/index.php/Configuration_Samples"> Configuration file examples can be found in the rsyslog wiki</a>.</p> -<p>There is also one sample file provided together with the documentation set. -If you do not like to read, be sure to have at least a quick look at -<a href="rsyslog-example.conf">rsyslog-example.conf</a>. </p> -<p>While rsyslogd contains enhancements over standard syslogd, efforts have been -made to keep the configuration file as compatible as possible. While, for -obvious reasons, <a href="features.html">enhanced features</a> require a -different config file syntax, rsyslogd should be able to work with a standard -syslog.conf file. This is especially useful while you are migrating from syslogd -to rsyslogd.</p> +<p>There is also one sample file provided together with the +documentation set. If you do not like to read, be sure to have at least +a quick look at +<a href="rsyslog-example.conf">rsyslog-example.conf</a>. +</p> +<p>While rsyslogd contains enhancements over standard syslogd, +efforts have been made to keep the configuration file as compatible as +possible. While, for obvious reasons, <a href="features.html">enhanced +features</a> require a different config file syntax, rsyslogd +should be able to work with a standard syslog.conf file. This is +especially useful while you are migrating from syslogd to rsyslogd.</p> <h2>Modules</h2> -<p>Rsyslog has a modular design. Consequently, there is a growing number of -modules. Here is the entry point to their documentation and what they do (list -is currently not complete)</p> +<p>Rsyslog has a modular design. Consequently, there is a growing +number of modules. Here is the entry point to their documentation and +what they do (list is currently not complete)</p> <ul> - <li><a href="omsnmp.html">omsnmp</a> - SNMP trap output module</li><li>omgss - output module for GSS-enabled syslog</li> - <li>ommysql - output module for MySQL</li> - <li>ompgsql - output module for PostgreSQL</li> - <li><a href="omlibdbi.html">omlibdbi</a> - generic database output module (Firebird/Interbase, MS SQL, Sybase, SQLLite, Ingres, Oracle, mSQL)</li><li><a href="imfile.html">imfile</a> - input module for text files</li><li>imudp - udp syslog message input</li><li>imtcp - input plugin for plain tcp and GSS-enable syslog</li><li>immark - support for mark messages</li> - <li>imklog - kernel logging</li> +<li><a href="omsnmp.html">omsnmp</a> - SNMP +trap output module</li> +<li>omgss - output module for GSS-enabled syslog</li> +<li>ommysql - output module for MySQL</li> +<li>ompgsql - output module for PostgreSQL</li> +<li><a href="omlibdbi.html">omlibdbi</a> - +generic database output module (Firebird/Interbase, MS SQL, Sybase, +SQLLite, Ingres, Oracle, mSQL)</li> +<li><a href="imfile.html">imfile</a> +- input module for text files</li> +<li>imudp - udp syslog message input</li> +<li>imtcp - input plugin for plain tcp and GSS-enable syslog</li> +<li>immark - support for mark messages</li> +<li>imklog - kernel logging</li> </ul> -<p>Please note that each module provides configuration directives, which are NOT -necessarily being listed below. Also remember, that a modules configuration -directive (and functionality) is only available if it has been loaded (using -$ModLoad).</p> -<h2>Lines</h2>Lines can be continued by specifying a backslash ("\") as the last character of the line.<br><h2>Global Directives</h2> -<p>All global directives need to be specified on a line by their own and must -start with a dollar-sign. Here is a list in alphabetical order. Follow links for -a description.</p> -<p>Not all directives have an in-depth description right now. Default values for -them are in bold. A more in-depth description will appear as implementation -progresses. Directives may change during that process, we will NOT try hard to -maintain backwards compatibility (after all, v3 is still very early in -development and quite unstable...). So you have been warned ;)</p> -<p><b>Be sure to read information about <a href="queues.html">queues in rsyslog</a></b> -- many parameter settings modify queue parameters. If in doubt, use the default, -it is usually well-chosen and applicable in most cases.</p> +<p>Please note that each module provides configuration +directives, which are NOT necessarily being listed below. Also +remember, that a modules configuration directive (and functionality) is +only available if it has been loaded (using $ModLoad).</p> +<h2>Lines</h2> +Lines can be continued by specifying a backslash ("\") as the last +character of the line.<br> +<h2>Global Directives</h2> +<p>All global directives need to be specified on a line by their +own and must start with a dollar-sign. Here is a list in alphabetical +order. Follow links for a description.</p> +<p>Not all directives have an in-depth description right now. +Default values for them are in bold. A more in-depth description will +appear as implementation progresses. Directives may change during that +process, we will NOT try hard to maintain backwards compatibility +(after all, v3 is still very early in development and quite +unstable...). So you have been warned ;)</p> +<p><b>Be sure to read information about <a href="queues.html">queues in rsyslog</a></b> - +many parameter settings modify queue parameters. If in doubt, use the +default, it is usually well-chosen and applicable in most cases.</p> <ul> - <li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li> - <li>$ActionQueueCheckpointInterval <number></li> - <li>$ActionQueueDequeueSlowdown <number> [number is timeout in <i> - micro</i>seconds (1000000us is 1sec!), default 0 (no delay). Simple - rate-limiting!]</li> - <li>$ActionQueueDiscardMark <number> [default 9750]</li> - <li>$ActionQueueDiscardSeverity <number> [*numerical* severity! default 4 (warning)]</li> - <li>$ActionQueueFileName <name></li> - <li>$ActionQueueHighWaterMark <number> [default 8000]</li> - <li>$ActionQueueImmediateShutdown [on/<b>off</b>]</li> - <li>$ActionQueueSize <number></li> - <li>$ActionQueueLowWaterMark <number> [default 2000]</li> - <li>$ActionQueueMaxFileSize <size_nbr>, default 1m</li> - <li>$ActionQueueTimeoutActionCompletion <number> [number is timeout in ms (1000ms is 1sec!), default 1000, 0 means immediate!]</li> - <li>$ActionQueueTimeoutEnqueue <number> [number is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li> - <li>$ActionQueueTimeoutShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li> - <li>$ActionQueueWorkerTimeoutThreadShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 60000 (1 minute)]</li> - <li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li> - <li>$ActionQueueSaveOnShutdown [on/<b>off</b>] - </li><li>$ActionQueueWorkerThreads <number>, num worker threads, default 1, - recommended 1</li> - <li>$ActionQueueWorkerThreadMinumumMessages <number>, default 100</li> - <li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li> - <li>$AddUnixListenSocket <name-of-socket> adds additional unix socket, - default none -- former -a option</li> - <li>$ActionResumeRetryCount <number> [default 0, -1 means eternal]</li> - <li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li> - <li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li> - <li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li> - <li>$DebugPrintKernelSymbols (imklog) [on/<b>off</b>]</li> - <li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li> - <li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li> - <li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li> - <li><a href="rsconf1_dirgroup.html">$DirGroup</a></li> - <li><a href="rsconf1_dirowner.html">$DirOwner</a></li> - <li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li> - <li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li> - <li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li> - <li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li> - <li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li> - <li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li> - <li><a href="rsconf1_filegroup.html">$FileGroup</a></li> - <li><a href="rsconf1_fileowner.html">$FileOwner</a></li> - <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><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li> - <li>$klogSymbolLookup (imklog) [<b>on</b>/off] -- former klogd -x option</li> - <li>$klogUseSyscallInterface (imklog) [on/<b>off</b>] -- former klogd - -2 option</li> - <li>$klogSymbolsTwice (imklog) [on/<b>off</b>] -- former klogd -s option</li> - <li>$MainMsgQueueCheckpointInterval <number></li> - <li>$MainMsgQueueDequeueSlowdown <number> [number is timeout in <i> - micro</i>seconds (1000000us is 1sec!), default 0 (no delay). Simple - rate-limiting!]</li> - <li>$MainMsgQueueDiscardMark <number> [default 9750]</li> - <li>$MainMsgQueueDiscardSeverity <number> [*numerical* severity! default 4 (warning)]</li> - <li>$MainMsgQueueFileName <name></li> - <li>$MainMsgQueueHighWaterMark <number> [default 8000]</li> - <li>$MainMsgQueueImmediateShutdown [on/<b>off</b>]</li> - <li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li> - <li>$MainMsgQueueLowWaterMark <number> [default 2000]</li> - <li>$MainMsgQueueMaxFileSize <size_nbr>, default 1m</li> - <li>$MainMsgQueueTimeoutActionCompletion -<number> [number is timeout in ms (1000ms is 1sec!), default +<li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li> +<li>$ActionQueueCheckpointInterval <number></li> +<li>$ActionQueueDequeueSlowdown <number> [number +is timeout in <i> micro</i>seconds (1000000us is 1sec!), +default 0 (no delay). Simple rate-limiting!]</li> +<li>$ActionQueueDiscardMark <number> [default +9750]</li> +<li>$ActionQueueDiscardSeverity <number> +[*numerical* severity! default 4 (warning)]</li> +<li>$ActionQueueFileName <name></li> +<li>$ActionQueueHighWaterMark <number> [default +8000]</li> +<li>$ActionQueueImmediateShutdown [on/<b>off</b>]</li> +<li>$ActionQueueSize <number></li> +<li>$ActionQueueLowWaterMark <number> [default +2000]</li> +<li>$ActionQueueMaxFileSize <size_nbr>, default 1m</li> +<li>$ActionQueueTimeoutActionCompletion <number> +[number is timeout in ms (1000ms is 1sec!), default 1000, 0 means +immediate!]</li> +<li>$ActionQueueTimeoutEnqueue <number> [number +is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li> +<li>$ActionQueueTimeoutShutdown <number> [number +is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li> +<li>$ActionQueueWorkerTimeoutThreadShutdown +<number> [number is timeout in ms (1000ms is 1sec!), +default 60000 (1 minute)]</li> +<li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li> +<li>$ActionQueueSaveOnShutdown [on/<b>off</b>] +</li> +<li>$ActionQueueWorkerThreads <number>, num +worker threads, default 1, recommended 1</li> +<li>$ActionQueueWorkerThreadMinumumMessages +<number>, default 100</li> +<li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li> +<li>$AddUnixListenSocket <name-of-socket> adds +additional unix socket, default none -- former -a option</li> +<li>$ActionResumeRetryCount <number> [default 0, +-1 means eternal]</li> +<li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li> +<li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li> +<li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li> +<li>$DebugPrintKernelSymbols (imklog) [on/<b>off</b>]</li> +<li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li> +<li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li> +<li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li> +<li><a href="rsconf1_dirgroup.html">$DirGroup</a></li> +<li><a href="rsconf1_dirowner.html">$DirOwner</a></li> +<li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li> +<li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li> +<li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li> +<li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li> +<li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li> +<li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li> +<li><a href="rsconf1_filegroup.html">$FileGroup</a></li> +<li><a href="rsconf1_fileowner.html">$FileOwner</a></li> +<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><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li> +<li>$klogSymbolLookup (imklog) [<b>on</b>/off] -- +former klogd -x option</li> +<li>$klogUseSyscallInterface (imklog) [on/<b>off</b>] +-- former klogd -2 option</li> +<li>$klogSymbolsTwice (imklog) [on/<b>off</b>] -- +former klogd -s option</li> +<li>$MainMsgQueueCheckpointInterval <number></li> +<li>$MainMsgQueueDequeueSlowdown <number> [number +is timeout in <i> micro</i>seconds (1000000us is 1sec!), +default 0 (no delay). Simple rate-limiting!]</li> +<li>$MainMsgQueueDiscardMark <number> [default +9750]</li> +<li>$MainMsgQueueDiscardSeverity <number> +[*numerical* severity! default 4 (warning)]</li> +<li>$MainMsgQueueFileName <name></li> +<li>$MainMsgQueueHighWaterMark <number> [default +8000]</li> +<li>$MainMsgQueueImmediateShutdown [on/<b>off</b>]</li> +<li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li> +<li>$MainMsgQueueLowWaterMark <number> [default +2000]</li> +<li>$MainMsgQueueMaxFileSize <size_nbr>, default +1m</li> +<li>$MainMsgQueueTimeoutActionCompletion +<number> [number is timeout in ms (1000ms is 1sec!), +default 1000, 0 means immediate!]</li> - <li>$MainMsgQueueTimeoutEnqueue <number> [number is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li> - <li>$MainMsgQueueTimeoutShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li> - <li>$MainMsgQueueWorkerTimeoutThreadShutdown <number> [number is timeout in ms (1000ms is 1sec!), default 60000 (1 minute)]</li> - <li>$MainMsgQueueType [<b>FixedArray</b>/LinkedList/Direct/Disk]</li> - <li>$MainMsgQueueSaveOnShutdown [on/<b>off</b>] - </li><li>$MainMsgQueueWorkerThreads <number>, num worker threads, default 1, - recommended 1</li> - <li>$MainMsgQueueWorkerThreadMinumumMessages <number>, default 100</li> - <li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a> (immark)</li> - <li><a href="rsconf1_moddir.html">$ModDir</a></li> - <li><a href="rsconf1_modload.html">$ModLoad</a></li> - <li>$OmitLocalLogging (imuxsock) [on/<b>off</b>] -- former -o option</li> - <li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li> - <li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li> - <li>$WorkDirectory <name> (directory for spool and other work files)</li> - <li>$SystemLogSocketName <name-of-socket> -- former -p option</li> - <li>$UDPServerAddress <IP> (imudp) -- local IP address (or name) the UDP - listens should bind to</li> - <li>$UDPServerRun <port> (imudp) -- former -r<port> option, default 514, - start UDP server on this port, "*" means all addresses</li> - <li><a href="rsconf1_umask.html">$UMASK</a></li> +<li>$MainMsgQueueTimeoutEnqueue <number> [number +is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li> +<li>$MainMsgQueueTimeoutShutdown <number> [number +is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li> +<li>$MainMsgQueueWorkerTimeoutThreadShutdown +<number> [number is timeout in ms (1000ms is 1sec!), +default 60000 (1 minute)]</li> +<li>$MainMsgQueueType [<b>FixedArray</b>/LinkedList/Direct/Disk]</li> +<li>$MainMsgQueueSaveOnShutdown [on/<b>off</b>] +</li> +<li>$MainMsgQueueWorkerThreads <number>, num +worker threads, default 1, recommended 1</li> +<li>$MainMsgQueueWorkerThreadMinumumMessages +<number>, default 100</li> +<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a> +(immark)</li> +<li><a href="rsconf1_moddir.html">$ModDir</a></li> +<li><a href="rsconf1_modload.html">$ModLoad</a></li> +<li>$OmitLocalLogging (imuxsock) [on/<b>off</b>] -- +former -o option</li> +<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li> +<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li> +<li>$WorkDirectory <name> (directory for spool +and other work files)</li> +<li>$SystemLogSocketName <name-of-socket> -- +former -p option</li> +<li>$UDPServerAddress <IP> (imudp) -- local IP +address (or name) the UDP listens should bind to</li> +<li>$UDPServerRun <port> (imudp) -- former +-r<port> option, default 514, start UDP server on this +port, "*" means all addresses</li> +<li><a href="rsconf1_umask.html">$UMASK</a></li> </ul> -<p><b>Where <size_nbr> is 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 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 point of view, "1,,0.0.,.,0" also has -the value 1000. </p> +<p><b>Where <size_nbr> is 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 +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 +point of view, "1,,0.0.,.,0" also has the value 1000. </p> <h2>Basic Structure</h2> -<p>Rsyslog supports standard sysklogd's configuration file format and extends -it. So in general, you can take a "normal" syslog.conf and use it together with -rsyslogd. It will understand everything. However, to use most of rsyslogd's -unique features, you need to add extended configuration directives.</p><p>Rsyslogd -supports the classical, selector-based rule lines. They are still at the heart -of it and all actions are initiated via rule lines. A rule lines is any line not -starting with a $ or the comment sign (#). Lines starting with $ carry -rsyslog-specific directives.</p><p>Every rule line consists of two fields, a selector field and an action field. -These two fields are separated by one or more spaces or tabs. The selector field -specifies a pattern of facilities and priorities belonging to the specified -action.<br> +<p>Rsyslog supports standard sysklogd's configuration file format +and extends it. So in general, you can take a "normal" syslog.conf and +use it together with rsyslogd. It will understand everything. However, +to use most of rsyslogd's unique features, you need to add extended +configuration directives.</p> +<p>Rsyslogd supports the classical, selector-based rule lines. +They are still at the heart of it and all actions are initiated via +rule lines. A rule lines is any line not starting with a $ or the +comment sign (#). Lines starting with $ carry rsyslog-specific +directives.</p> +<p>Every rule line consists of two fields, a selector field and +an action field. These two fields are separated by one or more spaces +or tabs. The selector field specifies a pattern of facilities and +priorities belonging to the specified action.<br> <br> Lines starting with a hash mark ("#'') and empty lines are ignored. - -</p><h2>Templates</h2> -<p>Templates are a key feature of rsyslog. They allow to specify any +</p> +<h2>Templates</h2> +<p>Templates are a key feature of rsyslog. They allow to specify +any format a user might want. They are also used for dynamic file name generation. Every output in rsyslog uses templates - this holds true for files, user messages and so on. The database writer expects its @@ -171,598 +224,685 @@ compatible with the stock syslogd formats are hardcoded into rsyslogd. So if no template is specified, we use one of these hardcoded templates. Search for "template_" in syslogd.c and you will find the hardcoded ones.</p> -<p>A template consists of a template directive, a name, the actual template text -and optional options. A sample is:</p> -<blockquote><code>$template MyTemplateName,"\7Text %property% some more text\n",<options></code></blockquote> -<p>The "$template" is the template directive. It tells rsyslog that this line -contains a template. "MyTemplateName" is the template name. All -other config lines refer to this name. The text within quotes is the actual -template text. The backslash is an escape character, much as it is in C. It does -all these "cool" things. For example, \7 rings the bell (this is an ASCII -value), \n is a new line. C programmers and perl coders have the advantage of -knowing this, but the set in rsyslog is a bit restricted currently. -</p><p> -All text in the template is used literally, except for things within percent -signs. These are properties and allow you access to the contents of the syslog -message. Properties are accessed via the property replacer (nice name, huh) and -it can do cool things, too. For example, it can pick a substring or do -date-specific formatting. More on this is below, on some lines of the property -replacer.<br> -<br> -The <options> part is optional. It carries options influencing the template as -whole. See details below. Be sure NOT to mistake template options with property -options - the later ones are processed by the property replacer and apply to a -SINGLE property, only (and not the whole template).<br> +<p>A template consists of a template directive, a name, the +actual template text and optional options. A sample is:</p> +<blockquote><code>$template MyTemplateName,"\7Text +%property% some more text\n",<options></code></blockquote> +<p>The "$template" is the template directive. It tells rsyslog +that this line contains a template. "MyTemplateName" is the template +name. All +other config lines refer to this name. The text within quotes is the +actual template text. The backslash is an escape character, much as it +is in C. It does all these "cool" things. For example, \7 rings the +bell (this is an ASCII value), \n is a new line. C programmers and perl +coders have the advantage of knowing this, but the set in rsyslog is a +bit restricted currently. +</p> +<p>All text in the template is used literally, except for things +within percent signs. These are properties and allow you access to the +contents of the syslog message. Properties are accessed via the +property replacer (nice name, huh) and it can do cool things, too. For +example, it can pick a substring or do date-specific formatting. More +on this is below, on some lines of the property replacer.<br> +<br> +The <options> part is optional. It carries options +influencing the template as whole. See details below. Be sure NOT to +mistake template options with property options - the later ones are +processed by the property replacer and apply to a SINGLE property, only +(and not the whole template).<br> <br> Template options are case-insensitive. Currently defined are: </p> -<p><b>sql</b> - format the string suitable for a SQL statement in MySQL format. This will -replace single quotes ("'") and the backslash character by their -backslash-escaped counterpart ("\'" and "\\") inside each field. Please note -that in MySQL configuration, the <code class="literal">NO_BACKSLASH_ESCAPES</code> +<p><b>sql</b> - format the string suitable for a SQL +statement in MySQL format. This will replace single quotes ("'") and +the backslash character by their backslash-escaped counterpart ("\'" +and "\\") inside each field. Please note that in MySQL configuration, +the <code class="literal">NO_BACKSLASH_ESCAPES</code> mode must be turned off for this format to work (this is the default).</p> -<p><b>stdsql</b> - format the string suitable for a SQL statement that is to be -sent to a standards-compliant sql server. This will -replace single quotes ("'") by two single quotes ("''") inside each field. -You must use stdsql together with MySQL if in MySQL configuration the -<code class="literal">NO_BACKSLASH_ESCAPES</code> is turned on.</p> -<p>Either the <b>sql</b> or <b>stdsql</b> -option <b>must</b> be specified when a template is used for writing to a database, -otherwise injection might occur. Please note that due to the unfortunate fact -that several vendors have violated the sql standard and introduced their own -escape methods, it is impossible to have a single option doing all the work. -So you yourself must make sure you are using the right format. <b>If you choose +<p><b>stdsql</b> - format the string suitable for a +SQL statement that is to be sent to a standards-compliant sql server. +This will replace single quotes ("'") by two single quotes ("''") +inside each field. You must use stdsql together with MySQL if in MySQL +configuration the +<code class="literal">NO_BACKSLASH_ESCAPES</code> is +turned on.</p> +<p>Either the <b>sql</b> or <b>stdsql</b> +option <b>must</b> be specified when a template is used +for writing to a database, otherwise injection might occur. Please note +that due to the unfortunate fact that several vendors have violated the +sql standard and introduced their own escape methods, it is impossible +to have a single option doing all the work. So you yourself +must make sure you are using the right format. <b>If you choose the wrong one, you are still vulnerable to sql injection.</b><br> <br> -Please note that the database writer *checks* that the sql option is present in -the template. If it is not present, the write database action is disabled. This -is to guard you against accidental forgetting it and then becoming vulnerable -to SQL injection. The sql option can also be useful with files - especially if -you want to import them into a database on another machine for performance -reasons. However, do NOT use it if you do not have a real need for it - among -others, it takes some toll on the processing time. Not much, but on a really -busy system you might notice it ;)</p> -<p>The default template for the write to database action has the sql option set. -As we currently support only MySQL and the sql option matches the default MySQL -configuration, this is a good choice. However, if you have turned on -<code class="literal">NO_BACKSLASH_ESCAPES</code> in your MySQL config, you need -to supply a template with the stdsql option. Otherwise you will become -vulnerable to SQL injection. <br> +Please note that the database writer *checks* that the sql option is +present in the template. If it is not present, the write database +action is disabled. This is to guard you against accidental forgetting +it and then becoming vulnerable to SQL injection. The sql option can +also be useful with files - especially if you want to import them into +a database on another machine for performance reasons. However, do NOT +use it if you do not have a real need for it - among others, it takes +some toll on the processing time. Not much, but on a really busy system +you might notice it ;)</p> +<p>The default template for the write to database action has the +sql option set. As we currently support only MySQL and the sql option +matches the default MySQL configuration, this is a good choice. +However, if you have turned on +<code class="literal">NO_BACKSLASH_ESCAPES</code> in +your MySQL config, you need to supply a template with the stdsql +option. Otherwise you will become vulnerable to SQL injection. <br> <br> To escape:<br> % = \%<br> \ = \\ --> '\' is used to escape (as in C)<br> -$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"<br> -<br> -Properties can be accessed by the <a href="property_replacer.html">property replacer</a> -(see there for details).</p> -<p><b>Please note that as of 1.15.0, templates can also by used to generate -selector lines with dynamic file names.</b> For example, if you would like to -split syslog messages from different hosts to different files (one per host), -you can define the following template:</p> -<blockquote><code>$template DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote> -<p>This template can then be used when defining an output selector line. It will -result in something like "/var/log/system-localhost.log"</p> +$template TraditionalFormat,%timegenerated% %HOSTNAME% +%syslogtag%%msg%\n"<br> +<br> +Properties can be accessed by the <a href="property_replacer.html">property +replacer</a> (see there for details).</p> +<p><b>Please note that as of 1.15.0, templates can also by +used to generate selector lines with dynamic file names.</b> For +example, if you would like to split syslog messages from different +hosts to different files (one per host), you can define the following +template:</p> +<blockquote><code>$template +DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote> +<p>This template can then be used when defining an output +selector line. It will result in something like +"/var/log/system-localhost.log"</p> <h2>Output Channels</h2> -<p>Output Channels are a new concept first introduced in rsyslog 0.9.0. <b>As of this -writing, it is most likely that they will be replaced by something different in -the future.</b> So if you -use them, be prepared to change you configuration file syntax when you upgrade -to a later release.<br> -<br> -The idea behind output channel definitions is that it shall provide an umbrella -for any type of output that the user might want. In essence,<br> -this is the "file" part of selector lines (and this is why we are not sure -output channel syntax will stay after the next review). There is a<br> -difference, though: selector channels both have filter conditions (currently -facility and severity) as well as the output destination. Output channels define -the output definition, only. As of this build, they can only be used to write to -files - not pipes, ttys or whatever else. If we stick with output channels, this -will change over time.</p> -<p>In concept, an output channel includes everything needed to know about an -output actions. In practice, the current implementation only carries<br> -a filename, a maximum file size and a command to be issued when this file size -is reached. More things might be present in future version, which might also -change the syntax of the directive.</p> -<p>Output channels are defined via an $outchannel directive. It's syntax is as -follows:<br> +<p>Output Channels are a new concept first introduced in rsyslog +0.9.0. <b>As of this writing, it is most likely that they will +be replaced by something different in the future.</b> So if you +use them, be prepared to change you configuration file syntax when you +upgrade to a later release.<br> +<br> +The idea behind output channel definitions is that it shall provide an +umbrella for any type of output that the user might want. In essence,<br> +this is the "file" part of selector lines (and this is why we are not +sure output channel syntax will stay after the next review). There is a<br> +difference, though: selector channels both have filter conditions +(currently facility and severity) as well as the output destination. +Output channels define the output definition, only. As of this build, +they can only be used to write to files - not pipes, ttys or whatever +else. If we stick with output channels, this will change over time.</p> +<p>In concept, an output channel includes everything needed to +know about an output actions. In practice, the current implementation +only carries<br> +a filename, a maximum file size and a command to be issued when this +file size is reached. More things might be present in future version, +which might also change the syntax of the directive.</p> +<p>Output channels are defined via an $outchannel directive. It's +syntax is as follows:<br> <br> $outchannel name,file-name,max-size,action-on-max-size<br> <br> -name is the name of the output channel (not the file), file-name is the file -name to be written to, max-size the maximum allowed size and action-on-max-size -a command to be issued when the max size is reached. This command always has -exactly one parameter. The binary is that part of action-on-max-size before the -first space, its parameter is everything behind that space.<br> -<br> -Please note that max-size is queried BEFORE writing the log message to the file. -So be sure to set this limit reasonably low so that any message might fit. For -the current release, setting it 1k lower than you expected is helpful. The -max-size must always be specified in bytes - there are no special symbols (like -1k, 1m,...) at this point of development.<br> -<br> -Keep in mind that $outchannel just defines a channel with "name". It does not -activate it. To do so, you must use a selector line (see below). That selector -line includes the channel name plus an $ sign in front of it. A sample might be:<br> +name is the name of the output channel (not the file), file-name is the +file name to be written to, max-size the maximum allowed size and +action-on-max-size a command to be issued when the max size is reached. +This command always has exactly one parameter. The binary is that part +of action-on-max-size before the first space, its parameter is +everything behind that space.<br> +<br> +Please note that max-size is queried BEFORE writing the log message to +the file. So be sure to set this limit reasonably low so that any +message might fit. For the current release, setting it 1k lower than +you expected is helpful. The max-size must always be specified in bytes +- there are no special symbols (like 1k, 1m,...) at this point of +development.<br> +<br> +Keep in mind that $outchannel just defines a channel with "name". It +does not activate it. To do so, you must use a selector line (see +below). That selector line includes the channel name plus an $ sign in +front of it. A sample might be:<br> <br> *.* $mychannel<br> <br> -In its current form, output channels primarily provide the ability to size-limit -an output file. To do so, specify a maximum size. When this size is reached, -rsyslogd will execute the action-on-max-size command and then reopen the file -and retry. The command should be something like a -<a href="log_rotation_fix_size.html">log rotation script</a> or a similar thing.</p> -<p>If there is no action-on-max-size command or the command did not resolve the -situation, the file is closed and never reopened by rsyslogd (except, of course, -by huping it). This logic was integrated when we first experienced severe issues -with files larger 2gb, which could lead to rsyslogd dumping core. In such cases, -it is more appropriate to stop writing to a single file. Meanwhile, rsyslogd has -been fixed to support files larger 2gb, but obviously only on file systems and -operating system versions that do so. So it can still make sense to enforce a -2gb file size limit.</p> +In its current form, output channels primarily provide the ability to +size-limit an output file. To do so, specify a maximum size. When this +size is reached, rsyslogd will execute the action-on-max-size command +and then reopen the file and retry. The command should be something +like a <a href="log_rotation_fix_size.html">log rotation +script</a> or a similar thing.</p> +<p>If there is no action-on-max-size command or the command did +not resolve the situation, the file is closed and never reopened by +rsyslogd (except, of course, by huping it). This logic was integrated +when we first experienced severe issues with files larger 2gb, which +could lead to rsyslogd dumping core. In such cases, it is more +appropriate to stop writing to a single file. Meanwhile, rsyslogd has +been fixed to support files larger 2gb, but obviously only on file +systems and operating system versions that do so. So it can still make +sense to enforce a 2gb file size limit.</p> <h2>Filter Conditions</h2> <p>Rsyslog offers two different types "filter conditions":</p> <ul> - <li>"traditional" severity and facility based selectors</li> - <li>property-based filters</li> +<li>"traditional" severity and facility based selectors</li> +<li>property-based filters</li> </ul> <h3>Blocks</h3> -<p>Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each block of lines -is separated from the previous block by a program or hostname specification. A -block will only log messages corresponding to the most recent program and -hostname specifications given. Thus, a block which selects ‘ppp’ as the program, -directly followed by a block that selects messages from the hostname ‘dialhost’, -then the second block will only log messages from the ppp program on dialhost. +<p>Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each +block of lines is separated from the previous block by a program or +hostname specification. A block will only log messages corresponding to +the most recent program and hostname specifications given. Thus, a +block which selects ‘ppp’ as the program, directly followed by a block +that selects messages from the hostname ‘dialhost’, then the second +block will only log messages from the ppp program on dialhost. </p> -<p>A program specification is a line beginning with ‘!prog’ and the following -blocks will be associated with calls to syslog from that specific program. A -program specification for ‘foo’ will also match any message logged by the kernel -with the prefix ‘foo: ’. Alternatively, a program specification ‘-foo’ causes the -following blocks to be applied to messages from any program but the one specified. - -A hostname specification of the form ‘+hostname’ and -the following blocks will be applied to messages received from the specified -hostname. Alternatively, a hostname specification ‘-hostname’ causes the -following blocks to be applied to messages from any host but the one specified. - -If the hostname is given as ‘@’, the local hostname will be used. (NOT YET -IMPLEMENTED) A program or hostname specification may be reset by giving the -program or hostname as ‘*’.</p> -<p>Please note that the "#!prog", "#+hostname" and "#-hostname" syntax available -in BSD syslogd is not supported by rsyslogd. By default, no hostname or program -is set.</p> +<p>A program specification is a line beginning with ‘!prog’ and +the following blocks will be associated with calls to syslog from that +specific program. A program specification for ‘foo’ will also match any +message logged by the kernel with the prefix ‘foo: ’. Alternatively, a +program specification ‘-foo’ causes the following blocks to be applied +to messages from any program but the one specified. A hostname +specification of the form ‘+hostname’ and the following blocks will be +applied to messages received from the specified hostname. +Alternatively, a hostname specification ‘-hostname’ causes the +following blocks to be applied to messages from any host but the one +specified. If the hostname is given as ‘@’, the local hostname will be +used. (NOT YET IMPLEMENTED) A program or hostname specification may be +reset by giving the program or hostname as ‘*’.</p> +<p>Please note that the "#!prog", "#+hostname" and "#-hostname" +syntax available in BSD syslogd is not supported by rsyslogd. By +default, no hostname or program is set.</p> <h3>Selectors</h3> -<p><b>Selectors are the traditional way of filtering syslog messages.</b> They -have been kept in rsyslog with their original syntax, because it is well-known, -highly effective and also needed for compatibility with stock syslogd -configuration files. If you just need to filter based on priority and facility, -you should do this with selector lines. They are <b>not</b> second-class -citizens in rsyslog and offer the best performance for this job.</p> -<p>The selector field itself again consists of two parts, a facility and a -priority, separated by a period (``.''). Both parts are case insensitive and can -also be specified as decimal numbers, but don't do that, you have been warned. -Both facilities and priorities are described in rsyslog(3). The names mentioned -below correspond to the similar LOG_-values in /usr/include/rsyslog.h.<br><br>The facility is one of the following keywords: auth, authpriv, cron, daemon, -kern, lpr, mail, mark, news, security (same as auth), syslog, user, uucp and -local0 through local7. The keyword security should not be used anymore and mark -is only for internal use and therefore should not be used in applications. -Anyway, you may want to specify and redirect these messages here. The facility -specifies the subsystem that produced the message, i.e. all mail programs log -with the mail facility (LOG_MAIL) if they log using syslog.<br><br>Please note that the upcoming next syslog-RFC specifies many more facilities. -Support for them will be added in a future version of rsyslog, which might -require changes to existing configuration files.<br><br>The priority is one of the following keywords, in ascending order: debug, info, -notice, warning, warn (same as warning), err, error (same as err), crit, alert, -emerg, panic (same as emerg). The keywords error, warn and panic are deprecated -and should not be used anymore. The priority defines the severity of the message<br> -<br>The behavior of the original BSD syslogd is that all messages of the specified -priority and higher are logged according to the given action. Rsyslogd behaves the same, but has some extensions.<br><br>In addition to the above mentioned names the rsyslogd(8) understands the -following extensions: An asterisk (``*'') stands for all facilities or all -priorities, depending on where it is used (before or after the period). The -keyword none stands for no priority of the given facility.<br><br>You can specify multiple facilities with the same priority pattern in one -statement using the comma (``,'') operator. You may specify as much facilities -as you want. Remember that only the facility part from such a statement is -taken, a priority part would be skipped.</p> -<p>Multiple selectors may be specified for a single action using the semicolon -(``;'') separator. Remember that each selector in the selector field is capable -to overwrite the preceding ones. Using this behavior you can exclude some -priorities from the pattern.</p> -<p>Rsyslogd has a syntax extension to the original BSD source, that makes its -use more intuitively. You may precede every priority with an equation sign -(``='') to specify only this single priority and not any of the above. You may -also (both is valid, too) precede the priority with an exclamation mark (``!'') -to ignore all that priorities, either exact this one or this and any higher -priority. If you use both extensions than the exclamation mark must occur before -the equation sign, just use it intuitively.</p> +<p><b>Selectors are the traditional way of filtering syslog +messages.</b> They have been kept in rsyslog with their original +syntax, because it is well-known, highly effective and also needed for +compatibility with stock syslogd configuration files. If you just need +to filter based on priority and facility, you should do this with +selector lines. They are <b>not</b> second-class citizens +in rsyslog and offer the best performance for this job.</p> +<p>The selector field itself again consists of two parts, a +facility and a priority, separated by a period (``.''). Both parts are +case insensitive and can also be specified as decimal numbers, but +don't do that, you have been warned. Both facilities and priorities are +described in rsyslog(3). The names mentioned below correspond to the +similar LOG_-values in /usr/include/rsyslog.h.<br> +<br> +The facility is one of the following keywords: auth, authpriv, cron, +daemon, kern, lpr, mail, mark, news, security (same as auth), syslog, +user, uucp and local0 through local7. The keyword security should not +be used anymore and mark is only for internal use and therefore should +not be used in applications. Anyway, you may want to specify and +redirect these messages here. The facility specifies the subsystem that +produced the message, i.e. all mail programs log with the mail facility +(LOG_MAIL) if they log using syslog.<br> +<br> +Please note that the upcoming next syslog-RFC specifies many more +facilities. Support for them will be added in a future version of +rsyslog, which might require changes to existing configuration files.<br> +<br> +The priority is one of the following keywords, in ascending order: +debug, info, notice, warning, warn (same as warning), err, error (same +as err), crit, alert, emerg, panic (same as emerg). The keywords error, +warn and panic are deprecated and should not be used anymore. The +priority defines the severity of the message<br> +<br> +The behavior of the original BSD syslogd is that all messages of the +specified priority and higher are logged according to the given action. +Rsyslogd behaves the same, but has some extensions.<br> +<br> +In addition to the above mentioned names the rsyslogd(8) understands +the following extensions: An asterisk (``*'') stands for all facilities +or all priorities, depending on where it is used (before or after the +period). The keyword none stands for no priority of the given facility.<br> +<br> +You can specify multiple facilities with the same priority pattern in +one statement using the comma (``,'') operator. You may specify as much +facilities as you want. Remember that only the facility part from such +a statement is taken, a priority part would be skipped.</p> +<p>Multiple selectors may be specified for a single action using +the semicolon (``;'') separator. Remember that each selector in the +selector field is capable to overwrite the preceding ones. Using this +behavior you can exclude some priorities from the pattern.</p> +<p>Rsyslogd has a syntax extension to the original BSD source, +that makes its use more intuitively. You may precede every priority +with an equation sign (``='') to specify only this single priority and +not any of the above. You may also (both is valid, too) precede the +priority with an exclamation mark (``!'') to ignore all that +priorities, either exact this one or this and any higher priority. If +you use both extensions than the exclamation mark must occur before the +equation sign, just use it intuitively.</p> <h3>Property-Based Filters</h3> -<p>Property-based filters are unique to rsyslogd. They allow to filter on any -property, like HOSTNAME, syslogtag and msg. A list of all currently-supported -properties can be found in the <a href="property_replacer.html">property -replacer documentation</a> (but keep in mind that only the properties, not the -replacer is supported). With this filter, each properties can be checked against -a specified value, using a specified compare operation. Currently, there is only -a single compare operation (contains) available, but additional operations will be added in the -future.</p> -<p>A property-based filter must start with a colon in column 0. This tells -rsyslogd that it is the new filter type. The colon must be followed by the -property name, a comma, the name of the compare operation to carry out, another -comma and then the value to compare against. This value must be quoted. There -can be spaces and tabs between the commas. Property names and compare operations -are case-sensitive, so "msg" works, while "MSG" is an invalid property name. In -brief, the syntax is as follows:</p> +<p>Property-based filters are unique to rsyslogd. They allow to +filter on any property, like HOSTNAME, syslogtag and msg. A list of all +currently-supported properties can be found in the <a href="property_replacer.html">property replacer documentation</a> +(but keep in mind that only the properties, not the replacer is +supported). With this filter, each properties can be checked against a +specified value, using a specified compare operation. Currently, there +is only a single compare operation (contains) available, but additional +operations will be added in the future.</p> +<p>A property-based filter must start with a colon in column 0. +This tells rsyslogd that it is the new filter type. The colon must be +followed by the property name, a comma, the name of the compare +operation to carry out, another comma and then the value to compare +against. This value must be quoted. There can be spaces and tabs +between the commas. Property names and compare operations are +case-sensitive, so "msg" works, while "MSG" is an invalid property +name. In brief, the syntax is as follows:</p> <p><code><b>:property, [!]compare-operation, "value"</b></code></p> -<p>The following <b>compare-operations</b> are currently supported:</p> +<p>The following <b>compare-operations</b> are +currently supported:</p> <table id="table1" border="1" width="100%"> - <tbody><tr> - <td>contains</td> - <td>Checks if the string provided in value is contained in the property. - There must be an exact match, wildcards are not supported.</td> - </tr> - <tr> - <td>isequal</td> - <td>Compares the "value" string provided and the property contents. - These two values must be exactly equal to match. The difference to - contains is that contains searches for the value anywhere inside the - property value, whereas all characters must be identical for isequal. As - such, isequal is most useful for fields like syslogtag or FROMHOST, - where you probably know the exact contents.</td> - </tr> - <tr> - <td>startswith</td> - <td>Checks if the value is found exactly at the beginning of the - property value. For example, if you search for "val" with<p><code><b>:msg, - startswith, "val"</b></code></p> - <p>it will be a match if msg contains "values are in this message" but - it won't match if the msg contains "There are values in this message" - (in the later case, contains would match). Please note that "startswith" - is by far faster than regular expressions. So even once they are - implemented, it can make very much sense (performance-wise) to use "startswith".</p></td> - </tr> - <tr> - <td>regex</td> - <td>Compares the property against the provided regular expression.</td> - </tr> -</tbody></table> -<p>You can use the bang-character (!) immediately in front of a -compare-operation, the outcome of this operation is negated. For example, if msg -contains "This is an informative message", the following sample would not match:</p> +<tbody> +<tr> +<td>contains</td> +<td>Checks if the string provided in value is contained in +the property. There must be an exact match, wildcards are not supported.</td> +</tr> +<tr> +<td>isequal</td> +<td>Compares the "value" string provided and the property +contents. These two values must be exactly equal to match. The +difference to contains is that contains searches for the value anywhere +inside the property value, whereas all characters must be identical for +isequal. As such, isequal is most useful for fields like syslogtag or +FROMHOST, where you probably know the exact contents.</td> +</tr> +<tr> +<td>startswith</td> +<td>Checks if the value is found exactly at the beginning +of the property value. For example, if you search for "val" with +<p><code><b>:msg, startswith, "val"</b></code></p> +<p>it will be a match if msg contains "values are in this +message" but it won't match if the msg contains "There are values in +this message" (in the later case, contains would match). Please note +that "startswith" is by far faster than regular expressions. So even +once they are implemented, it can make very much sense +(performance-wise) to use "startswith".</p> +</td> +</tr> +<tr> +<td>regex</td> +<td>Compares the property against the provided regular +expression.</td> +</tr> +</tbody> +</table> +<p>You can use the bang-character (!) immediately in front of a +compare-operation, the outcome of this operation is negated. For +example, if msg contains "This is an informative message", the +following sample would not match:</p> <p><code><b>:msg, contains, "error"</b></code></p> <p>but this one matches:</p> <p><code><b>:msg, !contains, "error"</b></code></p> -<p>Using negation can be useful if you would like to do some generic processing -but exclude some specific events. You can use the discard action in conjunction -with that. A sample would be:</p> -<p><code><b>*.* /var/log/allmsgs-including-informational.log<br> +<p>Using negation can be useful if you would like to do some +generic processing but exclude some specific events. You can use the +discard action in conjunction with that. A sample would be:</p> +<p><code><b>*.* +/var/log/allmsgs-including-informational.log<br> :msg, contains, "informational" <font color="#ff0000" size="4">~</font> -<br>*.* /var/log/allmsgs-but-informational.log</b></code></p> -<p>Do not overlook the red tilde in line 2! In this sample, all messages are -written to the file allmsgs-including-informational.log. Then, all messages -containing the string "informational" are discarded. That means the config file -lines below the "discard line" (number 2 in our sample) will not be applied to -this message. Then, all remaining lines will also be written to the file -allmsgs-but-informational.log.</p> -<p><b>Value</b> is a quoted string. It supports some escape sequences:</p> +<br> +*.* /var/log/allmsgs-but-informational.log</b></code></p> +<p>Do not overlook the red tilde in line 2! In this sample, all +messages are written to the file allmsgs-including-informational.log. +Then, all messages containing the string "informational" are discarded. +That means the config file lines below the "discard line" (number 2 in +our sample) will not be applied to this message. Then, all remaining +lines will also be written to the file allmsgs-but-informational.log.</p> +<p><b>Value</b> is a quoted string. It supports some +escape sequences:</p> <p>\" - the quote character (e.g. "String with \"Quotes\"")<br> \\ - the backslash character (e.g. "C:\\tmp")</p> -<p>Escape sequences always start with a backslash. Additional escape sequences -might be added in the future. Backslash characters <b>must</b> be escaped. Any -other sequence then those outlined above is invalid and may lead to -unpredictable results.</p> -<p>Probably, "msg" is the most prominent use case of property based filters. It -is the actual message text. If you would like to filter based on some message -content (e.g. the presence of a specific code), this can be done easily by:</p> +<p>Escape sequences always start with a backslash. Additional +escape sequences might be added in the future. Backslash characters <b>must</b> +be escaped. Any other sequence then those outlined above is invalid and +may lead to unpredictable results.</p> +<p>Probably, "msg" is the most prominent use case of property +based filters. It is the actual message text. If you would like to +filter based on some message content (e.g. the presence of a specific +code), this can be done easily by:</p> <p><code><b>:msg, contains, "ID-4711"</b></code></p> -<p>This filter will match when the message contains the string "ID-4711". Please -note that the comparison is case-sensitive, so it would not match if "id-4711" -would be contained in the message.</p> -<p>Getting property-based filters right can sometimes be challenging. In order -to help you do it with as minimal effort as possible, rsyslogd spits out debug -information for all property-based filters during their evaluation. To enable -this, run rsyslogd in foreground and specify the "-d" option.</p> -<p>Boolean operations inside property based filters (like 'message contains -"ID17" or message contains "ID18"') are currently not supported -(except for "not" as outlined above). Please note -that while it is possible to query facility and severity via property-based filters, -it is far more advisable to use classic selectors (see above) for those -cases.</p> +<p>This filter will match when the message contains the string +"ID-4711". Please note that the comparison is case-sensitive, so it +would not match if "id-4711" would be contained in the message.</p> +<p>Getting property-based filters right can sometimes be +challenging. In order to help you do it with as minimal effort as +possible, rsyslogd spits out debug information for all property-based +filters during their evaluation. To enable this, run rsyslogd in +foreground and specify the "-d" option.</p> +<p>Boolean operations inside property based filters (like +'message contains "ID17" or message contains "ID18"') are currently not +supported (except for "not" as outlined above). Please note that while +it is possible to query facility and severity via property-based +filters, it is far more advisable to use classic selectors (see above) +for those cases.</p> +<h3>Expression-Based Filters</h3> +So far, please see <a href="expression.h">expressions</a>. <h2>ACTIONS</h2> -<p>The action field of a rule describes what to do with the message. In general, -message content is written to a kind of "logfile". But also other actions might -be done, like writing to a database table or forwarding to another host.<br> -<br> -Templates can be used with all actions. If used, the specified template is used -to generate the message content (instead of the default template). To specify a -template, write a semicolon after the action value immediately followed by the -template name.<br> -<br> -Beware: templates MUST be defined BEFORE they are used. It is OK to define some -templates, then use them in selector lines, define more templates and use use -them in the following selector lines. But it is NOT permitted to use a template -in a selector line that is above its definition. If you do this, the action will be ignored.</p> -<p><b>You can have multiple actions for a single selector </b> (or more -precisely a single filter of such a selector line). Each action must be on its -own line and the line must start with an ampersand ('&') character and have no -filters. An example would be</p> +<p>The action field of a rule describes what to do with the +message. In general, message content is written to a kind of "logfile". +But also other actions might be done, like writing to a database table +or forwarding to another host.<br> +<br> +Templates can be used with all actions. If used, the specified template +is used to generate the message content (instead of the default +template). To specify a template, write a semicolon after the action +value immediately followed by the template name.<br> +<br> +Beware: templates MUST be defined BEFORE they are used. It is OK to +define some templates, then use them in selector lines, define more +templates and use use them in the following selector lines. But it is +NOT permitted to use a template in a selector line that is above its +definition. If you do this, the action will be ignored.</p> +<p><b>You can have multiple actions for a single selector </b> (or +more precisely a single filter of such a selector line). Each action +must be on its own line and the line must start with an ampersand +('&') character and have no filters. An example would be</p> <p><code><b>*.=crit rger<br> & root<br> & /var/log/critmsgs</b></code></p> -<p>These three lines send critical messages to the user rger and root and also -store them in /var/log/critmsgs. <b>Using multiple actions per selector is</b> -convenient and also <b>offers a performance benefit</b>. As the filter needs to -be evaluated only once, there is less computation required to process the -directive compared to the otherwise-equal config directives below:</p> +<p>These three lines send critical messages to the user rger and +root and also store them in /var/log/critmsgs. <b>Using multiple +actions per selector is</b> convenient and also <b>offers +a performance benefit</b>. As the filter needs to be evaluated +only once, there is less computation required to process the directive +compared to the otherwise-equal config directives below:</p> <p><code><b>*.=crit rger<br> *.=crit root<br> *.=crit /var/log/critmsgs</b></code></p> <p> </p> <h3>Regular File</h3> -<p>Typically messages are logged to real files. The file has to be specified with -full pathname, beginning with a slash "/''.<br> +<p>Typically messages are logged to real files. The file has to +be specified with full pathname, beginning with a slash "/''.<br> <br> -You may prefix each entry with the minus ``-'' sign to omit syncing the file -after every logging. Note that you might lose information if the system crashes -right behind a write attempt. Nevertheless this might give you back some -performance, especially if you run programs that use +You may prefix each entry with the minus ``-'' sign to omit syncing the +file after every logging. Note that you might lose information if the +system crashes right behind a write attempt. Nevertheless this might +give you back some performance, especially if you run programs that use logging in a very verbose manner.</p> -<p>If your system is connected to a reliable UPS and you receive lots of log -data (e.g. firewall logs), it might be a very good idea to turn of +<p>If your system is connected to a reliable UPS and you receive +lots of log data (e.g. firewall logs), it might be a very good idea to +turn of syncing by specifying the "-" in front of the file name. </p> -<p><b>The filename can be either static </b>(always the same) or <b>dynamic</b> -(different based on message received). The later is useful if you would -automatically split messages into different files based on some message -criteria. For example, dynamic file name selectors allow you to split messages -into different files based on the host that sent them. With dynamic file names, -everything is automatic and you do not need any filters. </p> -<p>It works via the template system. First, you define a template for the file -name. An example can be seen above in the description of template. We will use -the "DynFile" template defined there. Dynamic filenames are indicated by -specifying a questions mark "?" instead of a slash, followed by the template -name. Thus, the selector line for our dynamic file name would look as follows:</p> +<p><b>The filename can be either static </b>(always +the same) or <b>dynamic</b> (different based on message +received). The later is useful if you would automatically split +messages into different files based on some message criteria. For +example, dynamic file name selectors allow you to split messages into +different files based on the host that sent them. With dynamic file +names, everything is automatic and you do not need any filters. </p> +<p>It works via the template system. First, you define a template +for the file name. An example can be seen above in the description of +template. We will use the "DynFile" template defined there. Dynamic +filenames are indicated by specifying a questions mark "?" instead of a +slash, followed by the template name. Thus, the selector line for our +dynamic file name would look as follows:</p> <blockquote> <code>*.* ?DynFile</code> </blockquote> -<p>That's all you need to do. Rsyslog will now automatically generate file names -for you and store the right messages into the right files. Please note that the -minus sign also works with dynamic file name selectors. Thus, to avoid syncing, -you may use</p> +<p>That's all you need to do. Rsyslog will now automatically +generate file names for you and store the right messages into the right +files. Please note that the minus sign also works with dynamic file +name selectors. Thus, to avoid syncing, you may use</p> <blockquote> <code>*.* -?DynFile</code></blockquote> -<p>And of course you can use templates to specify the output format:</p> +<p>And of course you can use templates to specify the output +format:</p> <blockquote> <code>*.* ?DynFile;MyTemplate</code></blockquote> -<p><b>A word of caution:</b> rsyslog creates files as needed. So if a new host -is using your syslog server, rsyslog will automatically create a new file for -it.</p> - -<p><b>Creating directories is also supported</b>. For example you can use the hostname as directory -and the program name as file name:</p> +<p><b>A word of caution:</b> rsyslog creates files as +needed. So if a new host is using your syslog server, rsyslog will +automatically create a new file for it.</p> +<p><b>Creating directories is also supported</b>. For +example you can use the hostname as directory and the program name as +file name:</p> <blockquote> <code>$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"</code></blockquote> - <h3>Named Pipes</h3> -<p>This version of rsyslogd(8) has support for logging output to named pipes (fifos). -A fifo or named pipe can be used as a destination for log messages by prepending -a pipe symbol (``|'') to the name of the file. This is handy for debugging. Note -that the fifo must be created with the mkfifo(1) command before rsyslogd(8) is -started.</p> +<p>This version of rsyslogd(8) has support for logging output to +named pipes (fifos). A fifo or named pipe can be used as a destination +for log messages by prepending a pipe symbol (``|'') to the name of the +file. This is handy for debugging. Note that the fifo must be created +with the mkfifo(1) command before rsyslogd(8) is started.</p> <h3>Terminal and Console</h3> -<p>If the file you specified is a tty, special tty-handling is done, same with -/dev/console.</p> +<p>If the file you specified is a tty, special tty-handling is +done, same with /dev/console.</p> <h3>Remote Machine</h3> -<p>Rsyslogd provides full remote logging, i.e. is able to send messages to a -remote host running rsyslogd(8) and to receive messages from remote hosts. -Using this feature you're able to control all syslog messages on one host, if -all other machines will log remotely to that. This tears down<br> +<p>Rsyslogd provides full remote logging, i.e. is able to send +messages to a remote host running rsyslogd(8) and to receive messages +from remote hosts. Using this feature you're able to control all syslog +messages on one host, if all other machines will log remotely to that. +This tears down<br> administration needs.<br> <br> -<b>Please note that this version of rsyslogd by default does NOT forward messages -it has received from the network to another host. Specify the "-h" option to enable this.</b></p> -<p>To forward messages to another host, prepend the hostname with the at sign ("@"). -A single at sign means that messages will be forwarded via UDP protocol (the -standard for syslog). If you prepend two at signs ("@@"), the messages will be -transmitted via TCP. Please note that plain TCP based syslog is not officially -standardized, but most major syslogds support it (e.g. syslog-ng or WinSyslog). -The forwarding action indicator (at-sign) can be followed by one or more options. -If they are given, they must be immediately (without a space) following the -final at sign and be enclosed in parenthesis. The individual options must be -separated by commas. The following options are right now defined:</p> +<b>Please note that this version of rsyslogd by default does NOT +forward messages it has received from the network to another host. +Specify the "-h" option to enable this.</b></p> +<p>To forward messages to another host, prepend the hostname with +the at sign ("@"). A single at sign means that messages will +be forwarded via UDP protocol (the standard for syslog). If you prepend +two at signs ("@@"), the messages will be transmitted via TCP. Please +note that plain TCP based syslog is not officially standardized, but +most major syslogds support it (e.g. syslog-ng or WinSyslog). The +forwarding action indicator (at-sign) can be followed by one or more +options. If they are given, they must be immediately (without a space) +following the final at sign and be enclosed in parenthesis. The +individual options must be separated by commas. The following options +are right now defined:</p> <table id="table2" border="1" width="100%"> - <tbody><tr> - <td> - <p align="center"><b>z<number></b></p></td> - <td>Enable zlib-compression for the message. The <number> is the - compression level. It can be 1 (lowest gain, lowest CPU overhead) to 9 (maximum - compression, highest CPU overhead). The level can also be 0, which means - "no compression". If given, the "z" option is ignored. So this does not - make an awful lot of sense. There is hardly a difference between level 1 - and 9 for typical syslog messages. You can expect a compression gain - between 0% and 30% for typical messages. Very chatty messages may - compress up to 50%, but this is seldom seen with typically traffic. - Please note that rsyslogd checks the compression gain. Messages with 60 - bytes or less will never be compressed. This is because compression gain - is pretty unlikely and we prefer to save CPU cycles. Messages over that - size are always compressed. However, it is checked if there is a gain in - compression and only if there is, the compressed message is transmitted. - Otherwise, the uncompressed messages is transmitted. This saves the - receiver CPU cycles for decompression. It also prevents small message to - actually become larger in compressed form.<p><b>Please note that when a - TCP transport is used, compression will also turn on - syslog-transport-tls framing. See the "o" option for important - information on the implications.</b></p> - <p>Compressed messages are automatically detected and decompressed by - the receiver. There is nothing that needs to be configured on the - receiver side.</p></td> - </tr> - <tr> - <td> - <p align="center"><b>o</b></p></td> - <td><b>This option is experimental. Use at your own risk and only if you - know why you need it! If in doubt, do NOT turn it on.</b><p>This option - is only valid for plain TCP based transports. It selects a different - framing based on IETF internet draft syslog-transport-tls-06. This - framing offers some benefits over traditional LF-based framing. However, - the standardization effort is not yet complete. There may be changes in - upcoming versions of this standard. Rsyslog will be kept in line with - the standard. There is some chance that upcoming changes will be - incompatible to the current specification. In this case, all systems - using -transport-tls framing must be upgraded. There will be no effort - made to retain compatibility between different versions of rsyslog. The - primary reason for that is that it seems technically impossible to - provide compatibility between some of those changes. So you should take - this note very serious. It is not something we do not *like* to do (and - may change our mind if enough people beg...), it is something we most - probably *can not* do for technical reasons (aka: you can beg as much as - you like, it won't change anything...).</p> - <p>The most important implication is that compressed syslog messages via - TCP must be considered with care. Unfortunately, it is technically - impossible to transfer compressed records over traditional syslog plain - tcp transports, so you are left with two evil choices...</p></td> - </tr> -</tbody></table> +<tbody> +<tr> +<td> +<p align="center"><b>z<number></b></p> +</td> +<td>Enable zlib-compression for the message. The +<number> is the compression level. It can be 1 (lowest +gain, lowest CPU overhead) to 9 (maximum compression, highest CPU +overhead). The level can also be 0, which means "no compression". If +given, the "z" option is ignored. So this does not make an awful lot of +sense. There is hardly a difference between level 1 and 9 for typical +syslog messages. You can expect a compression gain between 0% and 30% +for typical messages. Very chatty messages may compress up to 50%, but +this is seldom seen with typically traffic. Please note that rsyslogd +checks the compression gain. Messages with 60 bytes or less will never +be compressed. This is because compression gain is pretty unlikely and +we prefer to save CPU cycles. Messages over that size are always +compressed. However, it is checked if there is a gain in compression +and only if there is, the compressed message is transmitted. Otherwise, +the uncompressed messages is transmitted. This saves the receiver CPU +cycles for decompression. It also prevents small message to actually +become larger in compressed form. +<p><b>Please note that when a TCP transport is used, +compression will also turn on syslog-transport-tls framing. See the "o" +option for important information on the implications.</b></p> +<p>Compressed messages are automatically detected and +decompressed by the receiver. There is nothing that needs to be +configured on the receiver side.</p> +</td> +</tr> +<tr> +<td> +<p align="center"><b>o</b></p> +</td> +<td><b>This option is experimental. Use at your own +risk and only if you know why you need it! If in doubt, do NOT turn it +on.</b> +<p>This option is only valid for plain TCP based +transports. It selects a different framing based on IETF internet draft +syslog-transport-tls-06. This framing offers some benefits over +traditional LF-based framing. However, the standardization effort is +not yet complete. There may be changes in upcoming versions of this +standard. Rsyslog will be kept in line with the standard. There is some +chance that upcoming changes will be incompatible to the current +specification. In this case, all systems using -transport-tls framing +must be upgraded. There will be no effort made to retain compatibility +between different versions of rsyslog. The primary reason for that is +that it seems technically impossible to provide compatibility between +some of those changes. So you should take this note very serious. It is +not something we do not *like* to do (and may change our mind if enough +people beg...), it is something we most probably *can not* do for +technical reasons (aka: you can beg as much as you like, it won't +change anything...).</p> +<p>The most important implication is that compressed syslog +messages via TCP must be considered with care. Unfortunately, it is +technically impossible to transfer compressed records over traditional +syslog plain tcp transports, so you are left with two evil choices...</p> +</td> +</tr> +</tbody> +</table> <p><br> The hostname may be followed by a colon and the destination port.</p> <p>The following is an example selector line with forwarding:</p> <p>*.* @@(o,z9)192.168.0.1:1470</p> -<p>In this example, messages are forwarded via plain TCP with experimental -framing and maximum compression to the host 192.168.0.1 at port 1470.</p> +<p>In this example, messages are forwarded via plain TCP with +experimental framing and maximum compression to the host 192.168.0.1 at +port 1470.</p> <p>*.* @192.168.0.1</p> -<p>In the example above, messages are forwarded via UDP to the machine -192.168.0.1, the destination port defaults to 514. Messages will not be -compressed.</p> -<p><b>Note to sysklogd users:</b> sysklogd does <b>not</b> support RFC 3164 -format, which is the default forwarding template in rsyslog. As such, you will -experience duplicate hostnames if rsyslog is the sender and sysklogd is the -receiver. The fix is simple: you need to use a different template. Use that one:</p> -<p class="MsoPlainText">$template sysklogd,"<%PRI%>%TIMESTAMP% -%syslogtag%%msg%\""<br> +<p>In the example above, messages are forwarded via UDP to the +machine 192.168.0.1, the destination port defaults to 514. Messages +will not be compressed.</p> +<p><b>Note to sysklogd users:</b> sysklogd does <b>not</b> +support RFC 3164 format, which is the default forwarding template in +rsyslog. As such, you will experience duplicate hostnames if rsyslog is +the sender and sysklogd is the receiver. The fix is simple: you need to +use a different template. Use that one:</p> +<p class="MsoPlainText">$template +sysklogd,"<%PRI%>%TIMESTAMP% %syslogtag%%msg%\""<br> *.* @192.168.0.1;sysklogd</p> <h3>List of Users</h3> -<p>Usually critical messages are also directed to ``root'' on that machine. You can -specify a list of users that shall get the message by simply writing the login. -You may specify more than one user by separating them with commas (",''). If -they're logged in they get the message. Don't think a mail would be sent, that -might be too late.</p> +<p>Usually critical messages are also directed to ``root'' on +that machine. You can specify a list of users that shall get the +message by simply writing the login. You may specify more than one user +by separating them with commas (",''). If they're logged in they get +the message. Don't think a mail would be sent, that might be too late.</p> <h3>Everyone logged on</h3> -<p>Emergency messages often go to all users currently online to notify them that -something strange is happening with the system. To specify this wall(1)-feature -use an asterisk ("*'').</p> +<p>Emergency messages often go to all users currently online to +notify them that something strange is happening with the system. To +specify this wall(1)-feature use an asterisk ("*'').</p> <h3>Call Plugin</h3> -<p>This is a generic way to call an output plugin. The plugin must support this -functionality. Actual parameters depend on the module, so see the module's doc -on what to supply. The general syntax is as follows:</p> +<p>This is a generic way to call an output plugin. The plugin +must support this functionality. Actual parameters depend on the +module, so see the module's doc on what to supply. The general syntax +is as follows:</p> <p>:modname:params;template</p> -<p>Currently, the ommysql database output module supports this syntax (in -addtion to the ">" syntax it traditionally supported). For ommysql, the module -name is "ommysql" and the params are the traditional ones. The ;template part is -not module specific, it is generic rsyslog functionality available to all -modules.</p> +<p>Currently, the ommysql database output module supports this +syntax (in addtion to the ">" syntax it traditionally +supported). For ommysql, the module name is "ommysql" and the params +are the traditional ones. The ;template part is not module specific, it +is generic rsyslog functionality available to all modules.</p> <p>As an example, the ommysql module may be called as follows:</p> <p>:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate</p> -<p>For details, please see the "Database Table" section of this documentation.</p> -<p>Note: as of this writing, the ":modname:" part is hardcoded into the module. -So the name to use is not necessarily the name the module's plugin file is -called.</p> +<p>For details, please see the "Database Table" section of this +documentation.</p> +<p>Note: as of this writing, the ":modname:" part is hardcoded +into the module. So the name to use is not necessarily the name the +module's plugin file is called.</p> <h3>Database Table</h3> -<p>This allows logging of the message to a database table. Currently, only MySQL -databases are supported. However, other database drivers will most probably be -developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible schema is required -for this to work. You can create that schema with the createDB.SQL file that -came with the rsyslog package. You can also<br> -use any other schema of your liking - you just need to define a proper template -and assign this template to the action.<br> -<br> -The database writer is called by specifying a greater-then sign (">") in front -of the database connect information. Immediately after that<br> -sign the database host name must be given, a comma, the database name, another -comma, the database user, a comma and then the user's password. If a specific -template is to be used, a semicolon followed by the template name can follow -the connect information. This is as follows:<br> +<p>This allows logging of the message to a database table. +Currently, only MySQL databases are supported. However, other database +drivers will most probably be developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible +schema is required for this to work. You can create that schema with +the createDB.SQL file that came with the rsyslog package. You can also<br> +use any other schema of your liking - you just need to define a proper +template and assign this template to the action.<br> +<br> +The database writer is called by specifying a greater-then sign +(">") in front of the database connect information. Immediately +after that<br> +sign the database host name must be given, a comma, the database name, +another comma, the database user, a comma and then the user's password. +If a specific template is to be used, a semicolon followed by the +template name can follow the connect information. This is as follows:<br> <br> >dbhost,dbname,dbuser,dbpassword;dbtemplate</p> -<p><b>Important: to use the database functionality, the MySQL output module must be -loaded in the config file</b> BEFORE the first database table action is used. This is done by -placing the</p> +<p><b>Important: to use the database functionality, the +MySQL output module must be loaded in the config file</b> BEFORE +the first database table action is used. This is done by placing the</p> <p><code><b>$ModLoad MySQL</b></code></p> -<p>directive some place above the first use of the database write (we recommend -doing at the the beginning of the config file).</p> +<p>directive some place above the first use of the database write +(we recommend doing at the the beginning of the config file).</p> <h3>Discard</h3> -<p>If the discard action is carried out, the received message is immediately -discarded. No further processing of it occurs. Discard has primarily been added -to filter out messages before carrying on any further processing. For obvious -reasons, the results of "discard" are depending on where in the configuration -file it is being used. Please note that once a message has been discarded there -is no way to retrieve it in later configuration file lines.</p> -<p>Discard can be highly effective if you want to filter out some annoying -messages that otherwise would fill your log files. To do that, place the discard -actions early in your log files. This often plays well with property-based -filters, giving you great freedom in specifying what you do not want.</p> -<p>Discard is just the single tilde character with no further parameters:</p> +<p>If the discard action is carried out, the received message is +immediately discarded. No further processing of it occurs. Discard has +primarily been added to filter out messages before carrying on any +further processing. For obvious reasons, the results of "discard" are +depending on where in the configuration file it is being used. Please +note that once a message has been discarded there is no way to retrieve +it in later configuration file lines.</p> +<p>Discard can be highly effective if you want to filter out some +annoying messages that otherwise would fill your log files. To do that, +place the discard actions early in your log files. This often plays +well with property-based filters, giving you great freedom in +specifying what you do not want.</p> +<p>Discard is just the single tilde character with no further +parameters:</p> <p>~</p> <p>For example,</p> <p>*.* ~</p> -<p>discards everything (ok, you can achive the same by not running rsyslogd at -all...).</p> +<p>discards everything (ok, you can achive the same by not +running rsyslogd at all...).</p> <h3>Output Channel</h3> -<p>Binds an output channel definition (see there for details) to this action. -Output channel actions must start with a $-sign, e.g. if you would like to bind -your output channel definition "mychannel" to the action, use "$mychannel". -Output channels support template definitions like all all other actions.</p> +<p>Binds an output channel definition (see there for details) to +this action. Output channel actions must start with a $-sign, e.g. if +you would like to bind your output channel definition "mychannel" to +the action, use "$mychannel". Output channels support template +definitions like all all other actions.</p> <h3>Shell Execute</h3> -<p>This executes a program in a subshell. The program is passed the -template-generated message as the only command line parameter. Rsyslog waits -until the program terminates and only then continues to run.</p> +<p>This executes a program in a subshell. The program is passed +the template-generated message as the only command line parameter. +Rsyslog waits until the program terminates and only then continues to +run.</p> <p>^program-to-execute;template</p> -<p>The program-to-execute can be any valid executable. It receives the template -string as a single parameter (argv[1]).</p> -<p><b>WARNING:</b> The Shell Execute action was added to serve an urgent need. -While it is considered reasonable save when used with some thinking, its -implications must be considered. The current implementation uses a system() call -to execute the command. This is not the best way to do it (and will hopefully -changed in further releases). Also, proper escaping of special characters is -done to prevent command injection. However, attackers always find smart ways to -circumvent escaping, so we can not say if the escaping applied will really safe -you from all hassles. Lastly, rsyslog will wait until the shell command -terminates. Thus, a program error in it (e.g. an infinite loop) can actually -disable rsyslog. Even without that, during the programs run-time no messages are -processed by rsyslog. As the IP stacks buffers are quickly overflowed, this -bears an increased risk of message loss. You must be aware of these implications. -Even though they are severe, there are several cases where the "shell execute" -action is very useful. This is the reason why we have included it in its current -form. To mitigate its risks, always a) test your program thoroughly, b) make -sure its runtime is as short as possible (if it requires a longer run-time, you -might want to spawn your own sub-shell asynchronously), c) apply proper -firewalling so that only known senders can send syslog messages to rsyslog. -Point c) is especially important: if rsyslog is accepting message from any hosts, -chances are much higher that an attacker might try to exploit the "shell execute" -action.</p> +<p>The program-to-execute can be any valid executable. It +receives the template string as a single parameter (argv[1]).</p> +<p><b>WARNING:</b> The Shell Execute action was added +to serve an urgent need. While it is considered reasonable save when +used with some thinking, its implications must be considered. The +current implementation uses a system() call to execute the command. +This is not the best way to do it (and will hopefully changed in +further releases). Also, proper escaping of special characters is done +to prevent command injection. However, attackers always find smart ways +to circumvent escaping, so we can not say if the escaping applied will +really safe you from all hassles. Lastly, rsyslog will wait until the +shell command terminates. Thus, a program error in it (e.g. an infinite +loop) can actually disable rsyslog. Even without that, during the +programs run-time no messages are processed by rsyslog. As the IP +stacks buffers are quickly overflowed, this bears an increased risk of +message loss. You must be aware of these implications. Even though they +are severe, there are several cases where the "shell execute" action is +very useful. This is the reason why we have included it in its current +form. To mitigate its risks, always a) test your program thoroughly, b) +make sure its runtime is as short as possible (if it requires a longer +run-time, you might want to spawn your own sub-shell asynchronously), +c) apply proper firewalling so that only known senders can send syslog +messages to rsyslog. Point c) is especially important: if rsyslog is +accepting message from any hosts, chances are much higher that an +attacker might try to exploit the "shell execute" action.</p> <h2>TEMPLATE NAME</h2> -<p>Every ACTION can be followed by a template name. If so, that template is used -for message formatting. If no name is given, a hard-coded default template is -used for the action. There can only be one template name for each given action. -The default template is specific to each action. For a description of what a -template is and what you can do with it, see "TEMPLATES" at the top of this -document.</p> +<p>Every ACTION can be followed by a template name. If so, that +template is used for message formatting. If no name is given, a +hard-coded default template is used for the action. There can only be +one template name for each given action. The default template is +specific to each action. For a description of what a template is and +what you can do with it, see "TEMPLATES" at the top of this document.</p> <h2>EXAMPLES</h2> -<p>Below are example for templates and selector lines. I hope they are -self-explanatory. If not, please see www.monitorware.com/rsyslog/ for advise.</p> +<p>Below are example for templates and selector lines. I hope +they are self-explanatory. If not, please see +www.monitorware.com/rsyslog/ for advise.</p> <h3>TEMPLATES</h3> -<p>Please note that the samples are split across multiple lines. A template MUST -NOT actually be split across multiple lines.<br> +<p>Please note that the samples are split across multiple lines. +A template MUST NOT actually be split across multiple lines.<br> <br> A template that resembles traditional syslogd file output:<br> $template TraditionalFormat,"%timegenerated% %HOSTNAME%<br> %syslogtag%%msg:::drop-last-lf%\n"<br> <br> A template that tells you a little more about the message:<br> -$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br> +$template +precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br> %syslogtag%,%msg%\n"<br> <br> A template for RFC 3164 format:<br> -$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"<br> +$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% +%syslogtag%%msg%"<br> <br> A template for the format traditonally used for user messages:<br> $template usermsg," XXXX%syslogtag%%msg%\n\r"<br> <br> And a template with the traditonal wall-message format:<br> -$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated%<br> +$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at +%timegenerated%<br> <br> A template that can be used for the database write (please note the SQL<br> template option)<br> @@ -770,12 +910,12 @@ $template MySQLInsert,"insert iut, message, receivedat values<br> ('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br> into systemevents\r\n", SQL<br> <br> -The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a> -format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a> format, you do -not feel bad if you don't know it ;)). It's interesting to see how it takes -different parts out of the date stamps. What happens is that the date stamp is -split into the actual date and time and the these two are combined with just a -comma in between them.<br> +The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a> +format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a> +format, you do not feel bad if you don't know it ;)). It's interesting +to see how it takes different parts out of the date stamps. What +happens is that the date stamp is split into the actual date and time +and the these two are combined with just a comma in between them.<br> <br> $template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br> %timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,<br> @@ -786,8 +926,8 @@ $template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br> #<br> *.=crit;kern.none /var/adm/critical<br> <br> -This will store all messages with the priority crit in the file /var/adm/critical, -except for any kernel message.<br> +This will store all messages with the priority crit in the file +/var/adm/critical, except for any kernel message.<br> <br> <br> # Kernel messages are first, stored in the kernel<br> @@ -801,20 +941,21 @@ kern.crit @finlandia;RFC3164fmt<br> kern.crit /dev/console<br> kern.info;kern.!err /var/adm/kernel-info<br> <br> -The first rule direct any message that has the kernel facility to the file /var/adm/kernel.<br> +The first rule direct any message that has the kernel facility to the +file /var/adm/kernel.<br> <br> -The second statement directs all kernel messages of the priority crit and higher -to the remote host finlandia. This is useful, because if the host crashes and -the disks get irreparable errors you might not be able to read the stored -messages. If they're on a remote host, too, you still can try to find out the -reason for the crash.<br> +The second statement directs all kernel messages of the priority crit +and higher to the remote host finlandia. This is useful, because if the +host crashes and the disks get irreparable errors you might not be able +to read the stored messages. If they're on a remote host, too, you +still can try to find out the reason for the crash.<br> <br> -The third rule directs these messages to the actual console, so the person who -works on the machine will get them, too.<br> +The third rule directs these messages to the actual console, so the +person who works on the machine will get them, too.<br> <br> -The fourth line tells rsyslogd to save all kernel messages that come with -priorities from info up to warning in the file /var/adm/kernel-info. Everything -from err and higher is excluded.<br> +The fourth line tells rsyslogd to save all kernel messages that come +with priorities from info up to warning in the file +/var/adm/kernel-info. Everything from err and higher is excluded.<br> <br> <br> # The tcp wrapper loggs with mail.info, we display<br> @@ -822,25 +963,26 @@ from err and higher is excluded.<br> #<br> mail.=info /dev/tty12<br> <br> -This directs all messages that uses mail.info (in source LOG_MAIL | LOG_INFO) to -/dev/tty12, the 12th console. For example the tcpwrapper tcpd(8) uses this as -it's default.<br> +This directs all messages that uses mail.info (in source LOG_MAIL | +LOG_INFO) to /dev/tty12, the 12th console. For example the tcpwrapper +tcpd(8) uses this as it's default.<br> <br> <br> # Store all mail concerning stuff in a file<br> #<br> mail.*;mail.!=info /var/adm/mail<br> <br> -This pattern matches all messages that come with the mail facility, except for -the info priority. These will be stored in the file /var/adm/mail.<br> +This pattern matches all messages that come with the mail facility, +except for the info priority. These will be stored in the file +/var/adm/mail.<br> <br> <br> # Log all mail.info and news.info messages to info<br> #<br> mail,news.=info /var/adm/info<br> <br> -This will extract all messages that come either with mail.info or with news.info -and store them in the file /var/adm/info.<br> +This will extract all messages that come either with mail.info or with +news.info and store them in the file /var/adm/info.<br> <br> <br> # Log info and notice messages to messages file<br> @@ -848,8 +990,8 @@ and store them in the file /var/adm/info.<br> *.=info;*.=notice;\<br> mail.none /var/log/messages<br> <br> -This lets rsyslogd log all messages that come with either the info or the notice -facility into the file /var/log/messages, except for all<br> +This lets rsyslogd log all messages that come with either the info or +the notice facility into the file /var/log/messages, except for all<br> messages that use the mail facility.<br> <br> <br> @@ -858,17 +1000,17 @@ messages that use the mail facility.<br> *.=info;\<br> mail,news.none /var/log/messages<br> <br> -This statement causes rsyslogd to log all messages that come with the info -priority to the file /var/log/messages. But any message coming either with the -mail or the news facility will not be stored.<br> +This statement causes rsyslogd to log all messages that come with the +info priority to the file /var/log/messages. But any message coming +either with the mail or the news facility will not be stored.<br> <br> <br> # Emergency messages will be displayed using wall<br> #<br> *.=emerg *<br> <br> -This rule tells rsyslogd to write all emergency messages to all currently logged -in users. This is the wall action.<br> +This rule tells rsyslogd to write all emergency messages to all +currently logged in users. This is the wall action.<br> <br> <br> # Messages of the priority alert will be directed<br> @@ -876,37 +1018,38 @@ in users. This is the wall action.<br> #<br> *.alert root,rgerhards<br> <br> -This rule directs all messages with a priority of alert or higher to the -terminals of the operator, i.e. of the users ``root'' and ``rgerhards'' if -they're logged in.<br> +This rule directs all messages with a priority of alert or higher to +the terminals of the operator, i.e. of the users ``root'' and +``rgerhards'' if they're logged in.<br> <br> <br> *.* @finlandia<br> <br> -This rule would redirect all messages to a remote host called finlandia. This is -useful especially in a cluster of machines where all syslog messages will be -stored on only one machine.<br> +This rule would redirect all messages to a remote host called +finlandia. This is useful especially in a cluster of machines where all +syslog messages will be stored on only one machine.<br> <br> -In the format shown above, UDP is used for transmitting the message. The -destination port is set to the default auf 514. Rsyslog is also capable of using -much more secure and reliable TCP sessions for message forwarding. Also, the -destination port can be specified. To select TCP, simply add one additional @ in -front of the host name (that is, @host is UPD, @@host is TCP). For example:<br> +In the format shown above, UDP is used for transmitting the message. +The destination port is set to the default auf 514. Rsyslog is also +capable of using much more secure and reliable TCP sessions for message +forwarding. Also, the destination port can be specified. To select TCP, +simply add one additional @ in front of the host name (that is, @host +is UPD, @@host is TCP). For example:<br> <br> <br> *.* @@finlandia<br> <br> -To specify the destination port on the remote machine, use a colon followed by -the port number after the machine name. The following forwards to port 1514 on -finlandia:<br> +To specify the destination port on the remote machine, use a colon +followed by the port number after the machine name. The following +forwards to port 1514 on finlandia:<br> <br> <br> *.* @@finlandia:1514<br> <br> -This syntax works both with TCP and UDP based syslog. However, you will probably -primarily need it for TCP, as there is no well-accepted port for this transport -(it is non-standard). For UDP, you can usually stick with the default auf 514, -but might want to modify it for security rea-<br> +This syntax works both with TCP and UDP based syslog. However, you will +probably primarily need it for TCP, as there is no well-accepted port +for this transport (it is non-standard). For UDP, you can usually stick +with the default auf 514, but might want to modify it for security rea-<br> sons. If you would like to do that, it's quite easy:<br> <br> <br> @@ -916,26 +1059,29 @@ sons. If you would like to do that, it's quite easy:<br> <br> *.* >dbhost,dbname,dbuser,dbpassword;dbtemplate<br> <br> -This rule writes all message to the database "dbname" hosted on "dbhost". The -login is done with user "dbuser" and password "dbpassword". The actual table -that is updated is specified within the template (which contains the insert -statement). The template is called "dbtemplate" in this case.</p> +This rule writes all message to the database "dbname" hosted on +"dbhost". The login is done with user "dbuser" and password +"dbpassword". The actual table that is updated is specified within the +template (which contains the insert statement). The template is called +"dbtemplate" in this case.</p> <p>:msg,contains,"error" @errorServer</p> -<p>This rule forwards all messages that contain the word "error" in the msg part -to the server "errorServer". Forwarding is via UDP. Please note the colon in -fron</p> +<p>This rule forwards all messages that contain the word "error" +in the msg part to the server "errorServer". Forwarding is via UDP. +Please note the colon in fron</p> <h2>CONFIGURATION FILE SYNTAX DIFFERENCES</h2> -<p>Rsyslogd uses a slightly different syntax for its configuration file than the -original BSD sources. Originally all messages of a specific priority and above -were forwarded to the log file. The modifiers ``='', ``!'' and ``-'' were added -to make rsyslogd more flexible and to use it in a more intuitive manner.<br> -<br> -The original BSD syslogd doesn't understand spaces as separators between the -selector and the action field.<br> -<br> -When compared to syslogd from sysklogd package, rsyslogd offers additional -<a href="features.html">features</a> (like template and database support). For obvious reasons, the syntax for -defining such features is available -in rsyslogd, only.<br> +<p>Rsyslogd uses a slightly different syntax for its +configuration file than the original BSD sources. Originally all +messages of a specific priority and above were forwarded to the log +file. The modifiers ``='', ``!'' and ``-'' were added to make rsyslogd +more flexible and to use it in a more intuitive manner.<br> +<br> +The original BSD syslogd doesn't understand spaces as separators +between the selector and the action field.<br> +<br> +When compared to syslogd from sysklogd package, rsyslogd offers +additional +<a href="features.html">features</a> (like template +and database support). For obvious reasons, the syntax for defining +such features is available in rsyslogd, only.<br> </p> </body></html>
\ No newline at end of file |