From 8b42f06d338b425f164cb3c534fb2dffe474221c Mon Sep 17 00:00:00 2001 From: Florian Riedl Date: Wed, 17 Apr 2013 09:12:55 +0200 Subject: doc: improve action doc --- doc/rsyslog_conf_actions.html | 118 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 1 deletion(-) diff --git a/doc/rsyslog_conf_actions.html b/doc/rsyslog_conf_actions.html index 0c7705f8..a468a403 100644 --- a/doc/rsyslog_conf_actions.html +++ b/doc/rsyslog_conf_actions.html @@ -3,6 +3,123 @@

This is a part of the rsyslog.conf documentation.

back +

Actions

+The action describes what to do with a log 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.
+
+There is a certain base format to configure a action that needs to follow +either a selector or a filter. If no selector or filter is configured +before the action line begins, all messages will be used automatically.
+
+A action line could look like this

*.auth action(type="omfwd" file="/var/log/auth")

Or a little simpler

action(type="omfwd" file="/var/log/auth")

without a selector, which will execute the action for all messages. +The command to initiate a action is always action(). +In the brackets you determine the parameters for the action, like type, +destination or special processing parameters. There are two types of action +parameters. The first are the general action parameters described below. +The second type are the module instance parameters. They are described in +the documentation of the respective module.

General Action Parameters

name word +
used primarily for documentation, e.g. when generating a configuration graph.
type string +
Mandatory parameter for every action. The name of the module that should be used.
action.writeallmarkmessages on/off +
[available since 5.1.5] - Normally, mark messages are written to actions only if the action was not recently executed (by default, recently means within the past 20 minutes). If this setting is switched to "on", mark messages are always sent to actions, no matter how recently they have been executed. In this mode, mark messages can be used as a kind of heartbeat. Note that this option auto-resets to "off", so if you intend to use it with multiple actions, it must be specified in front off all selector lines that should provide this functionality.
action.execonlyeverynthtime integer +
If configured, the next action will only be executed every n-th time. For example, if configured to 3, the first two messages that go into the action will be dropped, the 3rd will actually cause the action to execute, the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note: this setting is automatically re-set when the actual action is defined.
action.execonlyeverynthtimeout integer +
Has a meaning only if Action.ExecOnlyEveryNthTime is also configured for the same action. If so, the timeout setting specifies after which period the counting of "previous actions" expires and a new action count is begun. Specify 0 (the default) to disable timeouts. +Why is this option needed? Consider this case: a message comes in at, eg., 10am. That's count 1. Then, nothing happens for the next 10 hours. At 8pm, the next one occurs. That's count 2. Another 5 hours later, the next message occurs, bringing the total count to 3. Thus, this message now triggers the rule. +The question is if this is desired behavior? Or should the rule only be triggered if the messages occur within an e.g. 20 minute window? If the later is the case, you need a +
Action.ExecOnlyEveryNthTimeTimeout="1200" +
This directive will timeout previous messages seen if they are older than 20 minutes. In the example above, the count would now be always 1 and consequently no rule would ever be triggered.
action.execonlyonceeveryinterval integer +
Execute action only if the last execute is at last seconds in the past (more info in ommail, but may be used with any action)
action.execonlywhenpreviousissuspended on/off +
This directive allows to specify if actions should always be executed ("off," the default) or only if the previous action is suspended ("on"). This directive works hand-in-hand with the multiple actions per selector feature. It can be used, for example, to create rules that automatically switch destination servers or databases to a (set of) backup(s), if the primary server fails. Note that this feature depends on proper implementation of the suspend feature in the output module. All built-in output modules properly support it (most importantly the database write and the syslog message forwarder).
action.repeatedmsgcontainsoriginalmsg on/off +
"last message repeated n times" messages, if generated, have a different format that contains the message that is being repeated. Note that only the first "n" characters are included, with n to be at least 80 characters, most probably more (this may change from version to version, thus no specific limit is given). The bottom line is that n is large enough to get a good idea which message was repeated but it is not necessarily large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.
action.resumeretrycount integer +
[default 0, -1 means eternal]
action.resumeinterval integer +
Sets the ActionResumeInterval for the action. The interval provided is always in seconds. Thus, multiply by 60 if you need minutes and 3,600 if you need hours (not recommended). +When an action is suspended (e.g. destination can not be connected), the action is resumed for the configured interval. Thereafter, it is retried. If multiple retires fail, the interval is automatically extended. This is to prevent excessive ressource use for retires. After each 10 retries, the interval is extended by itself. To be precise, the actual interval is (numRetries / 10 + 1) * Action.ResumeInterval. so after the 10th try, it by default is 60 and after the 100th try it is 330.

