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