doc: update module doc to new config format

1 files changed, 140 insertions, 50 deletions

diff --git a/doc/imuxsock.html b/doc/imuxsock.html
index 19f9cf51..bd207a37 100644
--- a/doc/imuxsock.html
+++ b/doc/imuxsock.html
@@ -24,11 +24,11 @@ information). This seems to be consistent with what sysklogd did for
 the past four years. Alternate behaviour may be desirable if
 gateway-like processes send messages via the local log slot - in this
 case, it can be enabled via the
-$InputUnixListenSocketIgnoreMsgTimestamp and $SystemLogSocketIgnoreMsgTimestamp config directives</p>
+IgnoreTimestamp and SysSock.IgnoreTimestamp config directives</p>
 <p><b>There is input rate limiting available,</b> (since 5.7.1) to guard you against
 the problems of a wild running logging process. 
-If more than $SystemLogRateLimitInterval * $SystemLogRateLimitBurst log messages are emitted
-from the same process, those messages with $SystemLogRateLimitSeverity or lower will be
+If more than SysSock.RateLimit.Interval * SysSock.RateLimit.Burst log messages are emitted
+from the same process, those messages with SysSock.RateLimit.Severity or lower will be
 dropped. It is not possible to recover anything about these messages, but imuxsock will
 tell you how many it has dropped one the interval has expired AND the next message
 is logged. Rate-limiting depends on SCM_CREDENTIALS. If the platform does not support
@@ -36,7 +36,7 @@ this socket option, rate limiting is turned off. If multiple sockets are configu
 rate limiting works independently on each of them (that should be what you usually expect).
 The same functionality is available for additional log sockets, in which case the
 config statements just use 
-the prefix $IMUXSockRateLimit... but otherwise works exactly the same.
+the prefix RateLimit... but otherwise works exactly the same.
 When working with severities, please keep in mind that higher severity numbers mean lower
 severity and configure things accordingly.
 To turn off rate limiting, set the interval to zero.
@@ -46,8 +46,8 @@ the queues (which may cause exessive disk-io where it actually would not be need
 flow-controlling a log socket (and especially the system log socket) can lead to a very
 unresponsive system. As such, flow control is disabled by default. That means any log records
 are places as quickly as possible into the processing queues. If you would like to have
-flow control, you need to enable it via the $SystemLogSocketFlowControl and
-$InputUnixListenSocketFlowControl config directives. Just make sure you thought about
+flow control, you need to enable it via the SysSock.FlowControl and
+FlowControl config directives. Just make sure you thought about
 the implications. Note that for many systems, turning on flow control does not hurt.
 <p>Starting with rsyslog 5.9.4,
 <b><a href="http://www.rsyslog.com/what-are-trusted-properties/">trusted syslog properties</a>
@@ -57,87 +57,177 @@ privileges are dropped (depending on how they are dropped). Note that trusted pr
 can be very useful, but also typically cause the message to grow rather large. Also, the
 format of log messages is obviously changed by adding the trusted properties at the end.
 For these reasons, the feature is <b>not enabled by default</b>. If you want to use it,
-you must turn it on (via $SystemLogSocketAnnotate and $InputUnixListenSocketAnnotate).
+you must turn it on (via SysSock.Annotate and Annotate).
+
 <p><b>Configuration Directives</b>:</p>
+<p><b>Global Parameters</b></p>
 <ul>
-<li><b>$InputUnixListenSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]
+<li><b>SysSock.IgnoreTimestamp</b> [<b>on</b>/off]<br>
+Ignore timestamps included in the messages, applies to messages received via the system log socket.
+</li>
+<li><b>SysSock.Use</b> (imuxsock) [on/<b>off</b>] 
+do NOT listen for the local log socket. This is most useful if you run multiple
+instances of rsyslogd where only one shall handle the system log socket.
+</li>
+<li><b>SysSock.Name</b> &lt;name-of-socket&gt; 
+</li>
+<li><b>SysSock.FlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
+to the system log socket.
+</li>
+<li><b>SysSock.UsePIDFromSystem</b> [on/<b>off</b>] - specifies if the pid being logged shall
+be obtained from the log socket itself. If so, the TAG part of the message is rewritten.
+It is recommended to turn this option on, but the default is "off" to keep compatible
+with earlier versions of rsyslog. This option was introduced in 5.7.0.
+</li>
+<li><b>SysSock.RateLimit.Interval</b> [number] - specifies the rate-limiting
+interval in seconds.  Default value is 5 seconds. Set it to 0 to turn rate limiting off.
+</li>
+<li><b>SysSock.RateLimit.Burst</b> [number] - specifies the rate-limiting
+burst in number of messages. Default is 200.
+</li>
+<li><b>SysSock.RateLimit.Severity</b> [numerical severity] - specifies the severity of
+messages that shall be rate-limited.
+</li>
+<li><b>SysSock.UseSysTimeStamp</b> [<b>on</b>/off] the same as $InputUnixListenSocketUseSysTimeStamp, but for the system log socket.
+</li>
+<li><b>SysSock.Annotate</b> &lt;on/<b>off</b>&gt; turn on annotation/trusted
+properties for the system log socket.</li>
+</ul>
+
+<p><b>Input Instance Parameters</b></p>
+<ul>
+<li><b>IgnoreTimestamp</b> [<b>on</b>/off]
 <br>Ignore timestamps included in the message. Applies to the next socket being added.</li>