Action Queues

For some types of action it would make sense to have a queue ready which +will "store" log messages on a interim basis to prevent message loss. This +commonly applies to the forwarding kind of actions. Here is a list of Parameters +that are used for a action queue. Queues are described in the respective article.

Action.QueueCheckpointInterval number
ActionQueueDequeueBatchSize number (default 16)
ActionQueueDequeueSlowdown number +
number is timeout in microseconds (1000000us is 1sec!), default 0 (no delay). Simple rate-limiting!
ActionQueueDiscardMark number (default 9750)
ActionQueueDiscardSeverity number +
*numerical* severity! default 8 (nothing discarded)
ActionQueueFileName name
ActionQueueHighWaterMark number (default 8000)
ActionQueueImmediateShutdown on/off
ActionQueueSize number
ActionQueueLowWaterMark number (default 2000)
ActionQueueMaxFileSize size_nbr (default 1m)
ActionQueueTimeoutActionCompletion number +
number is timeout in ms (1000ms is 1sec!), default 1000, 0 means immediate!
ActionQueueTimeoutEnqueue number +
number is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite
ActionQueueTimeoutShutdown number +
number is timeout in ms (1000ms is 1sec!), default 0 (indefinite)
ActionQueueWorkerTimeoutThreadShutdown number +
number is timeout in ms (1000ms is 1sec!), default 60000 (1 minute)
ActionQueueType FixedArray/LinkedList/Direct/Disk
ActionQueueSaveOnShutdown on/off
ActionQueueWorkerThreads number +
number of worker threads, default 1, recommended 1
ActionQueueWorkerThreadMinumumMessages number (default 100)

Multiple Actions

You can have multiple actions for a single selector (or more precisely +a single filter of such a selector line). Each action must be called with +it's own action() statement and must all be enclosed by square brackets. +An example would be

*.=crit[ + action(type="omfwd" target="10.10.10.1" port="514" transport="udp") + action(type="omusrmsg" user="rger") + action(type="omfile" file="/var/log/critmsgs") + ]

These three lines send critical messages to a host via UDP, the user rger +and also store them in /var/log/critmsgs. Using multiple actions per selector +is convenient and also offers a performance benefit. As the filter needs to +be evaluated only once, there is less computation required to process +the directive

Stop/Discard

The stop action is no real action. It is basically a trigger to stop +processing of the message. Though, it is basically used instead of action() +in a selector line. For obvious reasons, the result of "stop" is depending +on where in the configuration it is used. Please note, that once processing +of a message has been stopped, there is no way to retrieve it in later +configuration file lines.
+
+Stop 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.
+
+It can be used like this:

Stop

Here, processing for all messages will be stopped and the messages will +be discarded. Though, using it this way is obviously stupid, especially at +the beginning of the configuration.

Actions (legacy format)

The action field of a rule describes what to do with the message. In general, message content is written to a kind of "logfile". @@ -331,7 +448,6 @@ 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.

[manual index] [rsyslog.conf] [rsyslog site]

-- cgit v1.2.3 From 1f3b2e2c74dad8ac0eb554372e4128b65ae8e772 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 17 Apr 2013 09:42:05 +0200 Subject: doc: further improve action doc --- doc/rsyslog_conf_actions.html | 167 +++++++++++++++--------------------------- 1 file changed, 60 insertions(+), 107 deletions(-) diff --git a/doc/rsyslog_conf_actions.html b/doc/rsyslog_conf_actions.html index a468a403..fa240d97 100644 --- a/doc/rsyslog_conf_actions.html +++ b/doc/rsyslog_conf_actions.html @@ -4,129 +4,82 @@

This is a part of the rsyslog.conf documentation.

back

Actions

-The action describes what to do with a log 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.
-
-There is a certain base format to configure a action that needs to follow -either a selector or a filter. If no selector or filter is configured -before the action line begins, all messages will be used automatically.
-
-A action line could look like this

*.auth action(type="omfwd" file="/var/log/auth")

Or a little simpler

action(type="omfwd" file="/var/log/auth")

without a selector, which will execute the action for all messages. -The command to initiate a action is always action(). -In the brackets you determine the parameters for the action, like type, -destination or special processing parameters. There are two types of action -parameters. The first are the general action parameters described below. -The second type are the module instance parameters. They are described in -the documentation of the respective module.

