this looks like 0.9.0 - even man pages are done ;)

1 files changed, 76 insertions, 0 deletions

diff --git a/rsyslog.conf.5 b/rsyslog.conf.5
index 6c91607c..0304be03 100644
--- a/rsyslog.conf.5
+++ b/rsyslog.conf.5
@@ -165,6 +165,74 @@ date-rfc3339   format as RFC 3339 date
 escape-cc      NOT yet implemented
 .fi
 
+.SH Output Channels
+.B Output Channels
+are a new concept first introduced in rsyslog 0.9.0. As of this writing, it
+is still unclear if they will stay in rsyslog or go away. 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. Output channels define the output
+defintion, only. As of this build, they can only be used to write to files - not
+pipes, ttys or whatever 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.
+
+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:
+
+*.* $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 reachead, 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 or a similar thing.
+
+.B WARNING:
+
+The current command logic is a quick hack. It simply issues the command
+via a system() call, which is very dirty. Don't make rsyslogd a suid
+binary and use action-on-max-size commands - this will mess up things.
+Fixing this is on top of the todo list and the fix will hopefully
+appear soon.
+
+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.
+
 .SH SELECTORS
 The selector field itself again consists of two parts, a
 .I facility
@@ -355,6 +423,14 @@ template name can follow the connect information. This is as follows:
 .nf
     >dbhost,dbname,dbuser,dbpassword;dbtemplate
 .fi
+
+.SS Output Channel
+Binds an output channel definition (see there for details) to this action.
+Output channel actions must start with a $-sign, e.g. if you would like
+to bind your output channel definition "mychannel" to the action, use 
+"$mychannel". Output channels support template definitions like all all other
+actions.
+
 .SH TEMPLATE NAME
 Every ACTION can be followed by a template name. If so, that template is used
 for message formatting. If no name is given, a hardcoded default template is