diff options
Diffstat (limited to 'source/configuration/action')
13 files changed, 560 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 diff --git a/source/configuration/action/rsconf1_actionexeconlywhenpreviousissuspended.rst b/source/configuration/action/rsconf1_actionexeconlywhenpreviousissuspended.rst new file mode 100644 index 0000000..11251fe --- /dev/null +++ b/source/configuration/action/rsconf1_actionexeconlywhenpreviousissuspended.rst @@ -0,0 +1,41 @@ +$ActionExecOnlyWhenPreviousIsSuspended +-------------------------------------- + +**Type:** action configuration parameter + +**Default:** off + +**Description:** + +This parameter allows to specify if actions should always be executed +("off," the default) or only if the previous action is suspended ("on"). +This parameter 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). + +This selector processes all messages it receives (\*.\*). It tries to +forward every message to primary-syslog.example.com (via tcp). If it can +not reach that server, it tries secondary-1-syslog.example.com, if that +fails too, it tries secondary-2-syslog.example.com. If neither of these +servers can be connected, the data is stored in /var/log/localbuffer. +Please note that the secondaries and the local log buffer are only used +if the one before them does not work. So ideally, /var/log/localbuffer +will never receive a message. If one of the servers resumes operation, +it automatically takes over processing again. + +We strongly advise not to use repeated line reduction together with +ActionExecOnlyWhenPreviousIsSuspended. It may lead to "interesting" and +undesired results (but you can try it if you like). + +Example:: + + *.* @@primary-syslog.example.com + $ActionExecOnlyWhenPreviousIsSuspended on + & @@secondary-1-syslog.example.com # & is used to have more than one action for + & @@secondary-2-syslog.example.com # the same selector - the multi-action feature + & /var/log/localbuffer + $ActionExecOnlyWhenPreviousIsSuspended off # to re-set it for the next selector diff --git a/source/configuration/action/rsconf1_actionresumeinterval.rst b/source/configuration/action/rsconf1_actionresumeinterval.rst new file mode 100644 index 0000000..69d2114 --- /dev/null +++ b/source/configuration/action/rsconf1_actionresumeinterval.rst @@ -0,0 +1,26 @@ +$ActionResumeInterval +--------------------- + +**Type:** action configuration parameter + +**Default:** 30 + +**Description:** + +Sets the ActionResumeInterval for all following actions. 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 retries fail, the interval is automatically +extended. This is to prevent excessive resource use for retries. After +each 10 retries, the interval is extended by itself. To be precise, the +actual interval is (numRetries / 10 + 1) \* $ActionResumeInterval. so +after the 10th try, it by default is 60 and after the 100th try it is +330. + +**Sample:** + +$ActionResumeInterval 30 + diff --git a/source/configuration/action/rsconf1_dirgroup.rst b/source/configuration/action/rsconf1_dirgroup.rst new file mode 100644 index 0000000..c965a43 --- /dev/null +++ b/source/configuration/action/rsconf1_dirgroup.rst @@ -0,0 +1,19 @@ +$DirGroup +--------- + +**Type:** global configuration parameter + +**Default:** + +**Description:** + +Set the group for directories newly created. Please note that this +setting does not affect the group of directories already existing. The +parameter is a group name, for which the groupid is obtained by rsyslogd +on during startup processing. Interim changes to the user mapping are +not detected. + +**Sample:** + +``$DirGroup loggroup`` + diff --git a/source/configuration/action/rsconf1_dirowner.rst b/source/configuration/action/rsconf1_dirowner.rst new file mode 100644 index 0000000..4bb2701 --- /dev/null +++ b/source/configuration/action/rsconf1_dirowner.rst @@ -0,0 +1,19 @@ +$DirOwner +--------- + +**Type:** global configuration parameter + +**Default:** + +**Description:** + +Set the file owner for directories newly created. Please note that this +setting does not affect the owner of directories already existing. The +parameter is a user name, for which the userid is obtained by rsyslogd +during startup processing. Interim changes to the user mapping are not +detected. + +**Sample:** + +``$DirOwner loguser`` + diff --git a/source/configuration/action/rsconf1_dynafilecachesize.rst b/source/configuration/action/rsconf1_dynafilecachesize.rst new file mode 100644 index 0000000..71ddc53 --- /dev/null +++ b/source/configuration/action/rsconf1_dynafilecachesize.rst @@ -0,0 +1,4 @@ +$DynaFileCacheSize +------------------ + +This is an :doc:`omfile <../modules/omfile>` parameter. See there for details. diff --git a/source/configuration/action/rsconf1_filecreatemode.rst b/source/configuration/action/rsconf1_filecreatemode.rst new file mode 100644 index 0000000..63f1ad7 --- /dev/null +++ b/source/configuration/action/rsconf1_filecreatemode.rst @@ -0,0 +1,43 @@ +$FileCreateMode +--------------- + +**Type:** global configuration parameter + +**Default:** 0644 + +**Description:** + +The $FileCreateMode parameter allows to specify the creation mode with +which rsyslogd creates new files. If not specified, the value 0644 is +used (which retains backward-compatibility with earlier releases). The +value given must always be a 4-digit octal number, with the initial +digit being zero. + +Please note that the actual permission depend on rsyslogd's process +umask. If in doubt, use "$umask 0000" right at the beginning of the +configuration file to remove any restrictions. + +$FileCreateMode may be specified multiple times. If so, it specifies the +creation mode for all selector lines that follow until the next +$FileCreateMode parameter. Order of lines is vitally important. + +**Sample:** + +``$FileCreateMode 0600`` + +This sample lets rsyslog create files with read and write access only +for the users it runs under. + +The following sample is deemed to be a complete rsyslog.conf:: + + $umask 0000 # make sure nothing interferes with the following definitions + *.* /var/log/file-with-0644-default + $FileCreateMode 0600 + *.* /var/log/file-with-0600 + $FileCreateMode 0644 + *.* /var/log/file-with-0644 + +As you can see, open modes depend on position in the config file. Note +the first line, which is created with the hardcoded default creation +mode. + diff --git a/source/configuration/action/rsconf1_filegroup.rst b/source/configuration/action/rsconf1_filegroup.rst new file mode 100644 index 0000000..7b33381 --- /dev/null +++ b/source/configuration/action/rsconf1_filegroup.rst @@ -0,0 +1,18 @@ +$FileGroup +---------- + +**Type:** global configuration parameter + +**Default:** + +**Description:** + +Set the group for dynaFiles newly created. Please note that this setting +does not affect the group of files already existing. The parameter is a +group name, for which the groupid is obtained by rsyslogd during startup +processing. Interim changes to the user mapping are not detected. + +**Sample:** + +``$FileGroup loggroup`` + diff --git a/source/configuration/action/rsconf1_fileowner.rst b/source/configuration/action/rsconf1_fileowner.rst new file mode 100644 index 0000000..1ad6a6e --- /dev/null +++ b/source/configuration/action/rsconf1_fileowner.rst @@ -0,0 +1,19 @@ +$FileOwner +---------- + +**Type:** global configuration parameter + +**Default:** + +**Description:** + +Set the file owner for dynaFiles newly created. Please note that this +setting does not affect the owner of files already existing. The +parameter is a user name, for which the userid is obtained by rsyslogd +during startup processing. Interim changes to the user mapping are not +detected. + +**Sample:** + +``$FileOwner loguser`` + diff --git a/source/configuration/action/rsconf1_gssforwardservicename.rst b/source/configuration/action/rsconf1_gssforwardservicename.rst new file mode 100644 index 0000000..c2e2fa1 --- /dev/null +++ b/source/configuration/action/rsconf1_gssforwardservicename.rst @@ -0,0 +1,21 @@ +$GssForwardServiceName +---------------------- + +**Type:** global configuration parameter + +**Default:** host + +**Provided by:** *omgssapi* + +**Description:** + +Specifies the service name used by the client when forwarding GSS-API +wrapped messages. + +The GSS-API service names are constructed by appending '@' and a +hostname following "@@" in each selector. + +**Sample:** + +``$GssForwardServiceName rsyslog`` + diff --git a/source/configuration/action/rsconf1_gssmode.rst b/source/configuration/action/rsconf1_gssmode.rst new file mode 100644 index 0000000..8e3b8b6 --- /dev/null +++ b/source/configuration/action/rsconf1_gssmode.rst @@ -0,0 +1,20 @@ +$GssMode +-------- + +**Type:** global configuration parameter + +**Default:** encryption + +**Provided by:** *omgssapi* + +**Description:** + +Specifies GSS-API mode to use, which can be "**integrity**\ " - clients +are authenticated and messages are checked for integrity, +"**encryption**\ " - same as "integrity", but messages are also +encrypted if both sides support it. + +**Sample:** + +``$GssMode Encryption`` + diff --git a/source/configuration/action/rsconf1_omfileforcechown.rst b/source/configuration/action/rsconf1_omfileforcechown.rst new file mode 100644 index 0000000..5eba119 --- /dev/null +++ b/source/configuration/action/rsconf1_omfileforcechown.rst @@ -0,0 +1,67 @@ +$omfileForceChown +----------------- + +**Type:** action configuration parameter + +**Parameter Values:** boolean (on/off, yes/no) + +**Available:** 4.7.0+, 5.3.0-5.8.x, **NOT** available in 5.9.x or higher + +**Note: this parameter has been removed and is no longer available. The +documentation is currently being retained for historical reaons.** +Expect it to go away at some later stage as well. + +**Default:** off + +**Description:** + +Forces rsyslogd to change the ownership for output files that already +exist. Please note that this tries to fix a potential problem that +exists outside the scope of rsyslog. Actually, it tries to fix invalid +ownership/permission settings set by the original file creator. + +Rsyslog changes the ownership during initial execution with root +privileges. When a privilege drop is configured, privileges are dropped +after the file owner ship is changed. Not that this currently is a +limitation in rsyslog's privilege drop code, which is on the TODO list +to be removed. See Caveats section below for the important implications. + +**Caveats:** + +This parameter tries to fix a problem that actually is outside the scope +of rsyslog. As such, there are a couple of restrictions and situations +in which it will not work. **Users are strongly encouraged to fix their +system instead of turning this parameter on** - it should only be used +as a last resort. + +At least in the following scenario, this parameter will fail expectedly: + +It does not address the situation that someone changes the ownership +\*after\* rsyslogd has started. Let's, for example, consider a log +rotation script. + +- rsyslog is started +- ownership is changed +- privileges dropped +- log rotation (lr) script starts +- lr removes files +- lr creates new files with root:adm (or whatever else) +- lr HUPs rsyslogd +- rsyslogd closes files +- rsyslogd tries to open files +- rsyslogd tries to change ownership --> fail as we are non-root now +- file open fails + +Please note that once the privilege drop code is refactored, this +parameter will no longer work, because then privileges will be dropped +before any action is performed, and thus we will no longer be able to +chown files that do not belong to the user rsyslogd is configured to run +under. + +So **expect the parameter to go away**. It will not be removed in +version 4, but may disappear at any time for any version greater than 4. + +**Sample:** + +``$FileOwner loguser $omfileForceChown on`` + diff --git a/source/configuration/action/rsconf1_repeatedmsgreduction.rst b/source/configuration/action/rsconf1_repeatedmsgreduction.rst new file mode 100644 index 0000000..33ddeb9 --- /dev/null +++ b/source/configuration/action/rsconf1_repeatedmsgreduction.rst @@ -0,0 +1,70 @@ +$RepeatedMsgReduction +--------------------- + +**Type:** global configuration parameter + +**Default:** off + +Description +^^^^^^^^^^^ + +This parameter models old sysklogd legacy. **Note that many people, +including the rsyslog authors, consider this to be a misfeature.** See +*Discussion* below to learn why. + +This parameter specifies whether or not repeated messages should be +reduced (this is the "Last line repeated n times" feature). If set to +*on*, repeated messages are reduced. If kept at *off*, every message is +logged. In very early versions of rsyslog, this was controlled by the +*-e* command line option. + +What is a repeated message +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For a message to be classified as repeated, the following properties +must be **identical**: + +* msg +* hostname +* procid +* appname + +Note that rate-limiters are usually applied to specific input sources +or processes. So first and foremost the input source must be the same +to classify a messages as a duplicated. + +You may want to check out +`testing rsyslog ratelimiting <http://www.rsyslog.com/first-try-to-test-rate-limiting/>`_ +for some extra information on the per-process ratelimiting. + +Discussion +^^^^^^^^^^ + +* Very old versions of rsyslog did not have the ability to include the + repeated message itself within the repeat message. + +* Versions before 7.3.2 applied repeat message reduction to the output + side. This had some implications: + + - they did not account for the actual message origin, so two processes + emitting an equally-looking message triggered the repeated message + reduction code + + - repeat message processing could be set on a per-action basis, which + has switched to per-input basis for 7.3.2 and above + +* While turning this feature on can save some space in logs, most log analysis + tools need to see the repeated messages, they can't handle the + "last message repeated" format. +* This is a feature that worked decades ago when logs were small and reviewed + by a human, it fails badly on high volume logs processed by tools. + +Sample +^^^^^^ + +This turns on repeated message reduction (**not** recommended): + +:: + + $RepeatedMsgReduction on # do not log repeated messages + |