+Action object describe what is to be done with a message. They are +implemented via outpout modules. +

The action object has different parameters: +

those that apply to all actions and are action specific. These + are documented below. +
parameters for the action queue. While they also apply to + all parameters, they are queue-specific, not action-specific (they + are the same that are used in rulesets, for example). +
action-specific parameters. These are specific to a certain + type of actions. They are documented by the output module + in question. +

General Action Parameters

name word -
used primarily for documentation, e.g. when generating a configuration graph.
type string +
name word +
used for statistics gathering and documentation +
type string
Mandatory parameter for every action. The name of the module that should be used.
action.writeallmarkmessages on/off -
[available since 5.1.5] - Normally, mark messages are written to actions only if the action was not recently executed (by default, recently means within the past 20 minutes). If this setting is switched to "on", mark messages are always sent to actions, no matter how recently they have been executed. In this mode, mark messages can be used as a kind of heartbeat. Note that this option auto-resets to "off", so if you intend to use it with multiple actions, it must be specified in front off all selector lines that should provide this functionality.
action.execonlyeverynthtime integer +
action.writeAllMarkMessages on/off +
Normally, mark messages are written to actions only if the action was not recently executed (by default, recently means within the past 20 minutes). If this setting is switched to "on", mark messages are always sent to actions, no matter how recently they have been executed. In this mode, mark messages can be used as a kind of heartbeat. Note that this option auto-resets to "off", so if you intend to use it with multiple actions, it must be specified in front off all selector lines that should provide this functionality.
action.execOnlyEveryNthTime integer
If configured, the next action will only be executed every n-th time. For example, if configured to 3, the first two messages that go into the action will be dropped, the 3rd will actually cause the action to execute, the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note: this setting is automatically re-set when the actual action is defined.
action.execonlyeverynthtimeout integer +
action.execOnlyEveryNthTimeout integer
Has a meaning only if Action.ExecOnlyEveryNthTime is also configured for the same action. If so, the timeout setting specifies after which period the counting of "previous actions" expires and a new action count is begun. Specify 0 (the default) to disable timeouts. Why is this option needed? Consider this case: a message comes in at, eg., 10am. That's count 1. Then, nothing happens for the next 10 hours. At 8pm, the next one occurs. That's count 2. Another 5 hours later, the next message occurs, bringing the total count to 3. Thus, this message now triggers the rule. The question is if this is desired behavior? Or should the rule only be triggered if the messages occur within an e.g. 20 minute window? If the later is the case, you need a
Action.ExecOnlyEveryNthTimeTimeout="1200"
This directive will timeout previous messages seen if they are older than 20 minutes. In the example above, the count would now be always 1 and consequently no rule would ever be triggered.
action.execonlyonceeveryinterval integer +
action.execOnlyOnceEveryInterval integer
Execute action only if the last execute is at last seconds in the past (more info in ommail, but may be used with any action)
action.execonlywhenpreviousissuspended on/off +
action.execOnlyWhenpReviousIsSuspended on/off
This directive allows to specify if actions should always be executed ("off," the default) or only if the previous action is suspended ("on"). This directive works hand-in-hand with the multiple actions per selector feature. It can be used, for example, to create rules that automatically switch destination servers or databases to a (set of) backup(s), if the primary server fails. Note that this feature depends on proper implementation of the suspend feature in the output module. All built-in output modules properly support it (most importantly the database write and the syslog message forwarder).
action.repeatedmsgcontainsoriginalmsg on/off +
action.repeatedmsgcontainsoriginalmsg on/off
"last message repeated n times" messages, if generated, have a different format that contains the message that is being repeated. Note that only the first "n" characters are included, with n to be at least 80 characters, most probably more (this may change from version to version, thus no specific limit is given). The bottom line is that n is large enough to get a good idea which message was repeated but it is not necessarily large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.
action.resumeretrycount integer +
action.resumeRetryCount integer
[default 0, -1 means eternal]
action.resumeinterval integer +
action.resumeInterval integer
Sets the ActionResumeInterval for the action. The interval provided is always in seconds. Thus, multiply by 60 if you need minutes and 3,600 if you need hours (not recommended). When an action is suspended (e.g. destination can not be connected), the action is resumed for the configured interval. Thereafter, it is retried. If multiple retires fail, the interval is automatically extended. This is to prevent excessive ressource use for retires. After each 10 retries, the interval is extended by itself. To be precise, the actual interval is (numRetries / 10 + 1) * Action.ResumeInterval. so after the 10th try, it by default is 60 and after the 100th try it is 330.

