Actions

The Action object describe what is to be done with a message. They are implemented via output 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). The are documented separately under queue parameters.
  • 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

    This names the action. The name is used for statistics gathering and documentation. If no name is given, one is dynamically generated based on the occurence of this action inside the rsyslog configuration. Actions are sequentially numbered from 1 to n.

  • type string Mandatory parameter for every action. The name of the module that should be used.

  • action.writeAllMarkMessages on/off This setting tells if mark messages are always written (“on”, the default) or only if the action was not recently executed (“off”). By default, recently means within the past 20 minutes. If this setting is “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. This mode also enables faster processing inside the rule engine. So it should be set to “off” only when there is a good reason to do so.

  • 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.

  • 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).

    Note, however, that a failed action may not immediately be detected.

    For more information, see the rsyslog execOnlyWhenPreviousIsSpuspended preciseness FAQ article.

  • 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).

  • 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.reportSuspension on/off Configures rsyslog to report suspension and reactivation of the action. This is useful to note which actions have problems (e.g. connecting to a remote system) and when. The default for this setting is the equally-named global parameter.

  • action.reportSuspensionContinuation on/off Configures rsyslog to report continuation of action suspension. This emits new messages whenever an action is to be retried, but continues to fail. If set to “on”, action.reportSuspension is also automatically set to “on”. The default for this setting is the equally-named global parameter.