diff options
Diffstat (limited to 'doc/rsyslog_conf.html')
| -rw-r--r-- | doc/rsyslog_conf.html | 1651 |
1 files changed, 997 insertions, 654 deletions
diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html index 25298d33..e65be0bc 100644 --- a/doc/rsyslog_conf.html +++ b/doc/rsyslog_conf.html @@ -1,540 +1,863 @@ -<html> -<head> -<title>rsyslog.conf file</title> -</head> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<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> +<ul> +<li><a href="omsnmp.html">omsnmp</a> - SNMP +trap output module</li> +<li><a href="omrelp.html">omrelp</a> - RELP +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="ommail.html">ommail</a> - +permits rsyslog to alert folks by mail if something important happens</li> +<li><a href="imfile.html">imfile</a> +- input module for text files</li> +<li><a href="imrelp.html">imrelp</a> - RELP +input module</li> +<li>imudp - udp syslog message input</li> +<li><a href="imtcp.html">imtcp</a> - input +plugin for plain tcp syslog</li> +<li><a href="imgssapi.html">imgssapi</a> - +input plugin for plain tcp and GSS-enable syslog</li> +<li>immark - support for mark messages</li> +<li><a href="imklog.html">imklog</a> - kernel logging</li> +<li><a href="imuxsock.html">imuxsock</a> - +unix sockets, including the system log socket</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>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><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></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><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><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li> - <li><a href="rsconf1_moddir.html">$ModDir</a></li> - <li><a href="rsconf1_modload.html">$ModLoad</a></li> - <li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li> - <li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li> - <li><a href="rsconf1_umask.html">$UMASK</a></li> +<li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li> +<li>$ActionExecOnlyOnceEveryInterval <seconds> - +execute action only if the last execute is at last +<seconds> seconds in the past (more info in <a href="ommail.html">ommail</a>, +but may be used with any action)</li> +<li>$ActionFileDefaultTemplate [templateName] - sets a new +default template for file actions</li> +<li>$ActionFileEnableSync [on/<span style="font-weight: bold;">off</span>] - enables file +syncing capability of omfile</li> +<li>$ActionForwardDefaultTemplate [templateName] - sets a new +default template for UDP and plain TCP forwarding action</li> +<li>$ActionGSSForwardDefaultTemplate [templateName] - sets a +new default template for GSS-API forwarding action</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>$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><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>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 <severity> +[either a textual or 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><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>$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> <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>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>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>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 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 template to be a proper -SQL statement - so this is highly customizable too. You might ask how does all -of this work when no templates at all are specified. Good question ;) The answer -is simple, though. Templates 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 +<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 +template to be a proper SQL statement - so this is highly customizable +too. You might ask how does all of this work when no templates at all +are specified. Good question ;) The answer is simple, though. Templates +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> -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 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> +<p>Template +names beginning with "RSYSLOG_" are reserved for rsyslog use. Do NOT +use them if, otherwise you may receive a conflict in the future (and +quite unpredictable behaviour). There is a small set of pre-defined +templates that you can use without the need to define it:</p> +<ul> +<li><span style="font-weight: bold;">RSYSLOG_TraditionalFileFormat</span> +- the "old style" default log file format with low-precision timestamps</li> +<li><span style="font-weight: bold;">RSYSLOG_FileFormat</span> +- a modern-style logfile format similar to TraditionalFileFormat, buth +with high-precision timestamps and timezone information</li> +<li><span style="font-weight: bold;">RSYSLOG_TraditionalForwardFormat</span> +- the traditional forwarding format with low-precision timestamps. Most +useful if you send messages to other syslogd's or rsyslogd +below +version 3.12.5.</li> +<li><span style="font-weight: bold;">RSYSLOG_ForwardFormat</span> +- a new high-precision forwarding format very similar to the +traditional one, but with high-precision timestamps and timezone +information. Recommended to be used when sending messages to rsyslog +3.12.5 or above.</li> +<li><span style="font-weight: bold;">RSYSLOG_SyslogProtocol23Format</span> +- the format specified in IETF's internet-draft +ietf-syslog-protocol-23, which is assumed to be come the new syslog +standard RFC. This format includes several improvements. The rsyslog +message parser understands this format, so you can use it together with +all relatively recent versions of rsyslog. Other syslogd's may get +hopelessly confused if receiving that format, so check before you use +it. Note that the format is unlikely to change when the final RFC comes +out, but this may happen.</li> +</ul> <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 log rotation script 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> +<p>Rsyslog offers four different types "filter conditions":</p> <ul> - <li>"traditional" severity and facility based selectors</li> - <li>property-based filters</li> +<li>BSD-style blocks</li> +<li>"traditional" severity and facility based selectors</li> +<li>property-based filters</li> +<li>expression-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> +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><code><b>:property, [!]compare-operation, "value"</b></code></p> -<p>The following <b>compare-operations</b> are currently supported:</p> -<table border="1" width="100%" id="table1"> - <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".</td> - </tr> - <tr> - <td>regex</td> - <td>Compares the property against the provided regular expression.</td> - </tr> +<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> +<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 POSIX +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>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> -: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> -<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><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><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> +: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> +<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><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><code><b>:msg, regex, "fatal .* error"</b></code></p> +<p>This filter uses a POSIX regular expression. It matches when +the +string contains the words "fatal" and "error" with anything in between +(e.g. "fatal net error" and "fatal lib error" but not "fatal error" as +two spaces are required by the regular expression!).</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> +Expression based filters allow +filtering on arbitrary complex expressions, which can include boolean, +arithmetic and string operations. Expression filters will evolve into a +full configuration scripting language. Unfortunately, their syntax will +slightly change during that process. So if you use them now, you need +to be prepared to change your configuration files some time later. +However, we try to implement the scripting facility as soon as possible +(also in respect to stage work needed). So the window of exposure is +probably not too long.<br> +<br> +Expression based filters are indicated by the keyword "if" in column 1 +of a new line. They have this format:<br> +<br> +if expr then action-part-of-selector-line<br> +<br> +"If" and "then" are fixed keywords that mus be present. "expr" is a +(potentially quite complex) expression. So the <a href="expression.h">expression documentation</a> for +details. "action-part-of-selector-line" is an action, just as you know +it (e.g. "/var/log/logfile" to write to that file).<br> +<br> +A few quick samples:<br> +<br> +<code> +*.* /var/log/file1 # the traditional way<br> +if $msg contains 'error' /var/log/errlog # the expression-based way<br> +</code> +<br> +Right now, you need to specify numerical values if you would like to +check for facilities and severity. These can be found in <a href="http://www.ietf.org/rfc/rfc3164.txt">RFC 3164</a>. +If you don't like that, you can of course also use the textual property +- just be sure to use the right one. As expression support is enhanced, +this will change. For example, if you would like to filter on message +that have facility local0, start with "DEVNAME" and have either +"error1" or "error0" in their message content, you could use the +following filter:<br> +<br> +<code> +if $syslogfacility-text == 'local0' and $msg +startswith 'DEVNAME' and ($msg contains 'error1' or $msg contains +'error0') then /var/log/somelog<br> +</code> +<br> +Please note that the above <span style="font-weight: bold;">must +all be on one line</span>! And if you would like to store all +messages except those that contain "error1" or "error0", you just need +to add a "not":<br> +<br> +<code> +if $syslogfacility-text == 'local0' and $msg +startswith 'DEVNAME' and <span style="font-weight: bold;">not</span> +($msg contains 'error1' or $msg contains +'error0') then /var/log/somelog<br> +</code> +<br> +If you would like to do case-insensitive comparisons, use +"contains_i" instead of "contains" and "startswith_i" instead of +"startswith".<br> +<br> +Note that regular expressions are currently NOT +supported in expression-based filters. These will be added later when +function support is added to the expression engine (the reason is that +regular expressions will be a separate loadable module, which requires +some more prequisites before it can be implemented).<br> <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 -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>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> <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> -<table border="1" width="100%" id="table2"> - <tr> - <td> - <p align="center"><b>z<number></b></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.</td> - </tr> - <tr> - <td> - <p align="center"><b>o</b></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...</td> - </tr> +<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> <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>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>Note that IPv6 addresses contain colons. So if an IPv6 address is specified in the hostname part, rsyslogd could not detect where the IP address ends and where the port starts. There is a syntax extension to support this: @@ -544,167 +867,182 @@ brackets also work with real host names and IPv4 addresses, too. is as follows: <p>*.* @[2001::1]:515 <p>This works with TCP, too. -<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><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><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><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 ommysql</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> <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> +$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> -%syslogtag%,%msg%\n"<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> +$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> -$template MySQLInsert,"insert iut, message, receivedat values<br> +$template MySQLInsert,"insert iut, message, receivedat values<br> ('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br> -into systemevents\r\n", SQL<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> +$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br> %timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,<br> %timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,<br> -%syslogtag%%msg%\n"</p> +%syslogtag%%msg%\n"</p> <h3>SELECTOR LINES</h3> <p># Store critical stuff in critical<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> @@ -718,20 +1056,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> @@ -739,25 +1078,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> @@ -765,8 +1105,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> @@ -775,17 +1115,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> @@ -793,37 +1133,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> @@ -833,27 +1174,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> -<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> +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> <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> +</body></html> |