updated doc to describe the new configuration options for forwarding

    messages

1 files changed, 75 insertions, 7 deletions

diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html
index 726ffa02..fb025b84 100644
--- a/doc/rsyslog_conf.html
+++ b/doc/rsyslog_conf.html
@@ -397,17 +397,85 @@ started.</p>
 /dev/console.</p>

 <h3>Remote Machine</h3>

 <p>Rsyslogd provides full remote logging, i.e. is able to send messages to a 

-remote host running rsyslogd(8) and to receive messages from remote hosts. The 

-remote host won't forward the message again, it will just log them locally. To 

-forward messages to another host, prepend the hostname with the at sign (``@'').<br>

-<br>

+remote host running rsyslogd(8) and to receive messages from remote hosts. 

 Using this feature you're able to control all syslog messages on one host, if 

 all other machines will log remotely to that. This tears down<br>

 administration needs.<br>

 <br>

-Please note that this version of rsyslogd by default does NOT forward messages 

-it has received from the network to another host. Specify the<br>

--h option to enable this.</p>

+<b>Please note that this version of rsyslogd by default does NOT forward messages 

+it has received from the network to another host. Specify the &quot;-h&quot; option to enable this.</b></p>

+<p>To forward messages to another host, prepend the hostname with the at sign (&quot;@&quot;).&nbsp; 

+A single at sign means that messages will be forwarded via UDP protocol (the 

+standard for syslog). If you prepend two at signs (&quot;@@&quot;), the messages will be 

+transmitted via TCP. Please note that plain TCP based syslog is not officially 

+standardized, but most major syslogds support it (e.g. syslog-ng or WinSyslog). 

+The forwarding action indicator (at-sign) can be followed by one or more options. 

+If they are given, they must be immediately (without a space) following the 

+final at sign and be enclosed in parenthesis. The individual options must be 

+separated by commas. The following options are right now defined:</p>

+<table border="1" width="100%" id="table2">

+	<tr>

+		<td>

+		<p align="center"><b>z&lt;number&gt;</b></td>

+		<td>Enable zlib-compression for the message. The &lt;number&gt; is the 

+		compression level. It can be 1 (lowest gain, lowest CPU overhead) to 9 (maximum 

+		compression, highest CPU overhead). The level can also be 0, which means 

+		&quot;no compression&quot;. If given, the &quot;z&quot; option is ignored. So this does not 

+		make an awful lot of sense. There is hardly a difference between level 1 

+		and 9 for typical syslog messages. You can expect a compression gain 

+		between 0% and 30% for typical messages. Very chatty messages may 

+		compress up to 50%, but this is seldomly seen with typicaly traffic. 

+		Please note that rsyslogd checks the compression gain. Messages with 60 

+		bytes or less will never be compressed. This is because compression gain 

+		is pretty unlikely and we prefer to save CPU cycles. Messags over that 

+		size are always compressed. However, it is checked if there is a gain in 

+		compression and only if there is, the compressed message is transmitted. 

+		Otherwise, the uncompressed messages is transmitted. This saves the 

+		receiver CPU cycles for decompression. It also prevents small message to 

+		actually become larger in compressed form.<p><b>Please note that when a 

+		TCP transport is used, compression will also turn on 

+		syslog-transport-tls framing. See the &quot;o&quot; option for important 

+		information on the implications.</b></p>

+		<p>Compressed messages are automatically detected and decompressed by 

+		the receiver. There is nothing that needs to be configured on the 

+		receiver side.</td>

+	</tr>

+	<tr>

+		<td>

+		<p align="center"><b>o</b></td>

+		<td><b>This option is experimental. Use at your own risk and only if you 

+		know why you need it! If in doubt, do NOT turn it on.</b><p>This option 

+		is only valid for plain TCP based transports. It selects a different 

+		framing based on IETF internet draft syslog-transport-tls-06. This 

+		framing offers some benefits over traditional LF-based framing. However, 

+		the standardization effort is not yet complete. There may be changes in 

+		upcoming versions of this standard. Rsyslog will be kept in line with 

+		the standard. There is some chance that upcoming changes will be 

+		incompatible to the current specification. In this case, all systems 

+		using -transport-tls framing must be upgraded. There will be no effort 

+		made to retain compatibility between different versions of rsyslog. The 

+		primary reason for that is that it seems technically impossible to 

+		provide compatibility between some of those changes. So you should take 

+		this note very serious. It is not something we do not *like* to do (and 

+		may change our mind if enough pepole beg...), it is something we most 

+		probably *can not* do for technical reasons (aka: you can beg as much as 

+		you like, it won't change anything...).</p>

+		<p>The most important implication is that compressed syslog messages via 

+		TCP must be considered with care. Unfortunately, it is technically 

+		impossible to transfer compressed records over traditional syslog plain 

+		tcp transports, so you are left with two evil choices...</td>

+	</tr>

+</table>

+<p><br>

+The hostname may be followed by a colon and the destination port.</p>

+<p>The following is an example selector line with forwarding:</p>

+<p>*.*&nbsp;&nbsp;&nbsp; @@(o,z9)192.168.0.1:1470</p>

+<p>In this example, messages are forwarded via plain TCP with experimental 

+framing and maximum compression to the host 192.168.0.1 at port 1470.</p>

+<p>*.* @192.168.0.1</p>

+<p>In the example above, messages are forwarded via UDP to the machine 

+192.168.0.1, the destination port defaults to 514. Messages will not be 

+compressed.</p>

 <h3>List of Users</h3>

 <p>Usually critical messages are also directed to ``root'' on that machine. You can 

 specify a list of users that shall get the message by simply writing the login.