hopefully ready for initial beta...

1 files changed, 60 insertions, 7 deletions

diff --git a/test.conf b/test.conf
index e3e04a9f..5bb935ac 100644
--- a/test.conf
+++ b/test.conf
@@ -1,22 +1,69 @@
 # 2004-11-17 rgerhards: work copy of the new syslog.conf
-# We try to keep things as consisent with existing syslog implementation
+# We try to keep things as consistent with existing syslog implementation
 # as possible. We use "$" to start lines that contain new dirctives.
 # Set syslogd options
 
-#$template Name,"Text %var% Text",<options>
+# Templates are a key feature of rsyslog. They allow to specify any
+# format a user might want. Every output in rsyslog uses templates - this
+# holds true for files, user messages and so on. The database writer
+# expects its template to be a proper SQL statement - so this is highly
+# customizable too. You might ask how does all of this work when no templates
+# at all are specified. Good question ;) The answer is simple, though. Templates
+# compatible with the stock syslogd formats are hardcoded into rsyslog. So if
+# no template is specified, we use one of these hardcoded templates. Search for
+# "template_" in syslogd.c and you will find the hardcoded ones.
+#
+# A template consists of a template directive, a name, the actual template text
+# and optional options. A sample is:
+#
+# $template MyTemplateName,"\7Text %property% some more text\n",<options>
+#
+# The "$template" is the template directive. It tells rsyslog that this
+# line contains a template.
+#
+# "MyTemplateName" is the template name. All other config lines refer to
+# this name.
+#
+# The text within quotes is the actual template text. The backslash is 
+# a escape character, much as in C. It does all these "cool" things. For
+# example, \7 rings the bell (this is an ASCII value), \n is a new line.
+# C programmers and perl coders have the advantage of knowing this, but the
+# set in rsyslog is a bit restricted currently. All text in the template
+# is used literally, except for things within percent signs. These are 
+# properties and allow you access to the contents of the syslog message.
+# Properties are accessed via the property replacer (nice name, huh) and
+# it can do cool things, too. For example, it can pick a substring or
+# do date-specific formatting. More on this is below, on some lines of the
+# property replacer.
+#
+# The <options> part is optional. It carries options that influence the
+# template as whole. Details are below. Be sure NOT to mistake template
+# options with property options - the later ones are processed by the
+# property replacer and apply to a SINGLE property, only (and not the
+# whole template).
+#
 # Template options are case-insensitive. Currently defined are:
 # sql - format the string suitable for a SQL statement. This will replace single
 #       quotes ("'") by two single quotes ("''") inside each field. This option MUST
 #       be specified when a template is used for writing to a database, otherwise SQL
-#       injection might occur. The "sql" option is only used for database-bound
-#       templates. It is ignored for all others.
-
+#       injection might occur.
+#
+# 	Please note that the database writer *checks* that the sql option is
+#	present in the template. If it is not present, the write database action
+#	is disabled. This is to guard you against accidential forgetting it and
+#	then becoming vulnerable for SQL injection.
+#	The sql option can also be useful with files - especially if you want
+#	to run them on another machine for performance reasons. However, do NOT
+#	use it if you do not have a real need for it - among others, it takes
+#	some toll on the processing time. Not much, but on a really busy system
+#	you might notice it ;)
+#
 # To escape:
 # % = \%
 # \ = \\
 # --> '\' is used to escape (as in C)
 #$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"
-
+#
 # Properties can be accessed by the property replacer. They are accessed
 # inside the template by putting them between percent signs. Properties
 # can be modifed by the property replacer. The full syntax is as follows:
@@ -63,8 +110,14 @@
 # date-rfc3339	format as RFC 3339 date
 # escape-cc	NOT yet implemented
 
+# Below find some samples of what a template can do. Have a good
+# time finding out what they do ;)
+
+# A template that resambles traditional syslogd file output:
 $template TraditionalFormat,"%timegenerated% %HOSTNAME% %syslogtag%%msg:::drop-last-lf%\n"
-$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,%syslogtag%,%msg%\n",1024
+
+# A template that tells you a little more about the message:
+ $template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,%syslogtag%,%msg%\n"
 $template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"
 #$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated::fulltime%,%HOSTNAME%,%syslogtag%,%msg%\n",1024
 $template usermsg," XXXX%syslogtag%%msg%\n\r"