-<li><b>$InputUnixListenSocketFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
+<li><b>FlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
 to the next socket.</li>
-<li><b>$IMUXSockRateLimitInterval</b> [number] - specifies the rate-limiting
+<li><b>RateLimit.Interval</b> [number] - specifies the rate-limiting
 interval in seconds.  Default value is 0, which turns off rate limiting. Set it to a number
 of seconds (5 recommended) to activate rate-limiting. The default of 0 has been choosen in 5.9.6+,
 as people experienced problems with this feature activated by default. Now it needs an
 explicit opt-in by setting this parameter.
 </li>
-<li><b>$IMUXSockRateLimitBurst</b> [number] - specifies the rate-limiting
+<li><b>RateLimit.Burst</b> [number] - specifies the rate-limiting
 burst in number of messages. Default is 200.
 </li>
-<li><b>$IMUXSockRateLimitSeverity</b> [numerical severity] - specifies the severity of
+<li><b>RateLimit.Severity</b> [numerical severity] - specifies the severity of
 messages that shall be rate-limited.
 </li>
-<li><b>$IMUXSockLocalIPIF</b> [interface name] - (available since 5.9.6) - if provided, the IP of the specified
+<!--<li><b>LocalIPIF</b> [interface name] - (available since 5.9.6) - if provided, the IP of the specified
 interface (e.g. "eth0") shall be used as fromhost-ip for imuxsock-originating messages.
 If this directive is not given OR the interface cannot be found (or has no IP address),
 the default of "127.0.0.1" is used.
-</li>
-<li><b>$InputUnixListenSocketUsePIDFromSystem</b> [on/<b>off</b>] - specifies if the pid being logged shall
+</li>-->
+<li><b>UsePIDFromSystem</b> [on/<b>off</b>] - specifies if the pid being logged shall
 be obtained from the log socket itself. If so, the TAG part of the message is rewritten.
 It is recommended to turn this option on, but the default is "off" to keep compatible
 with earlier versions of rsyslog. This option was introduced in 5.7.0.</li>
-<li><b>$InputUnixListenSocketUseSysTimeStamp</b> [<b>on</b>/off] instructs imuxsock
+<li><b>UseSysTimeStamp</b> [<b>on</b>/off] instructs imuxsock
 to obtain message time from the system (via control messages) insted of using time
 recorded inside the message. This may be most useful in combination with systemd. Note:
 this option was introduced with version 5.9.1. Due to the usefulness of it, we
 decided to enable it by default. As such, 5.9.1 and above behave slightly different
 than previous versions. However, we do not see how this could negatively affect
 existing environments.<br>
-<li><b>$SystemLogSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]<br>
-Ignore timestamps included in the messages, applies to messages received via the system log socket.</li>
-<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] -- former -o option;
-do NOT listen for the local log socket. This is most useful if you run multiple
-instances of rsyslogd where only one shall handle the system log socket.</li>
-<li><b>$SystemLogSocketName</b> &lt;name-of-socket&gt; -- former -p option</li>
-<li><b>$SystemLogFlowControl</b> [on/<b>off</b>] - specifies if flow control should be applied
-to the system log socket.</li>
-<li><b>$SystemLogUsePIDFromSystem</b> [on/<b>off</b>] - specifies if the pid being logged shall
-be obtained from the log socket itself. If so, the TAG part of the message is rewritten.
-It is recommended to turn this option on, but the default is "off" to keep compatible
-with earlier versions of rsyslog. This option was introduced in 5.7.0.</li>
-<li><b>$SystemLogParseTrusted</b> [on/<b>off</b>] - specifies if Trusted Properties shall be parsed
-and saved into libee event structure. This option needs $SystemLogSocketAnnotate to be on.</li>
-<li><b>$SystemLogRateLimitInterval</b> [number] - specifies the rate-limiting
-interval in seconds.  Default value is 5 seconds. Set it to 0 to turn rate limiting off.
-</li>
-<li><b>$SystemLogRateLimitBurst</b> [number] - specifies the rate-limiting
-burst in number of messages. Default is 200.
-</li>
-<li><b>$SystemLogRateLimitSeverity</b> [numerical severity] - specifies the severity of
-messages that shall be rate-limited.
-</li>
-<li><b>$SystemLogUseSysTimeStamp</b> [<b>on</b>/off] the same as $InputUnixListenSocketUseSysTimeStamp, but for the system log socket.
-<li><b>$InputUnixListenSocketCreatePath</b> [on/<b>off</b>] - create directories in the socket path
+<li><b>CreatePath</b> [on/<b>off</b>] - create directories in the socket path
 if they do not already exist. They are created with 0755 permissions with the owner being the process under
 which rsyslogd runs. The default is not to create directories. Keep in mind, though, that rsyslogd always
 creates the socket itself if it does not exist (just not the directories by default).
 <br>Note that this statement affects the
