Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 61 insertions, 0 deletions

diff --git a/source/configuration/output_channels.rst b/source/configuration/output_channels.rst
new file mode 100644
index 0000000..24e26c7
--- /dev/null
+++ b/source/configuration/output_channels.rst
@@ -0,0 +1,61 @@
+Output Channels
+---------------
+
+Output Channels are a new concept first introduced in rsyslog 0.9.0.
+**As of this writing, it is most likely that they will be replaced by
+something different in the future.** So if you use them, be prepared to
+change you configuration file syntax when you upgrade to a later
+release.
+The idea behind output channel definitions is that it shall provide an
+umbrella for any type of output that the user might want. In essence,
+this is the "file" part of selector lines (and this is why we are not
+sure output channel syntax will stay after the next review). There is a
+difference, though: selector channels both have filter conditions
+(currently facility and severity) as well as the output destination.
+they can only be used to write to files - not pipes, ttys or whatever
+Output channels define the output definition, only. As of this build,
+else. If we stick with output channels, this will change over time.
+
+In concept, an output channel includes everything needed to know about
+an output actions. In practice, the current implementation only carries
+a filename, a maximum file size and a command to be issued when this
+file size is reached. More things might be present in future version,
+which might also change the syntax of the directive.
+
+Output channels are defined via an $outchannel directive. It's syntax is
+as follows:
+$outchannel name,file-name,max-size,action-on-max-size
+name is the name of the output channel (not the file), file-name is the
+file name to be written to, max-size the maximum allowed size and
+action-on-max-size a command to be issued when the max size is reached.
+This command always has exactly one parameter. The binary is that part
+of action-on-max-size before the first space, its parameter is
+everything behind that space.
+Please note that max-size is queried BEFORE writing the log message to
+the file. So be sure to set this limit reasonably low so that any
+message might fit. For the current release, setting it 1k lower than you
+expected is helpful. The max-size must always be specified in bytes -
+there are no special symbols (like 1k, 1m,...) at this point of
+development.
+Keep in mind that $outchannel just defines a channel with "name". It
+does not activate it. To do so, you must use a selector line (see
+below). That selector line includes the channel name plus an $ sign in
+front of it. A sample might be:
+\*.\* :omfile:$mychannel
+In its current form, output channels primarily provide the ability to
+size-limit an output file. To do so, specify a maximum size. When this
+size is reached, rsyslogd will execute the action-on-max-size command
+and then reopen the file and retry. The command should be something like
+a `log rotation script <log_rotation_fix_size.html>`_ or a similar
+thing.
+
+If there is no action-on-max-size command or the command did not resolve
+the situation, the file is closed and never reopened by rsyslogd
+(except, of course, by huping it). This logic was integrated when we
+first experienced severe issues with files larger 2gb, which could lead
+to rsyslogd dumping core. In such cases, it is more appropriate to stop
+writing to a single file. Meanwhile, rsyslogd has been fixed to support
+files larger 2gb, but obviously only on file systems and operating
+system versions that do so. So it can still make sense to enforce a 2gb
+file size limit.
+