diff options
Diffstat (limited to '')
| -rw-r--r-- | source/configuration/action/index.rst | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/source/configuration/action/index.rst b/source/configuration/action/index.rst new file mode 100644 index 0000000..e71b7f6 --- /dev/null +++ b/source/configuration/action/index.rst @@ -0,0 +1,193 @@ +Legacy Action-Specific Configuration Statements +=============================================== + +Statements modify the next action(s) that is/are defined **via legacy syntax** +after the respective statement. +Actions defined via the action() object are **not** affected by the +legacy statements listed here. Use the action() object properties +instead. + +Generic action configuration Statements +--------------------------------------- +These statements can be used with all types of actions. + +.. toctree:: + :glob: + + *action* + *rsconf1_repeatedmsgreduction* + +- **$ActionName** <a\_single\_word> - used primarily for documentation, + e.g. when generating a configuration graph. Available since 4.3.1. +- **$ActionExecOnlyOnceEveryInterval** <seconds> - execute action only if + the last execute is at last <seconds> seconds in the past (more info + in `ommail <ommail.html>`_, but may be used with any action). To + disable this setting, use value 0. +- **$ActionExecOnlyEveryNthTime** <number> - 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. +- **$ActionExecOnlyEveryNthTimeTimeout** <number-of-seconds> - has a + meaning only if $ActionExecOnlyEveryNthTime 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 + $ActionExecOnlyEveryNthTimeTimeout 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. +- **$ActionResumeRetryCount** <number> [default 0, -1 means eternal] +- **$ActionWriteAllMarkMessages** [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. + +omfile-specific Configuration Statements +---------------------------------------- +These statements are specific to omfile-based actions. + +.. toctree:: + :glob: + + *omfile* + *dir* + *file* + +- **$CreateDirs** [**on**/off] - create directories on an as-needed + basis +- **$ActionFileDefaultTemplate** [templateName] - sets a new default + template for file actions +- **$ActionFileEnableSync [on/off]** - enables file syncing capability of + omfile +- **$OMFileAsyncWriting** [on/**off**], if turned on, the files will be + written in asynchronous mode via a separate thread. In that case, + double buffers will be used so that one buffer can be filled while + the other buffer is being written. Note that in order to enable + $OMFileFlushInterval, $OMFileAsyncWriting must be set to "on". + Otherwise, the flush interval will be ignored. Also note that when + $OMFileFlushOnTXEnd is "on" but $OMFileAsyncWriting is off, output + will only be written when the buffer is full. This may take several + hours, or even require a rsyslog shutdown. However, a buffer flush + can be forced in that case by sending rsyslogd a HUP signal. +- **$OMFileZipLevel** 0..9 [default 0] - if greater 0, turns on gzip + compression of the output file. The higher the number, the better the + compression, but also the more CPU is required for zipping. +- **$OMFileIOBufferSize** <size\_nbr>, default 4k, size of the buffer + used to writing output data. The larger the buffer, the potentially + better performance is. The default of 4k is quite conservative, it is + useful to go up to 64k, and 128K if you used gzip compression (then, + even higher sizes may make sense) +- **$OMFileFlushOnTXEnd** <[**on**/off]>, default on. Omfile has the + capability to write output using a buffered writer. Disk writes are + only done when the buffer is full. So if an error happens during that + write, data is potentially lost. In cases where this is unacceptable, + set $OMFileFlushOnTXEnd to on. Then, data is written at the end of + each transaction (for pre-v5 this means after **each** log message) + and the usual error recovery thus can handle write errors without + data loss. Note that this option severely reduces the effect of zip + compression and should be switched to off for that use case. Note + that the default -on- is primarily an aid to preserve the traditional + syslogd behaviour. + +omfwd-specific Configuration Statements +--------------------------------------- +These statements are specific to omfwd-based actions. + +- **$ActionForwardDefaultTemplate** [templateName] - sets a new default + template for UDP and plain TCP forwarding action +- **$ActionSendResendLastMsgOnReconnect** <[on/**off**]> specifies if the + last message is to be resend when a connection breaks and has been + reconnected. May increase reliability, but comes at the risk of + message duplication. +- **$ActionSendStreamDriver** <driver basename> just like + $DefaultNetstreamDriver, but for the specific action +- **$ActionSendStreamDriverMode** <mode>, default 0, mode to use with the + stream driver (driver-specific) +- **$ActionSendStreamDriverAuthMode** <mode>, authentication mode to use + with the stream driver. Note that this directive requires TLS + netstream drivers. For all others, it will be ignored. + (driver-specific) +- **$ActionSendStreamDriverPermittedPeer** <ID>, accepted fingerprint + (SHA1) or name of remote peer. Note that this directive requires TLS + netstream drivers. For all others, it will be ignored. + (driver-specific) - directive may go away! +- **$ActionSendTCPRebindInterval** nbr- [available since 4.5.1] - + instructs the TCP send action to close and re-open the connection to + the remote host every nbr of messages sent. Zero, the default, means + that no such processing is done. This directive is useful for use + with load-balancers. Note that there is some performance overhead + associated with it, so it is advisable to not too often "rebind" the + connection (what "too often" actually means depends on your + configuration, a rule of thumb is that it should be not be much more + often than once per second). +- **$ActionSendUDPRebindInterval** nbr- [available since 4.3.2] - + instructs the UDP send action to rebind the send socket every nbr of + messages sent. Zero, the default, means that no rebind is done. This + directive is useful for use with load-balancers. + +omgssapi-specific Configuration Statements +------------------------------------------ +These statements are specific to omgssapi actions. + +.. toctree:: + :glob: + + *gss* + +action-queue specific Configuration Statements +---------------------------------------------- +The following statements specify parameters for the action queue. +To understand queue parameters, read +:doc:`queues in rsyslog <../../concepts/queues>`. + +Action queue parameters usually affect the next action and auto-reset +to defaults thereafter. Most importantly, this means that when a +"real" (non-direct) queue type is defined, this affects the immediately +following action, only. The next and all other actions will be +in "direct" mode (no real queue) if not explicitly specified otherwise. + +- **$ActionQueueCheckpointInterval** <number> +- **$ActionQueueDequeueBatchSize** <number> [default 128] +- **$ActionQueueDequeueSlowdown** <number> [number is timeout in + *micro*\ seconds (1000000us is 1sec!), default 0 (no delay). Simple + rate-limiting!] +- **$ActionQueueDiscardMark** <number> [default 80% of queue size] +- **$ActionQueueDiscardSeverity** <number> [\*numerical\* severity! default + 8 (nothing discarded)] +- **$ActionQueueFileName** <name> +- **$ActionQueueHighWaterMark** <number> [default 90% of queue size] +- **$ActionQueueImmediateShutdown** [on/**off**] +- **$ActionQueueSize** <number> +- **$ActionQueueLowWaterMark** <number> [default 70% of queue size] +- **$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 discard immediately] +- **$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>, num worker threads, default 1, + recommended 1 +- $ActionQueueWorkerThreadMinumumMessages <number>, default 100 +- **$ActionGSSForwardDefaultTemplate** [templateName] - sets a new default + template for GSS-API forwarding action |