-next $AddUnixListenSocket directive that follows in sequence in the configuration file. It never works
+next Socket directive that follows in sequence in the configuration file. It never works
 on the system log socket (where it is deemed unnecessary). Also note that it is automatically 
-being reset to &quot;off&quot; after the $AddUnixListenSocket directive, so if you would have it active
+being reset to &quot;off&quot; after the Socket directive, so if you would have it active
 for two additional listen sockets, you need to specify it in front of each one. This option is primarily considered
 useful for defining additional sockets that reside on non-permanent file systems. As rsyslogd probably starts
 up before the daemons that create these sockets, it is a vehicle to enable rsyslogd to listen to those
 sockets even though their directories do not yet exist. [available since 4.7.0 and 5.3.0]</li>
-<li><b>$AddUnixListenSocket</b> &lt;name-of-socket&gt; adds additional unix socket, default none -- former -a option</li>
-<li><b>$InputUnixListenSocketHostName</b> &lt;hostname&gt; permits to override the hostname that
-shall be used inside messages taken from the <b>next</b> $AddUnixListenSocket socket. Note that
+<li><b>Socket</b> &lt;name-of-socket&gt; adds additional unix socket, default none -- former -a option</li>
+<li><b>HostName</b> &lt;hostname&gt; permits to override the hostname that
+shall be used inside messages taken from the <b>next</b> Socket socket. Note that
 the hostname must be specified before the $AddUnixListenSocket configuration directive, and it
 will only affect the next one and then automatically be reset. This functionality is provided so
 that the local hostname can be overridden in cases where that is desired.</li>
-<li><b>$InputUnixListenSocketAnnotate</b> &lt;on/<b>off</b>&gt; turn on annotation/trusted
+<li><b>Annotate</b> &lt;on/<b>off</b>&gt; turn on annotation/trusted
 properties for the non-system log socket in question.</li>