Action Queues

For some types of action it would make sense to have a queue ready which -will "store" log messages on a interim basis to prevent message loss. This -commonly applies to the forwarding kind of actions. Here is a list of Parameters -that are used for a action queue. Queues are described in the respective article.

Action.QueueCheckpointInterval number
ActionQueueDequeueBatchSize number (default 16)
ActionQueueDequeueSlowdown number -
number is timeout in microseconds (1000000us is 1sec!), default 0 (no delay). Simple rate-limiting!
ActionQueueDiscardMark number (default 9750)
ActionQueueDiscardSeverity number -
*numerical* severity! default 8 (nothing discarded)
ActionQueueFileName name
ActionQueueHighWaterMark number (default 8000)
ActionQueueImmediateShutdown on/off
ActionQueueSize number
ActionQueueLowWaterMark number (default 2000)
ActionQueueMaxFileSize size_nbr (default 1m)
ActionQueueTimeoutActionCompletion number -
number is timeout in ms (1000ms is 1sec!), default 1000, 0 means immediate!
ActionQueueTimeoutEnqueue number -
number is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite
ActionQueueTimeoutShutdown number -
number is timeout in ms (1000ms is 1sec!), default 0 (indefinite)
ActionQueueWorkerTimeoutThreadShutdown number -
number is timeout in ms (1000ms is 1sec!), default 60000 (1 minute)
ActionQueueType FixedArray/LinkedList/Direct/Disk
ActionQueueSaveOnShutdown on/off
ActionQueueWorkerThreads number -
number of worker threads, default 1, recommended 1
ActionQueueWorkerThreadMinumumMessages number (default 100)

Multiple Actions

You can have multiple actions for a single selector (or more precisely -a single filter of such a selector line). Each action must be called with -it's own action() statement and must all be enclosed by square brackets. -An example would be

*.=crit[ - action(type="omfwd" target="10.10.10.1" port="514" transport="udp") - action(type="omusrmsg" user="rger") - action(type="omfile" file="/var/log/critmsgs") - ]

These three lines send critical messages to a host via UDP, the user rger -and also store them in /var/log/critmsgs. Using multiple actions per selector -is convenient and also offers a performance benefit. As the filter needs to -be evaluated only once, there is less computation required to process -the directive

Stop/Discard

The stop action is no real action. It is basically a trigger to stop -processing of the message. Though, it is basically used instead of action() -in a selector line. For obvious reasons, the result of "stop" is depending -on where in the configuration it is used. Please note, that once processing -of a message has been stopped, there is no way to retrieve it in later -configuration file lines.
-
-Stop 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.
-
-It can be used like this:

Stop

Here, processing for all messages will be stopped and the messages will -be discarded. Though, using it this way is obviously stupid, especially at -the beginning of the configuration.

Actions (legacy format)

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.
-
-Templates can be used with all actions. If used, the specified template + +

Legacy Format

Be warned that legacy action format is hard to get right. It is +recommended to use RainerScript-Style action format whenever possible! +A key problem with legacy format is that a single action is defined via +multiple configurations lines, which may be spread all across rsyslog.conf. +Even the definition of multiple actions may be intermixed (often not +intentional!). If legacy actions format needs to be used (e.g. some modules +may not yet implement the RainerScript format), it is strongly recommended +to place all configuration statements pertaining to a single action +closely together. +

Please also note that legacy action parameters do not affect +RainerScript action objects. So if you define for example: + +

+$actionResumeRetryCount 10
+action(type="omfwd" target="server1.example.net")
+@@server2.example.net
+

+ +server1's "action.resumeRetryCount" parameter is not set, instead +server2's is! +

A goal of the new RainerScript action format was to avoid confusion +which parameters are actually used. As such, it would be counter-productive +to honor legacy action parameters inside a RainerScript definition. As +result, both types of action definitions are strictly (and nicely) +separated from each other. The bottom line is that if RainerScript actions +are used, one does not need to care about which legacy action parameters may +(still...) be in effect. +

Note that not all modules necessarily support legacy action format. +Especially newer modules are recommended to NOT support it. +

Legacy Description

Templates can be used with many 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.
@@ -453,7 +406,7 @@ what you can do with it, see "TEMPLATES" at the top of this document.

[rsyslog site]

-- cgit v1.2.3