small fix in escapefunction, finishing touches for 1.10.1v1-10-1

1 files changed, 5 insertions, 677 deletions

diff --git a/rsyslog.conf.5 b/rsyslog.conf.5
index 6046f3d9..677a2abe 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 "12 September 2005" "Version 1.10.0 (unstable)" "Linux System Administration"
+.TH RSYSLOG.CONF 5 "23 September 2005" "Version 1.10.1" "Linux System Administration"
 .SH NAME
 rsyslog.conf \- rsyslogd(8) configuration file
 .SH DESCRIPTION
@@ -37,677 +37,11 @@ a different config file syntax, rsyslogd should be able to work with
 a standard syslog.conf file. This is especially useful while you
 are migrating from syslogd to rsyslogd.
 
-Every rule consists of two fields, a 
-.I selector
-field and an
-.I action 
-field.  These two fields are separated by one or more spaces or
-tabs.  The selector field specifies a pattern of facilities and
-priorities belonging to the specified action.
+This man page is now a stub. Full documentation can be found in
+the doc folder of the rsyslog distribution. If in doubt, you
+can also view it online at
 
-Lines starting with a hash mark (``#'') and empty lines are ignored.
-
-.SH TEMPLATES
-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 
-an escape character, much as it is 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 influenceing the
-template as whole. See details 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:
-.nf
-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.
-.fi
-
-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 to SQL injection.
-The sql option can also be useful with files - especially if you want
-to import them into a database 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 ;)
-
-.nf
-To escape:
-% = \\%
-\\ = \\\\  --> '\\' is used to escape (as in C)
-$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\\n"
-.fi
-
-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:
-
-%propname:fromChar:toChar:options%
-
-propname is the name of the property to access. This IS case-sensitive!
-Currently supported are:
-
-.nf
-msg             the MSG part of the message (aka "the message" ;))
-rawmsg          the message excactly as it was received from the
-                socket. Should be useful for debugging.
-UxTradMsg       will disappear soon - do NOT use!
-HOSTNAME        hostname from the message
-source          alias for HOSTNAME
-syslogtag       TAG from the message
-PRI             PRI part of the message - undecoded (single value)
-IUT             the monitorware InfoUnitType - used when talking
-                to a MonitorWare backend (also for phpLogCon)
-syslogfacility  the facility from the message - in numerical form
-syslogpriority  the priority (actully severity!) from the
-                message - in numerical form
-timegenerated   timestamp when the message was RECEIVED. Always in
-                high resolution
-timereported    timestamp from the message. Resolution depends on
-                what was provided in the message (in most cases,
-                only seconds)
-TIMESTAMP       alias for timereported
-.fi
-
-FromChar and toChar are used to build substrings. They specify the
-offset within the string that should be copied. Offset counting
-starts at 1, so if you need to obtain the first 2 characters of the
-message text, you can use this syntax: "%msg:1:2%".
-If you do not whish to specify from and to, but you want to
-specify options, you still need to include the colons. For example,
-if you would like to convert the full message text to lower case,
-use "%msg:::lowercase%".
-
-.nf
-property options are case-insensitive, currently defined are:
-uppercase      convert property to lowercase only
-lowercase      convert property text to uppercase only
-drop-last-lf   The last LF in the message (if any), is dropped. 
-               Especially useful for PIX.
-date-mysql     format as mysql date
-date-rfc3164   format as RFC 3164 date
-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
-and a 
-.IR priority ,
-separated by a period (``.'').
-Both parts are case insensitive and can also be specified as decimal
-numbers, but don't do that, you have been warned.  Both facilities and
-priorities are described in 
-.BR rsyslog (3).
-The names mentioned below correspond to the similar 
-.BR LOG_ -values
-in
-.IR /usr/include/rsyslog.h .
-
-The
-.I facility
-is one of the following keywords:
-.BR auth ", " authpriv ", " cron ", " daemon ", " kern ", " lpr ", "
-.BR mail ", " mark ", " news ", " security " (same as " auth "), "
-.BR rsyslog ", " user ", " uucp " and " local0 " through " local7 .
-The keyword 
-.B security
-should not be used anymore and
-.B mark
-is only for internal use and therefore should not be used in
-applications.  Anyway, you may want to specify and redirect these
-messages here.  The
-.I facility
-specifies the subsystem that produced the message, i.e. all mail
-programs log with the mail facility
-.BR "" ( LOG_MAIL )
-if they log using rsyslog.
-
-Please note that the upcoming next syslog-RFC specifies many more
-facilities. Support for them will be added in a future version of
-rsyslog, which might require changes to existing configuration files.
-
-The
-.I priority
-is one of the following keywords, in ascending order: 
-.BR debug ", " info ", " notice ", " warning ", " warn " (same as "
-.BR warning "), " err ", " error " (same as " err "), " crit ", "
-.BR alert ", " emerg ", " panic " (same as " emerg ).
-The keywords
-.BR error ", " warn " and " panic
-are deprecated and should not be used anymore.  The
-.I priority
-defines the severity of the message
-
-The behavior of the original BSD syslogd is that all messages of the
-specified priority and higher are logged according to the given
-action.  This
-.BR rsyslogd (8)
-behaves the same, but has some extensions.
-
-In addition to the above mentioned names the
-.BR rsyslogd (8)
-understands the following extensions: An asterisk (``*'') stands for
-all facilities or all priorities, depending on where it is used
-(before or after the period).  The keyword
-.B none
-stands for no priority of the given facility.
-
-You can specify multiple facilities with the same priority pattern in
-one statement using the comma (``,'') operator.  You may specify as
-much facilities as you want.  Remember that only the facility part from
-such a statement is taken, a priority part would be skipped.
-
-Multiple selectors may be specified for a single
-.I action
-using the semicolon (``;'') separator.  Remember that each selector in
-the 
-.I selector
-field is capable to overwrite the preceding ones.  Using this
-behavior you can exclude some priorities from the pattern.
-
-.BR Rsyslogd (8)
-has a syntax extension to the original BSD source, that makes its use
-more intuitively.  You may precede every priority with an equation sign
-(``='') to specify only this single priority and not any of the
-above.  You may also (both is valid, too) precede the priority with an
-exclamation mark (``!'') to ignore all that priorities, either exact
-this one or this and any higher priority.  If you use both extensions
-than the exclamation mark must occur before the equation sign, just
-use it intuitively.
-
-.SH ACTIONS
-The action field of a rule describes what to do with the message.
-In general, message content is written to a kind of "logfile". But
-also other actions might be done, like writing to a database table
-or forwarding to another host.
-
-Templates can be used with all actions. If used, the specified template
-is used to generate the message content (instead of the default
-template). To specify a template, write a semicolon after the action
-value immediately followed by the template name.
-
-.B Beware:
-templates MUST be defined BEFORE they are used. It is OK to define
-some templates, then use them in selector lines, define more templates
-and use use them in the following selector lines. But it is NOT permitted
-to use a template in a selectore line that is above its definition. If you
-do this, the selector line will be ignored.
-
-.SS Regular File
-Typically messages are logged to real files.  The file has to be
-specified with full pathname, beginning with a slash ``/''.
-
-You may prefix each entry with the minus ``-'' sign to omit syncing
-the file after every logging.  Note that you might lose information if
-the system crashes right behind a write attempt.  Nevertheless this
-might give you back some performance, especially if you run programs
-that use logging in a very verbose manner.
-
-If your system is connected to a reliable UPS and you receive lots of
-log data (e.g. firewall logs), it might be a very good idea to turn
-of syncing by specifying the "-" in front of the file name.
-
-.SS Named Pipes
-This version of
-.BR rsyslogd (8)
-has support for logging output  to
-named pipes (fifos).  A fifo or named pipe can be used as
-a destination for log messages by prepending a pipe symbol (``|'') to
-the name of the file.  This is handy for debugging.  Note that the fifo
-must be created with the  
-.BR mkfifo (1)
-command  before
-.BR rsyslogd (8)
-is started.
-
-.SS Terminal and Console
-If the file you specified is a tty, special tty-handling is done, same
-with
-.IR /dev/console .
-
-.SS Remote Machine
-.BR Rsyslogd (8)
-provides full remote logging, i.e. is able to send messages to a
-remote host running 
-.BR 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 (``@'').
-
-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
-administration needs.
-
-Please note that this version of rsyslogd by default does NOT forward messages
-it has received from the network to another host. Specify the -h
-option to enable this.
-
-.SS List of Users
-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.  You may specify more than one user by
-separating them with commas (``,'').  If they're logged in they
-get the message.  Don't think a mail would be sent, that might be too
-late.
-
-.SS Everyone logged on
-Emergency messages often go to all users currently online to notify
-them that something strange is happening with the system.  To specify
-this
-.IR wall (1)-feature
-use an asterisk (``*'').
-
-.SS Database Table
-This allows logging of the message to a database table. Currently, only
-MySQL databases are supported. By default, a MonitorWare-compatible schema
-is required for this to work. You can create that schema with the
-createDB.SQL file that came with the rsyslog package. You can also
-use any other schema of your liking - you just need to define a proper
-template and assign this template to the action.
-
-The database writer is called by specifying a greater-then sign (">")
-in front of the database connect information. Immediately after that
-sign the database host name must be given, a comma, the database name,
-another comma, the database user, a comma and then the user's password.
-If a specific template is to be used, a semicolong followed by the
-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
-used for the action.
-There can only be one template name for each given action.
-The default template is specific to each action. For a 
-description of what a template is and what you can do with it, see
-"TEMPLATES" at the top of this document.
-
-.SH EXAMPLES
-Below are example for templates and selector lines. I hope they are
-self-explanatory. If not, please see www.monitorware.com/rsyslog/ for
-advise.
-.SS TEMPLATES
-Please note that
-the samples are split across multiple lines. A template MUST NOT actually
-be split across multiple lines.
-
-A template that resambles traditional syslogd file output:
-.br
-.nf
-$template TraditionalFormat,"%timegenerated% %HOSTNAME%
-%syslogtag%%msg:::drop-last-lf%\\n"
-.fi
-
-A template that tells you a little more about the message:
-.br
-.nf
-$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,
-%syslogtag%,%msg%\\n"
-.fi
-
-A template for RFC 3164 format:
-.br
-.nf
-$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"
-.fi
-
-A template for the format traditonally used for user messages:
-.br
-.nf
-$template usermsg," XXXX%syslogtag%%msg%\\n\\r"
-.fi
-
-And a template with the traditonal wall-message format:
-.br
-.nf
-$template wallmsg,"\\r\\n\\7Message from syslogd@%HOSTNAME% at %timegenerated%
-...\\r\\n %syslogtag%%msg%\\n\\r"
-.fi
-
-A template that can be used for the database write (please note the SQL template
-option)
-.br
-.nf
-$template MySQLInsert,"insert iut, message, receivedat values
-('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')
-into systemevents\\r\\n", SQL
-.fi
-
-The following template emulates winsyslog format (it's a Adiscon format, you 
-do not feel bad if you don't know it ;)). It's interesting to see how it
-takes different parts out of the date stamps. What happens is that the date
-stamp is split into the actual date and time and the these two are combined
-with just a comma in between them.
-
-.nf
-$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,
-%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,
-%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,
-%syslogtag%%msg%\\n"
-.fi
-
-.SS SELECTOR LINES
-.IP
-.nf
-# Store critical stuff in critical
-#
-*.=crit;kern.none            /var/adm/critical
-.fi
-.LP
-This will store all messages with the priority
-.B crit
-in the file
-.IR /var/adm/critical ,
-except for any kernel message.
-
-.IP
-.nf
-# Kernel messages are first, stored in the kernel
-# file, critical messages and higher ones also go
-# to another host and to the console. Messages to
-# the host finlandia are forwarded in RFC 3164
-# format (using the template defined above).
-#
-kern.*                       /var/adm/kernel
-kern.crit                    @finlandia;RFC3164fmt
-kern.crit                    /dev/console
-kern.info;kern.!err          /var/adm/kernel-info
-.fi
-.LP
-The first rule direct any message that has the kernel facility to the
-file
-.IR /var/adm/kernel .
-
-The second statement directs all kernel messages of the priority
-.B crit
-and higher to the remote host finlandia.  This is useful, because if
-the host crashes and the disks get irreparable errors you might not be
-able to read the stored messages.  If they're on a remote host, too,
-you still can try to find out the reason for the crash.
-
-The third rule directs these messages to the actual console, so the
-person who works on the machine will get them, too.
-
-The fourth line tells the rsyslogd to save all kernel messages that
-come with priorities from
-.BR info " up to " warning
-in the file
-.IR /var/adm/kernel-info .
-Everything from
-.I err
-and higher is excluded.
-
-.IP
-.nf
-# The tcp wrapper loggs with mail.info, we display
-# all the connections on tty12
-#
-mail.=info                   /dev/tty12
-.fi
-.LP
-This directs all messages that uses 
-.BR mail.info " (in source " LOG_MAIL " | " LOG_INFO )
-to
-.IR /dev/tty12 , 
-the 12th console.  For example the tcpwrapper
-.BR tcpd (8)
-uses this as it's default.
-
-.IP
-.nf
-# Store all mail concerning stuff in a file
-#
-mail.*;mail.!=info           /var/adm/mail
-.fi
-.LP
-This pattern matches all messages that come with the
-.B mail
-facility, except for the
-.B info
-priority.  These will be stored in the file
-.IR /var/adm/mail .
-
-.IP
-.nf
-# Log all mail.info and news.info messages to info
-#
-mail,news.=info              /var/adm/info
-.fi
-.LP
-This will extract all messages that come either with
-.BR mail.info " or with " news.info 
-and store them in the file
-.IR /var/adm/info .
-
-.IP
-.nf
-# Log info and notice messages to messages file
-#
-*.=info;*.=notice;\\
-	mail.none  /var/log/messages
-.fi
-.LP
-This lets
-.B rsyslogd
-log all messages that come with either the
-.BR info " or the " notice
-facility into the file
-.IR /var/log/messages ,
-except for all messages that use the
-.B mail
-facility.
-
-.IP
-.nf
-# Log info messages to messages file
-#
-*.=info;\\
-	mail,news.none       /var/log/messages
-.fi
-.LP
-This statement causes
-.B rsyslogd
-to log all messages that come with the
-.B info
-priority to the file
-.IR /var/log/messages .
-But any message coming either with the
-.BR mail " or the " news
-facility will not be stored.
-
-.IP
-.nf
-# Emergency messages will be displayed using wall
-#
-*.=emerg                     *
-.fi
-.LP
-This rule tells the
-.B rsyslogd
-to write all emergency messages to all currently logged in users.  This
-is the wall action.
-
-.IP
-.nf
-# Messages of the priority alert will be directed
-# to the operator
-#
-*.alert                      root,rgerhards
-.fi
-.LP
-This rule directs all messages with a priority of
-.B alert
-or higher to the terminals of the operator, i.e. of the users ``root''
-and ``rgerhards'' if they're logged in.
-
-.IP
-.nf
-*.*                          @finlandia
-.fi
-.LP
-This rule would redirect all messages to a remote host called
-finlandia.  This is useful especially in a cluster of machines where
-all syslog messages will be stored on only one machine.
-
-In the format shown above, UDP is used for transmitting the message. The
-destination port is set to the default auf 514. Rsyslog is also capable of
-using much more secure and reliable TCP sessions for message forwarding.
-Also, the destination port can be specified. To select TCP, simply
-add one additional @ in front of the host name (that is, @host is UPD,
-@@host is TCP). For example:
-
-.IP
-.nf
-*.*                          @@finlandia
-.fi
-.LP
-To specify the destination port on the remote machine, use a colon followed
-by the port number after the machine name. The following forwards to port
-1514 on finlandia:
-
-.IP
-.nf
-*.*                          @@finlandia:1514
-.fi
-.LP
-This syntax works both with TCP and UDP based syslog. However, you will
-probably primarily need it for TCP, as there is no well-accepted port
-for this transport (it is non-standard). For UDP, you can usually stick
-with the default auf 514, but might want to modify it for security reasons.
-If you would like to do that, it's quite easy:
-
-.IP
-.nf
-*.*                          @finlandia:1514
-.fi
-.LP
-
-.IP
-.fi
-*.*            >dbhost,dbname,dbuser,dbpassword;dbtemplate
-.nf
-.LP
-This rule writes all message to the database "dbname" hosted on "dbhost".
-The login is done with user "dbuser" and password "dbpassword". The
-actual table that is updated is specified within the template (which
-contains the insert statement). The template is called "dbtemplate" 
-in this case.
+    http://www.rsyslog.com/doc
 
 .SH FILES
 .PD 0
@@ -726,9 +60,3 @@ The
 .B rsyslogd
 is taken from sysklogd sources, which have been heavily modified
 by Rainer Gerhards (rgerhards@adiscon.com) and others.
-
-.SH MORE INFORMATION
-The documentation has grown in size. Thus, this man page lists only the most
-important facts. The full documentation is available in html format in the doc
-folder of the rsyslog files or online at
-http://www.rsyslog.com/doc