-<li><b>$SystemLogSocketAnnotate</b> &lt;on/<b>off</b>&gt; turn on annotation/trusted
-properties for the system log socket.</li>
+</ul>
+
+<b>Caveats/Known Bugs:</b><br>
+<ul>
+<li>There is a compile-time limit of 50 concurrent sockets. If you need more, you need to
+change the array size in imuxsock.c.
+<li>This documentation is sparse and incomplete.
+</ul>
+<p><b>Sample:</b></p>
+<p>The following sample is the minimum setup required to accept syslog messages from applications running
+on the local system.<br>
+</p>
+<textarea rows="2" cols="70">module(load="/folder/to/rsyslog/plugins/imuxsock/.libs/imuxsock" # needs to be done just once
+SysSock.FlowControl="on") # enable flow control (use if needed)
+</textarea>
+<p>The following sample is a configuration where rsyslogd pulls logs from two
+jails, and assigns different hostnames to each of the jails: </p>
+<textarea rows="6" cols="70">module(load="/folder/to/rsyslog/plugins/imuxsock/.libs/imuxsock") # needs to be done just once
+
+input(type="imuxsock" HostName="jail1.example.net" Socket="/jail/1/dev/log")
+input(type="imuxsock" HostName="jail2.example.net" Socket="/jail/2/dev/log")
+</textarea>
+<p>The following sample is a configuration where rsyslogd reads the openssh log
+messages via a separate socket, but this socket is created on a temporary file
+system. As rsyslogd starts up before the sshd, it needs to create the socket
+directories, because it otherwise can not open the socket and thus not listen
+to openssh messages. Note that it is vital not to place any other socket between
+the CreatePath and the Socket.</p>
+<textarea rows="6" cols="70">module(load="/folder/to/rsyslog/plugins/imuxsock/.libs/imuxsock") # needs to be done just once
+
+input(type="imuxsock" Socket="/var/run/sshd/dev/log" CreatePath="on")
+</textarea>
+<p>The following sample is used to turn off input rate limiting on the system log
+socket.
+<textarea rows="4" cols="70">module(load="/folder/to/rsyslog/plugins/imuxsock/.libs/imuxsock" # needs to be done just once
+SysSock.RateLimit.Interval="0") # turn off rate limiting
+</textarea>
+<p>The following sample is used activate message annotation and thus trusted properties
+on the system log socket.
+<textarea rows="4" cols="70">module(load="/folder/to/rsyslog/plugins/imuxsock/.libs/imuxsock" # needs to be done just once
+SysSock.Annotate="on")
+</textarea>
+
+
+<p><b>Legacy Configuration Directives</b>:</p>
+<ul>
+<li><b>$InputUnixListenSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]
+<br>Please see: IgnoreTimestamp.</li>
+<li><b>$InputUnixListenSocketFlowControl</b> [on/<b>off</b>] - Please see: FlowControl .</li>
+<li><b>$IMUXSockRateLimitInterval</b> [number] - Please see: RateLimit.Interval
+</li>
+<li><b>$IMUXSockRateLimitBurst</b> [number] - Please see: RateLimit.Burst
+</li>
+<li><b>$IMUXSockRateLimitSeverity</b> [numerical severity] - Please see: RateLimit.Severity
+</li>
+<li><b>$IMUXSockLocalIPIF</b> [interface name] - (available since 5.9.6) - if provided, the IP of the specified
+interface (e.g. "eth0") shall be used as fromhost-ip for imuxsock-originating messages.
+If this directive is not given OR the interface cannot be found (or has no IP address),
+the default of "127.0.0.1" is used.
+</li>
+<li><b>$InputUnixListenSocketUsePIDFromSystem</b> [on/<b>off</b>] - Please see: UsePIDFromSystem.</li>
+<li><b>$InputUnixListenSocketUseSysTimeStamp</b> [<b>on</b>/off] Please see: UseSysTimeStamp .<br>
+<li><b>$SystemLogSocketIgnoreMsgTimestamp</b> [<b>on</b>/off]<br>
+Please see: SysSock.IgnoreTimestamp.</li>
+<li><b>$OmitLocalLogging</b> (imuxsock) [on/<b>off</b>] Please see: SysSock.Use</li>
+<li><b>$SystemLogSocketName</b> &lt;name-of-socket&gt; Please see: SysSock.Name</li>
+<li><b>$SystemLogFlowControl</b> [on/<b>off</b>] - Please see: SysSock.FlowControl.</li>
+<li><b>$SystemLogUsePIDFromSystem</b> [on/<b>off</b>] - Please see: SysSock.UsePIDFromSystem.</li>
+<li><b>$SystemLogRateLimitInterval</b> [number] - Please see: SysSock.RateLimit.Interval.
+</li>
+<li><b>$SystemLogRateLimitBurst</b> [number] - Please see: SysSock.RateLimit.Burst
+</li>
+<li><b>$SystemLogRateLimitSeverity</b> [numerical severity] - Please see: SysSock.RateLimit.Severity
+</li>
+<li><b>$SystemLogUseSysTimeStamp</b> [<b>on</b>/off] Please see: SysSock.UseSysTimeStamp.
+<li><b>$InputUnixListenSocketCreatePath</b> [on/<b>off</b>] - Please see: CreatePath</li>
+<li><b>$AddUnixListenSocket</b> &lt;name-of-socket&gt; Please see: Socket </li>
+<li><b>$InputUnixListenSocketHostName</b> &lt;hostname&gt; Please see: HostName.</li>
+<li><b>$InputUnixListenSocketAnnotate</b> &lt;on/<b>off</b>&gt; Please see: Annotate.</li>
+<li><b>$SystemLogSocketAnnotate</b> &lt;on/<b>off</b>&gt; Please see: SysSock.Annotate.</li>
 </ul>
 
 <b>Caveats/Known Bugs:</b><br>
@@ -171,7 +261,7 @@ the $InputUnixListenSocketCreatePath and the $InputUnixListenSocketHostName.</p>
 <textarea rows="6" cols="70">$ModLoad imuxsock # needs to be done just once
 
 $InputUnixListenSocketCreatePath on # turn on for *next* socket
-$InputUnixListenSocketHostName /var/run/sshd/dev/log
+$InputUnixListenSocket /var/run/sshd/dev/log
 </textarea>
 <p>The following sample is used to turn off input rate limiting on the system log
 socket.