added RELP doc to man pages

1 files changed, 119 insertions, 7 deletions

diff --git a/rsyslog.conf.5 b/rsyslog.conf.5
index e673e490..e15a4549 100644
--- a/rsyslog.conf.5
+++ b/rsyslog.conf.5
@@ -17,7 +17,7 @@
 .\" along with this program; if not, write to the Free Software
 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
 .\"
-.TH RSYSLOG.CONF 5 "28 March 2008" "Version 3.12.5" "Linux System Administration"
+.TH RSYSLOG.CONF 5 "04 April 2008" "Version 3.15.0" "Linux System Administration"
 .SH NAME
 rsyslog.conf \- rsyslogd(8) configuration file
 .SH DESCRIPTION
@@ -40,6 +40,94 @@ to look at the html documentation, because the man pages only cover
 basic aspects of operation.
 
 
+.SH MODULES
+
+Rsyslog has a modular design. Consequently, there is a growing number
+of modules. See the html documentation for their full description.
+
+.TP
+.I omsnmp
+SNMP trap output module
+.TP
+.I omgssapi
+Output module for GSS-enabled syslog
+.TP
+.I ommysql
+Output module for MySQL
+.TP
+.I omprelp
+Output module for the reliable RELP protocol (prevents message loss). 
+For details, see below at imrelp and the html documentation.
+It can be used like this:
+.IP
+*.*  :omrelp:server:port
+.IP
+*.*  :omrelp:192.168.0.1:2514 # actual sample
+.TP
+.I ompgsql
+Output module for PostgreSQL
+.TP
+.I omlibdbi
+Generic database output module (Firebird/Interbase, MS SQL, Sybase,
+SQLLite, Ingres, Oracle, mSQL)
+.TP
+.I imfile
+Input module for text files
+.TP
+.I imudp
+Input plugin for UDP syslog. Replaces the deprecated -r option. Can be
+used like this:
+.IP
+$ModLoad imudp
+.IP
+$InputUDPServerRun 514
+.TP
+.I imtcp
+Input plugin for plain TCP syslog. Replaces the deprecated -t
+option. Can be used like this:
+.IP
+$ModLoad imtcp
+.IP
+$InputTCPServerRun 514
+.TP
+.TP
+.I imtcp
+Input plugin for the RELP protocol. RELP can be used instead
+of UDP or plain TCP syslog to provide reliable delivery of
+syslog messages. Please note that plain TCP syslog does NOT
+provide truly reliable delivery, with it messages may be lost
+when there is a connection problem or the server shuts down.
+RELP prevents message loss in those cases.
+It can be used like this:
+.IP
+$ModLoad imrelp
+.IP
+$InputRELPServerRun 2514
+.TP
+.I imgssapi
+Input plugin for plain TCP and GSS-enable syslog
+.TP
+.I immark
+Support for mark messages
+.TP
+.I imklog
+Kernel logging. To include kernel log messages, you need to do
+.IP
+$ModLoad imklog
+
+Please note that the klogd daemon is no longer necessary and consequently
+no longer provided by the rsyslog package.
+.TP
+.I imuxsock
+Unix sockets, including the system log socket. You need to specify
+.IP
+$ModLoad imudp
+
+in order to receive log messages from local system processes. This
+config directive should only left out if you know exactly what you
+are doing.
+
+
 .SH BASIC STRUCTURE
 
 Lines starting with a hash mark ('#') and empty lines are ignored. 
@@ -82,7 +170,16 @@ beginning with a slash ('/').
 
 .B Example:
 .RS
-*.*     /var/log/traditionalfile.log;TraditionalFormat      # log to a file in the traditional format
+*.*     /var/log/traditionalfile.log;RSYSLOG_TraditionalFormat      # log to a file in the traditional format
+.RE
+
+Note: if you would like to use high-precision timestamps in your log files,
+just remove the ";RSYSLOG_TraditionalFormat". That will select the default
+template, which, if not changed, uses RFC 3339 timestamps.
+
+.B Example:
+.RS
+*.*     /var/log/file.log # log to a file with RFC3339 timestamps
 .RE
 
 .SS Named pipes
@@ -95,9 +192,14 @@ the mkfifo(1) command before rsyslogd(8) is started.
 If the file you specified is a tty, special tty-handling is done, same with /dev/console.
 
 .SS Remote machine
-To forward messages to another host, prepend the hostname with the at sign ("@").  A single at 
-sign means that messages will be forwarded via UDP protocol (the standard for syslog). If you 
-prepend two at signs ("@@"), the messages will be transmitted via TCP. 
+There are three ways to forward message: the traditional UDP transport, which is extremely
+lossy but standard, the plain TCP based transport which loses messages only during certain
+situations but is widely available and the RELP transport which does not lose messages
+but is currently available only as part of rsyslogd 3.15.0 and above.
+
+To forward messages to another host via UDP, prepend the hostname with the at sign ("@").
+To forward it via plain tcp, prepend two at signs ("@@"). To forward via RELP, prepend the
+string ":omrelp:" in front of the hostname.
 
 .B Example:
 .RS
@@ -105,7 +207,18 @@ prepend two at signs ("@@"), the messages will be transmitted via TCP.
 .RE
 .sp
 In the example above, messages are forwarded via UDP to the machine 192.168.0.1, the destination 
-port defaults to 514. 
+port defaults to 514. Due to the nature of UDP, you will probably lose some messages in transit.
+If you expect high traffic volume, you can expect to lose a quite noticable number of messages
+(the higher the traffic, the more likely and severe is message loss).
+
+.B If you would like to prevent message loss, use RELP:
+.RS
+*.* :omrelp:192.168.0.1:2514
+.RE
+.sp
+Note that a port number was given as there is no standard port for relp.
+
+Keep in mind that you need to load the correct input and output plugins (see "Modules" above).
 
 Please note that rsyslogd offers a variety of options in regarding to remote
 forwarding. For full details, please see the html documentation.
@@ -610,7 +723,6 @@ the html documentation for all features and details. This is especially vital if
 up a more-then-extremely-simple system.
 
 .SH AUTHORS
-The
 .B rsyslogd
 is taken from sysklogd sources, which have been heavily modified
 by Rainer Gerhards (rgerhards@adiscon.com) and others.