diff options
Diffstat (limited to 'doc/property_replacer.html')
| -rw-r--r-- | doc/property_replacer.html | 208 |
1 files changed, 110 insertions, 98 deletions
diff --git a/doc/property_replacer.html b/doc/property_replacer.html index 8a7164c5..a6618616 100644 --- a/doc/property_replacer.html +++ b/doc/property_replacer.html @@ -1,98 +1,110 @@ -<html>
-<head>
-<title>The Rsyslogd Property Replacer</title>
-</head>
-<body>
-<h1>The Property Replacer</h1>
-<p><b>The property replacer is a core component in rsyslogd's output system.</b>
-A syslog message has a number of well-defined properties (see below). Each of
-this properties can be accessed <b>and</b> manipulated by the property replacer.
-With it, it is easy to use only part of a property value or manipulate the value,
-e.g. by converting all characters to lower case.</p>
-<h1>Accessing Properties</h1>
-<p>Syslog message properties are used inside templates. They are accessed by putting them between percent signs. Properties can be modified by
-the property replacer. The full syntax is as follows:</p>
-<blockquote><b><code>%propname:fromChar:toChar:options%</code></b></blockquote>
-<h2>Available Properties</h2>
-<p><b><code>propname</code></b> is the name of the property to access. It is case-sensitive.
-Currently supported are:</p>
-<table>
-<tr><td><b>msg</b></td><td>the MSG part of the message (aka "the message" ;))</td></tr>
-<tr><td><b>rawmsg</b></td><td>the message excactly as it was received from the
-socket. Should be useful for debugging.</td></tr>
-<tr><td><b>UxTradMsg</b></td><td>will disappear soon - do NOT use!</td></tr>
-<tr><td><b>HOSTNAME</b></td><td>hostname from the message</td></tr>
-<tr><td><b>source</b></td><td>alias for HOSTNAME</td></tr>
-<tr><td><b>FROMHOST</b></td><td>hostname of the system the message was received
- from (in a relay chain, this is the system immediately in front of us and
- not necessarily the original sender)</td></tr>
-<tr><td><b>syslogtag</b></td><td>TAG from the message</td></tr>
-<tr><td><b>programname</b></td><td>the "static" part of the tag, as defined by
-BSD syslogd. For example, when TAG is "named[12345]", programname is "named".</td></tr>
-<tr><td><b>PRI</b></td><td>PRI part of the message - undecoded (single value)</td></tr>
-<tr><td><b>IUT</b></td><td>the monitorware InfoUnitType - used when talking
-to a <a href="http://www.monitorware.com">MonitorWare</a> backend (also for
- <a href="http://www.phplogcon.org/">phpLogCon</a>)</td></tr>
-<tr><td><b>syslogfacility</b></td><td>the facility from the message - in numerical form</td></tr>
-<tr><td><b>syslogpriority</b></td><td>the priority (actully severity!) from the
- message - in numerical form</td></tr>
-<tr><td><b>timegenerated</b></td><td>timestamp when the message was RECEIVED. Always in
- high resolution</td></tr>
-<tr><td><b>timereported</b></td><td>timestamp from the message. Resolution depends on
-what was provided in the message (in most cases,
-only seconds)</td></tr>
-<tr><td><b>TIMESTAMP</b></td><td>alias for timereported</td></tr>
-</table>
-<h2>Character Positions</h2>
-<p><b><code>FromChar</code></b> and <b><code>toChar</code></b> are used to build substrings. They specify the offset within
-the string that should be copied. Offset counting starts at 1, so if you need to
-obtain the first 2 characters of the message text, you can use this syntax:
-"%msg:1:2%". If you do not whish to specify from and to, but you want to specify
-options, you still need to include the colons. For example, if you would like to
-convert the full message text to lower case, use "%msg:::lowercase%".
-If you would like to extract from a position until the end of the string, you
-can place a dollar-sign ("$") in toChar (e.g. %msg:10:$%, which will extract
-from position 10 to the end of the string).<p>
-There is also support for <b>regular expressions</b>. To use them, you need to
-place a "R" into FromChar. This tells rsyslog that a regular expression instead
-of position-based extraction is desired. The actual regular expression must then
-be provided in toChar. The regular expression <b>must</b> be followed by the
-string "--end". It denotes the end of the regular expression and will not become
-part of it. If you are using regular expressions, the property replacer will
-return the part of the property text that matches the regular expression. An
-example for a property replacer sequence with a regular expression is: "%msg:R:.*Sev:.
-\(.*\) \[.*--end%"<br>
-<p>
-<b>Also, extraction can be done based on so-called "fields"</b>. To do so, place
a "F" into FromChar. A field in its current definition is anything that is
delimited by a delimiter character. The delimiter by default is TAB (US-ASCII value 9).
-However, if can be changed to any other US-ASCII character by specifying a comma
-and teh <b>decimal</b> US-ASCII value of the delimiter immediately after the
-"F". For example, to use comma (",") as a delimiter, use this field specifier:
-"F,44". If your syslog data is delimited,
this is a quicker way to extract than via regular expressions (actually, a *much*
quicker way). Field counting starts at 1. Field zero is accepted, but will
always lead to a "field not found" error. The same happens if a field number
higher than the number of fields in the property is requested. The field number
must be placed in the "ToChar" parameter. An example where the 3rd field
-(delimited by TAB) from
the msg property is extracted is as follows: "%msg:F:3%". The same
-example with semicolon as delimiter is "%msg:F,59:3%".<p>
-Please note that the special characters "F" and "R" are case-sensitive. Only
upper case works, lower case will return an error. There are no white spaces
-permitted inside the sequence (that will lead to error messages and will NOT
-provide the intended result).<br>
-<h2>Property Options</h2>
-<b><code>property options</code></b> are case-insensitive. Currently, the following options
-are defined:</p>
-<table>
-<tr><td><b>uppercase</b></td><td>convert property to lowercase only</td></tr>
-<tr><td><b>lowercase</b></td><td>convert property text to uppercase only</td></tr>
-<tr><td><b>drop-last-lf</b></td><td>The last LF in the message (if any), is dropped.
- Especially useful for PIX.</td></tr>
-<tr><td><b>date-mysql</b></td><td>format as mysql date</td></tr>
-<tr><td><b>date-rfc3164</b></td><td>format as RFC 3164 date</td></tr>
-<tr><td><b>date-rfc3339</b></td><td>format as RFC 3339 date</td></tr>
-<tr><td><b>escape-cc</b></td><td>replace control characters (ASCII value 127 and
- values less then 32) with an escape sequence. The sequnce is "#<charval>"
- where charval is the 3-digit decimal value of the control character. For
- example, a tabulator would be replaced by "#009".</td></tr>
-<tr><td><b>space-cc</b></td><td>replace control characters by spaces</td></tr>
-<tr><td><b>drop-cc</b></td><td>drop control characters - the resulting string
- will neither contain control characters, escape sequences nor any other
- replacement character like space.</td></tr>
-</table>
-
-</body>
-</html>
+<html> +<head> +<title>The Rsyslogd Property Replacer</title> +</head> +<body> +<h1>The Property Replacer</h1> +<p><b>The property replacer is a core component in rsyslogd's output system.</b> +A syslog message has a number of well-defined properties (see below). Each of +this properties can be accessed <b>and</b> manipulated by the property replacer. +With it, it is easy to use only part of a property value or manipulate the value, +e.g. by converting all characters to lower case.</p> +<h1>Accessing Properties</h1> +<p>Syslog message properties are used inside templates. They are accessed by putting them between percent signs. Properties can be modified by +the property replacer. The full syntax is as follows:</p> +<blockquote><b><code>%propname:fromChar:toChar:options%</code></b></blockquote> +<h2>Available Properties</h2> +<p><b><code>propname</code></b> is the name of the property to access. It is case-sensitive. +Currently supported are:</p> +<table> +<tr><td><b>msg</b></td><td>the MSG part of the message (aka "the message" ;))</td></tr> +<tr><td><b>rawmsg</b></td><td>the message excactly as it was received from the +socket. Should be useful for debugging.</td></tr> +<tr><td><b>UxTradMsg</b></td><td>will disappear soon - do NOT use!</td></tr> +<tr><td><b>HOSTNAME</b></td><td>hostname from the message</td></tr> +<tr><td><b>source</b></td><td>alias for HOSTNAME</td></tr> +<tr><td><b>FROMHOST</b></td><td>hostname of the system the message was received + from (in a relay chain, this is the system immediately in front of us and + not necessarily the original sender)</td></tr> +<tr><td><b>syslogtag</b></td><td>TAG from the message</td></tr> +<tr><td><b>programname</b></td><td>the "static" part of the tag, as defined by +BSD syslogd. For example, when TAG is "named[12345]", programname is "named".</td></tr> +<tr><td><b>PRI</b></td><td>PRI part of the message - undecoded (single value)</td></tr> +<tr><td><b>PRI-text</b></td><td>the PRI part of the message in a textual form + (e.g. "syslog.info")</td></tr> +<tr><td><b>IUT</b></td><td>the monitorware InfoUnitType - used when talking +to a <a href="http://www.monitorware.com">MonitorWare</a> backend (also for + <a href="http://www.phplogcon.org/">phpLogCon</a>)</td></tr> +<tr><td><b>syslogfacility</b></td><td>the facility from the message - in numerical form</td></tr> +<tr><td><b>syslogpriority</b></td><td>the priority (actully severity!) from the + message - in numerical form</td></tr> +<tr><td><b>timegenerated</b></td><td>timestamp when the message was RECEIVED. Always in + high resolution</td></tr> +<tr><td><b>timereported</b></td><td>timestamp from the message. Resolution depends on +what was provided in the message (in most cases, +only seconds)</td></tr> +<tr><td><b>TIMESTAMP</b></td><td>alias for timereported</td></tr> +<tr><td><b>PROTOCOL-VERSION</b></td><td>The contents of the PROTCOL-VERSION + field from IETF draft draft-ietf-syslog-protcol</td></tr> +<tr><td><b>STRUCTURED-DATA</b></td><td>The contents of the STRUCTURED-DATA field + from IETF draft draft-ietf-syslog-protocol</td></tr> +<tr><td><b>APP-NAME</b></td><td>The contents of the APP-NAME field from IETF + draft draft-ietf-syslog-protocol</td></tr> +<tr><td><b>PROCID</b></td><td>The contents of the PROCID field from IETF draft + draft-ietf-syslog-protocol</td></tr> +<tr><td><b>MSGID</b></td><td>The contents of the MSGID field from IETF draft + draft-ietf-syslog-protocol</td></tr> +</table> +<h2>Character Positions</h2> +<p><b><code>FromChar</code></b> and <b><code>toChar</code></b> are used to build substrings. They specify the offset within +the string that should be copied. Offset counting starts at 1, so if you need to +obtain the first 2 characters of the message text, you can use this syntax: +"%msg:1:2%". If you do not whish to specify from and to, but you want to specify +options, you still need to include the colons. For example, if you would like to +convert the full message text to lower case, use "%msg:::lowercase%". +If you would like to extract from a position until the end of the string, you +can place a dollar-sign ("$") in toChar (e.g. %msg:10:$%, which will extract +from position 10 to the end of the string).<p> +There is also support for <b>regular expressions</b>. To use them, you need to +place a "R" into FromChar. This tells rsyslog that a regular expression instead +of position-based extraction is desired. The actual regular expression must then +be provided in toChar. The regular expression <b>must</b> be followed by the +string "--end". It denotes the end of the regular expression and will not become +part of it. If you are using regular expressions, the property replacer will +return the part of the property text that matches the regular expression. An +example for a property replacer sequence with a regular expression is: "%msg:R:.*Sev:. +\(.*\) \[.*--end%"<br> +<p> +<b>Also, extraction can be done based on so-called "fields"</b>. To do so, place
a "F" into FromChar. A field in its current definition is anything that is
delimited by a delimiter character. The delimiter by default is TAB (US-ASCII value 9). +However, if can be changed to any other US-ASCII character by specifying a comma +and teh <b>decimal</b> US-ASCII value of the delimiter immediately after the +"F". For example, to use comma (",") as a delimiter, use this field specifier: +"F,44". If your syslog data is delimited,
this is a quicker way to extract than via regular expressions (actually, a *much*
quicker way). Field counting starts at 1. Field zero is accepted, but will
always lead to a "field not found" error. The same happens if a field number
higher than the number of fields in the property is requested. The field number
must be placed in the "ToChar" parameter. An example where the 3rd field +(delimited by TAB) from
the msg property is extracted is as follows: "%msg:F:3%". The same +example with semicolon as delimiter is "%msg:F,59:3%".<p> +Please note that the special characters "F" and "R" are case-sensitive. Only
upper case works, lower case will return an error. There are no white spaces +permitted inside the sequence (that will lead to error messages and will NOT +provide the intended result).<br> +<h2>Property Options</h2> +<b><code>property options</code></b> are case-insensitive. Currently, the following options +are defined:</p> +<table> +<tr><td><b>uppercase</b></td><td>convert property to lowercase only</td></tr> +<tr><td><b>lowercase</b></td><td>convert property text to uppercase only</td></tr> +<tr><td><b>drop-last-lf</b></td><td>The last LF in the message (if any), is dropped. + Especially useful for PIX.</td></tr> +<tr><td><b>date-mysql</b></td><td>format as mysql date</td></tr> +<tr><td><b>date-rfc3164</b></td><td>format as RFC 3164 date</td></tr> +<tr><td><b>date-rfc3339</b></td><td>format as RFC 3339 date</td></tr> +<tr><td><b>escape-cc</b></td><td>replace control characters (ASCII value 127 and + values less then 32) with an escape sequence. The sequnce is "#<charval>" + where charval is the 3-digit decimal value of the control character. For + example, a tabulator would be replaced by "#009".</td></tr> +<tr><td><b>space-cc</b></td><td>replace control characters by spaces</td></tr> +<tr><td><b>drop-cc</b></td><td>drop control characters - the resulting string + will neither contain control characters, escape sequences nor any other + replacement character like space.</td></tr> +</table> + +</body> +</html> |