From 170d0d6f375241e0d0ca85a1327df82165fec439 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Tue, 11 Nov 2008 11:00:37 +0100 Subject: added forgotten files they were new after restructuring the doc... --- doc/Makefile.am | 7 + doc/rsyslog_conf_actions.html | 336 ++++++++++++++++++++++++++++++++++++++++ doc/rsyslog_conf_examples.html | 209 +++++++++++++++++++++++++ doc/rsyslog_conf_filter.html | 280 +++++++++++++++++++++++++++++++++ doc/rsyslog_conf_global.html | 227 +++++++++++++++++++++++++++ doc/rsyslog_conf_modules.html | 53 +++++++ doc/rsyslog_conf_output.html | 81 ++++++++++ doc/rsyslog_conf_templates.html | 150 ++++++++++++++++++ 8 files changed, 1343 insertions(+) create mode 100644 doc/rsyslog_conf_actions.html create mode 100644 doc/rsyslog_conf_examples.html create mode 100644 doc/rsyslog_conf_filter.html create mode 100644 doc/rsyslog_conf_global.html create mode 100644 doc/rsyslog_conf_modules.html create mode 100644 doc/rsyslog_conf_output.html create mode 100644 doc/rsyslog_conf_templates.html diff --git a/doc/Makefile.am b/doc/Makefile.am index 22d368e0..fef1e44c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -98,6 +98,13 @@ html_files = \ omrelp.html \ status.html \ troubleshoot.html \ + rsyslog_conf_actions.html \ + rsyslog_conf_examples.html \ + rsyslog_conf_filter.html \ + rsyslog_conf_global.html \ + rsyslog_conf_modules.html \ + rsyslog_conf_output.html \ + rsyslog_conf_templates.html \ src/classes.dia EXTRA_DIST = $(html_files) diff --git a/doc/rsyslog_conf_actions.html b/doc/rsyslog_conf_actions.html new file mode 100644 index 00000000..2ef3f4b0 --- /dev/null +++ b/doc/rsyslog_conf_actions.html @@ -0,0 +1,336 @@ + +Actions - rsyslog.conf + +

This is a part of the rsyslog.conf documentation.

+back +

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.
+
+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 selector line that is above its +definition. If you do this, the action will be ignored.

+

You can have multiple actions for a single selector  (or +more precisely a single filter of such a selector line). Each action +must be on its own line and the line must start with an ampersand +('&') character and have no filters. An example would be

+

*.=crit rger
+& root
+& /var/log/critmsgs

+

These three lines send critical messages to the user rger and +root and also store them in /var/log/critmsgs. Using multiple +actions per selector is convenient and also offers +a performance benefit. As the filter needs to be evaluated +only once, there is less computation required to process the directive +compared to the otherwise-equal config directives below:

+

*.=crit rger
+*.=crit root
+*.=crit /var/log/critmsgs

+

 

+

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.

+

The filename can be either static (always +the same) or dynamic (different based on message +received). The later is useful if you would automatically split +messages into different files based on some message criteria. For +example, dynamic file name selectors allow you to split messages into +different files based on the host that sent them. With dynamic file +names, everything is automatic and you do not need any filters.

+

It works via the template system. First, you define a template +for the file name. An example can be seen above in the description of +template. We will use the "DynFile" template defined there. Dynamic +filenames are indicated by specifying a questions mark "?" instead of a +slash, followed by the template name. Thus, the selector line for our +dynamic file name would look as follows:

+
+*.* ?DynFile +
+

That's all you need to do. Rsyslog will now automatically +generate file names for you and store the right messages into the right +files. Please note that the minus sign also works with dynamic file +name selectors. Thus, to avoid syncing, you may use

+
+*.* -?DynFile
+

And of course you can use templates to specify the output +format:

+
+*.* ?DynFile;MyTemplate
+

A word of caution: rsyslog creates files as +needed. So if a new host is using your syslog server, rsyslog will +automatically create a new file for it.

+

Creating directories is also supported. For +example you can use the hostname as directory and the program name as +file name:

+
+$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"
+

Named Pipes

+

This version of 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 mkfifo(1) command before rsyslogd(8) is started.

+

Terminal and Console

+

If the file you specified is a tty, special tty-handling is +done, same with /dev/console.

+

Remote Machine

+

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. 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.

+

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. 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:

+ + + + + + + + + + + +
+

z<number>

+		Enable zlib-compression for the message. The +<number> 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 "no compression". If +given, the "z" 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 seldom seen with typically 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. Messages 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. +

Please note that when a TCP transport is used, +compression will also turn on syslog-transport-tls framing. See the "o" +option for important information on the implications.

+

Compressed messages are automatically detected and +decompressed by the receiver. There is nothing that needs to be +configured on the receiver side.

+
+

o

+		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. +

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 +people 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...).

+

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...

+
+


+The hostname may be followed by a colon and the destination port.

+

The following is an example selector line with forwarding:

+

*.*    @@(o,z9)192.168.0.1:1470

+

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.

+

*.* @192.168.0.1

+

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.

+

Note that IPv6 addresses contain colons. So if an IPv6 address is specified +in the hostname part, rsyslogd could not detect where the IP address ends +and where the port starts. There is a syntax extension to support this: +put squary brackets around the address (e.g. "[2001::1]"). Square +brackets also work with real host names and IPv4 addresses, too. +

A valid sample to send messages to the IPv6 host 2001::1 at port 515 +is as follows: +

*.* @[2001::1]:515 +

This works with TCP, too. +

Note to sysklogd users: sysklogd does not +support RFC 3164 format, which is the default forwarding template in +rsyslog. As such, you will experience duplicate hostnames if rsyslog is +the sender and sysklogd is the receiver. The fix is simple: you need to +use a different template. Use that one:

+

$template +sysklogd,"<%PRI%>%TIMESTAMP% %syslogtag%%msg%\""
+*.* @192.168.0.1;sysklogd

+

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.

+

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 wall(1)-feature use an asterisk ("*'').

+

Call Plugin

+

This is a generic way to call an output plugin. The plugin +must support this functionality. Actual parameters depend on the +module, so see the module's doc on what to supply. The general syntax +is as follows:

+

:modname:params;template

+

Currently, the ommysql database output module supports this +syntax (in addtion to the ">" syntax it traditionally +supported). For ommysql, the module name is "ommysql" and the params +are the traditional ones. The ;template part is not module specific, it +is generic rsyslog functionality available to all modules.

+

As an example, the ommysql module may be called as follows:

+

:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate

+

For details, please see the "Database Table" section of this +documentation.

+

Note: as of this writing, the ":modname:" part is hardcoded +into the module. So the name to use is not necessarily the name the +module's plugin file is called.

+

Database Table

+

This allows logging of the message to a database table. +Currently, only MySQL databases are supported. However, other database +drivers will most probably be developed as plugins. 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 semicolon followed by the +template name can follow the connect information. This is as follows:
+
+>dbhost,dbname,dbuser,dbpassword;dbtemplate

+

Important: to use the database functionality, the +MySQL output module must be loaded in the config file BEFORE +the first database table action is used. This is done by placing the

+

$ModLoad ommysql

+

directive some place above the first use of the database write +(we recommend doing at the the beginning of the config file).

+

Discard

+

If the discard action is carried out, the received message is +immediately discarded. No further processing of it occurs. Discard has +primarily been added to filter out messages before carrying on any +further processing. For obvious reasons, the results of "discard" are +depending on where in the configuration file it is being used. Please +note that once a message has been discarded there is no way to retrieve +it in later configuration file lines.

+

Discard can be highly effective if you want to filter out some +annoying messages that otherwise would fill your log files. To do that, +place the discard actions early in your log files. This often plays +well with property-based filters, giving you great freedom in +specifying what you do not want.

+

Discard is just the single tilde character with no further +parameters:

+

~

+

For example,

+

*.*   ~

+

discards everything (ok, you can achive the same by not +running rsyslogd at all...).

+

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.

+

Shell Execute

+

This executes a program in a subshell. The program is passed +the template-generated message as the only command line parameter. +Rsyslog waits until the program terminates and only then continues to +run.

+

^program-to-execute;template

+

The program-to-execute can be any valid executable. It +receives the template string as a single parameter (argv[1]).

+

WARNING: The Shell Execute action was added +to serve an urgent need. While it is considered reasonable save when +used with some thinking, its implications must be considered. The +current implementation uses a system() call to execute the command. +This is not the best way to do it (and will hopefully changed in +further releases). Also, proper escaping of special characters is done +to prevent command injection. However, attackers always find smart ways +to circumvent escaping, so we can not say if the escaping applied will +really safe you from all hassles. Lastly, rsyslog will wait until the +shell command terminates. Thus, a program error in it (e.g. an infinite +loop) can actually disable rsyslog. Even without that, during the +programs run-time no messages are processed by rsyslog. As the IP +stacks buffers are quickly overflowed, this bears an increased risk of +message loss. You must be aware of these implications. Even though they +are severe, there are several cases where the "shell execute" action is +very useful. This is the reason why we have included it in its current +form. To mitigate its risks, always a) test your program thoroughly, b) +make sure its runtime is as short as possible (if it requires a longer +run-time, you might want to spawn your own sub-shell asynchronously), +c) apply proper firewalling so that only known senders can send syslog +messages to rsyslog. Point c) is especially important: if rsyslog is +accepting message from any hosts, chances are much higher that an +attacker might try to exploit the "shell execute" action.

+

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 +hard-coded 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.

+ + +

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + diff --git a/doc/rsyslog_conf_examples.html b/doc/rsyslog_conf_examples.html new file mode 100644 index 00000000..b46460e5 --- /dev/null +++ b/doc/rsyslog_conf_examples.html @@ -0,0 +1,209 @@ + +Examples - rsyslog.conf + +

This is a part of the rsyslog.conf documentation.

+back +

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.

+

TEMPLATES

+

Please note that the samples are split across multiple lines. +A template MUST NOT actually be split across multiple lines.
+
+A template that resembles traditional syslogd file output:
+$template TraditionalFormat,"%timegenerated% %HOSTNAME%
+%syslogtag%%msg:::drop-last-lf%\n"
+
+A template that tells you a little more about the message:
+$template +precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,
+%syslogtag%,%msg%\n"
+
+A template for RFC 3164 format:
+$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% +%syslogtag%%msg%"
+
+A template for the format traditonally used for user messages:
+$template usermsg," XXXX%syslogtag%%msg%\n\r"
+
+And a template with the traditonal wall-message format:
+$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at +%timegenerated%
+
+A template that can be used for the database write (please note the SQL
+template option)
+$template MySQLInsert,"insert iut, message, receivedat values
+('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')
+into systemevents\r\n", SQL
+
+The following template emulates WinSyslog +format (it's an 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.
+
+$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"

+

SELECTOR LINES

+

# Store critical stuff in critical
+#
+*.=crit;kern.none /var/adm/critical
+
+This will store all messages with the priority crit in the file +/var/adm/critical, except for any kernel message.
+
+
+# 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
+
+The first rule direct any message that has the kernel facility to the +file /var/adm/kernel.
+
+The second statement directs all kernel messages of the priority 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 rsyslogd to save all kernel messages that come +with priorities from info up to warning in the file +/var/adm/kernel-info. Everything from err and higher is excluded.
+
+
+# The tcp wrapper loggs with mail.info, we display
+# all the connections on tty12
+#
+mail.=info /dev/tty12
+
+This directs all messages that uses mail.info (in source LOG_MAIL | +LOG_INFO) to /dev/tty12, the 12th console. For example the tcpwrapper +tcpd(8) uses this as it's default.
+
+
+# Store all mail concerning stuff in a file
+#
+mail.*;mail.!=info /var/adm/mail
+
+This pattern matches all messages that come with the mail facility, +except for the info priority. These will be stored in the file +/var/adm/mail.
+
+
+# Log all mail.info and news.info messages to info
+#
+mail,news.=info /var/adm/info
+
+This will extract all messages that come either with mail.info or with +news.info and store them in the file /var/adm/info.
+
+
+# Log info and notice messages to messages file
+#
+*.=info;*.=notice;\
+mail.none /var/log/messages
+
+This lets rsyslogd log all messages that come with either the info or +the notice facility into the file /var/log/messages, except for all
+messages that use the mail facility.
+
+
+# Log info messages to messages file
+#
+*.=info;\
+mail,news.none /var/log/messages
+
+This statement causes rsyslogd to log all messages that come with the +info priority to the file /var/log/messages. But any message coming +either with the mail or the news facility will not be stored.
+
+
+# Emergency messages will be displayed using wall
+#
+*.=emerg *
+
+This rule tells rsyslogd to write all emergency messages to all +currently logged in users. This is the wall action.
+
+
+# Messages of the priority alert will be directed
+# to the operator
+#
+*.alert root,rgerhards
+
+This rule directs all messages with a priority of alert or higher to +the terminals of the operator, i.e. of the users "root'' and +"rgerhards'' if they're logged in.
+
+
+*.* @finlandia
+
+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:
+
+
+*.* @@finlandia
+
+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:
+
+
+*.* @@finlandia:1514
+
+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 rea-
+sons. If you would like to do that, it's quite easy:
+
+
+*.* @finlandia:1514
+
+
+
+*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate
+
+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.

+

:msg,contains,"error" @errorServer

+

This rule forwards all messages that contain the word "error" +in the msg part to the server "errorServer". Forwarding is via UDP. +Please note the colon in fron

+ +

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + diff --git a/doc/rsyslog_conf_filter.html b/doc/rsyslog_conf_filter.html new file mode 100644 index 00000000..55244c15 --- /dev/null +++ b/doc/rsyslog_conf_filter.html @@ -0,0 +1,280 @@ + +Filter Conditions - rsyslog.conf + +

This is a part of the rsyslog.conf documentation.

+back +

Filter Conditions

+

Rsyslog offers four different types "filter conditions":

+ +

Blocks

+

Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each +block of lines is separated from the previous block by a program or +hostname specification. A block will only log messages corresponding to +the most recent program and hostname specifications given. Thus, a +block which selects ‘ppp’ as the program, directly followed by a block +that selects messages from the hostname ‘dialhost’, then the second +block will only log messages from the ppp program on dialhost. +

+

A program specification is a line beginning with ‘!prog’ and +the following blocks will be associated with calls to syslog from that +specific program. A program specification for ‘foo’ will also match any +message logged by the kernel with the prefix ‘foo: ’. Alternatively, a +program specification ‘-foo’ causes the following blocks to be applied +to messages from any program but the one specified. A hostname +specification of the form ‘+hostname’ and the following blocks will be +applied to messages received from the specified hostname. +Alternatively, a hostname specification ‘-hostname’ causes the +following blocks to be applied to messages from any host but the one +specified. If the hostname is given as ‘@’, the local hostname will be +used. (NOT YET IMPLEMENTED) A program or hostname specification may be +reset by giving the program or hostname as ‘*’.

+

Please note that the "#!prog", "#+hostname" and "#-hostname" +syntax available in BSD syslogd is not supported by rsyslogd. By +default, no hostname or program is set.

+

Selectors

+

Selectors are the traditional way of filtering syslog +messages. They have been kept in rsyslog with their original +syntax, because it is well-known, highly effective and also needed for +compatibility with stock syslogd configuration files. If you just need +to filter based on priority and facility, you should do this with +selector lines. They are not second-class citizens +in rsyslog and offer the best performance for this job.

+

The selector field itself again consists of two parts, a +facility and a 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 rsyslog(3). The names mentioned below correspond to the +similar LOG_-values in /usr/include/rsyslog.h.
+
+The facility is one of the following keywords: auth, authpriv, cron, +daemon, kern, lpr, mail, mark, news, security (same as auth), syslog, +user, uucp and local0 through local7. The keyword security should not +be used anymore and 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 facility specifies the subsystem that +produced the message, i.e. all mail programs log with the mail facility +(LOG_MAIL) if they log using syslog.
+
+The priority is one of the following keywords, in ascending order: +debug, info, notice, warning, warn (same as warning), err, error (same +as err), crit, alert, emerg, panic (same as emerg). The keywords error, +warn and panic are deprecated and should not be used anymore. The +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. +Rsyslogd behaves the same, but has some extensions.
+
+In addition to the above mentioned names the 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 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 action using +the semicolon (";'') separator. Remember that each selector in the +selector field is capable to overwrite the preceding ones. Using this +behavior you can exclude some priorities from the pattern.

+

Rsyslogd 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.

+

Property-Based Filters

+

Property-based filters are unique to rsyslogd. They allow to +filter on any property, like HOSTNAME, syslogtag and msg. A list of all +currently-supported properties can be found in the property replacer documentation +(but keep in mind that only the properties, not the replacer is +supported). With this filter, each properties can be checked against a +specified value, using a specified compare operation. Currently, there +is only a single compare operation (contains) available, but additional +operations will be added in the future.

+

A property-based filter must start with a colon in column 0. +This tells rsyslogd that it is the new filter type. The colon must be +followed by the property name, a comma, the name of the compare +operation to carry out, another comma and then the value to compare +against. This value must be quoted. There can be spaces and tabs +between the commas. Property names and compare operations are +case-sensitive, so "msg" works, while "MSG" is an invalid property +name. In brief, the syntax is as follows:

+

:property, [!]compare-operation, "value"

+

The following compare-operations are +currently supported:

+ + + + + + + + + + + + + + + + + + + +
containsChecks if the string provided in value is contained in +the property. There must be an exact match, wildcards are not supported.
isequalCompares the "value" string provided and the property +contents. These two values must be exactly equal to match. The +difference to contains is that contains searches for the value anywhere +inside the property value, whereas all characters must be identical for +isequal. As such, isequal is most useful for fields like syslogtag or +FROMHOST, where you probably know the exact contents.
startswithChecks if the value is found exactly at the beginning +of the property value. For example, if you search for "val" with +

:msg, startswith, "val"

+

it will be a match if msg contains "values are in this +message" but it won't match if the msg contains "There are values in +this message" (in the later case, contains would match). Please note +that "startswith" is by far faster than regular expressions. So even +once they are implemented, it can make very much sense +(performance-wise) to use "startswith".

+
regexCompares the property against the provided POSIX +regular +expression.
+

You can use the bang-character (!) immediately in front of a +compare-operation, the outcome of this operation is negated. For +example, if msg contains "This is an informative message", the +following sample would not match:

+

:msg, contains, "error"

+

but this one matches:

+

:msg, !contains, "error"

+

Using negation can be useful if you would like to do some +generic processing but exclude some specific events. You can use the +discard action in conjunction with that. A sample would be:

+

*.* +/var/log/allmsgs-including-informational.log
+:msg, contains, "informational"  ~ +
+*.* /var/log/allmsgs-but-informational.log

+

Do not overlook the red tilde in line 2! In this sample, all +messages are written to the file allmsgs-including-informational.log. +Then, all messages containing the string "informational" are discarded. +That means the config file lines below the "discard line" (number 2 in +our sample) will not be applied to this message. Then, all remaining +lines will also be written to the file allmsgs-but-informational.log.

+

Value is a quoted string. It supports some +escape sequences:

+

\" - the quote character (e.g. "String with \"Quotes\"")
+\\ - the backslash character (e.g. "C:\\tmp")

+

Escape sequences always start with a backslash. Additional +escape sequences might be added in the future. Backslash characters must +be escaped. Any other sequence then those outlined above is invalid and +may lead to unpredictable results.

+

Probably, "msg" is the most prominent use case of property +based filters. It is the actual message text. If you would like to +filter based on some message content (e.g. the presence of a specific +code), this can be done easily by:

+

:msg, contains, "ID-4711"

+

This filter will match when the message contains the string +"ID-4711". Please note that the comparison is case-sensitive, so it +would not match if "id-4711" would be contained in the message.

+

:msg, regex, "fatal .* error"

+

This filter uses a POSIX regular expression. It matches when +the +string contains the words "fatal" and "error" with anything in between +(e.g. "fatal net error" and "fatal lib error" but not "fatal error" as +two spaces are required by the regular expression!).

+

Getting property-based filters right can sometimes be +challenging. In order to help you do it with as minimal effort as +possible, rsyslogd spits out debug information for all property-based +filters during their evaluation. To enable this, run rsyslogd in +foreground and specify the "-d" option.

+

Boolean operations inside property based filters (like +'message contains "ID17" or message contains "ID18"') are currently not +supported (except for "not" as outlined above). Please note that while +it is possible to query facility and severity via property-based +filters, it is far more advisable to use classic selectors (see above) +for those cases.

+

Expression-Based Filters

+Expression based filters allow +filtering on arbitrary complex expressions, which can include boolean, +arithmetic and string operations. Expression filters will evolve into a +full configuration scripting language. Unfortunately, their syntax will +slightly change during that process. So if you use them now, you need +to be prepared to change your configuration files some time later. +However, we try to implement the scripting facility as soon as possible +(also in respect to stage work needed). So the window of exposure is +probably not too long.
+
+Expression based filters are indicated by the keyword "if" in column 1 +of a new line. They have this format:
+
+if expr then action-part-of-selector-line
+
+"If" and "then" are fixed keywords that mus be present. "expr" is a +(potentially quite complex) expression. So the expression documentation for +details. "action-part-of-selector-line" is an action, just as you know +it (e.g. "/var/log/logfile" to write to that file).
+
+A few quick samples:
+
+ +*.* /var/log/file1 # the traditional way
+if $msg contains 'error' /var/log/errlog # the expression-based way
+ +
+Right now, you need to specify numerical values if you would like to +check for facilities and severity. These can be found in RFC 3164. +If you don't like that, you can of course also use the textual property +- just be sure to use the right one. As expression support is enhanced, +this will change. For example, if you would like to filter on message +that have facility local0, start with "DEVNAME" and have either +"error1" or "error0" in their message content, you could use the +following filter:
+
+ +if $syslogfacility-text == 'local0' and $msg +startswith 'DEVNAME' and ($msg contains 'error1' or $msg contains +'error0') then /var/log/somelog
+ +
+Please note that the above must +all be on one line! And if you would like to store all +messages except those that contain "error1" or "error0", you just need +to add a "not":
+
+ +if $syslogfacility-text == 'local0' and $msg +startswith 'DEVNAME' and not +($msg contains 'error1' or $msg contains +'error0') then /var/log/somelog
+ +
+If you would like to do case-insensitive comparisons, use +"contains_i" instead of "contains" and "startswith_i" instead of +"startswith".
+
+Note that regular expressions are currently NOT +supported in expression-based filters. These will be added later when +function support is added to the expression engine (the reason is that +regular expressions will be a separate loadable module, which requires +some more prequisites before it can be implemented).
+ +

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + diff --git a/doc/rsyslog_conf_global.html b/doc/rsyslog_conf_global.html new file mode 100644 index 00000000..bc618dd0 --- /dev/null +++ b/doc/rsyslog_conf_global.html @@ -0,0 +1,227 @@ + +Global Directives - rsyslog.conf + +

This is a part of the rsyslog.conf documentation.

+back +

Global Directives

+

All global directives need to be specified on a line by their +own and must start with a dollar-sign. Here is a list in alphabetical +order. Follow links for a description.

+

Please note that not all directives here are actually global. Some affect +only the next action. This documentation will be changed soon. +

Not all directives have an in-depth description right now. +Default values for them are in bold. A more in-depth description will +appear as implementation progresses. +

+

Be sure to read information about queues in rsyslog - +many parameter settings modify queue parameters. If in doubt, use the +default, it is usually well-chosen and applicable in most cases.

+ +

Where <size_nbr> is specified above, +modifiers can be used after the number part. For example, 1k means +1024. Supported are k(ilo), m(ega), g(iga), t(era), p(eta) and e(xa). +Lower case letters refer to the traditional binary defintion (e.g. 1m +equals 1,048,576) whereas upper case letters refer to their new +1000-based definition (e.g 1M equals 1,000,000).

+

Numbers may include '.' and ',' for readability. So you can +for example specify either "1000" or "1,000" with the same result. +Please note that rsyslogd simply ignores the punctuation. Form it's +point of view, "1,,0.0.,.,0" also has the value 1000.

+ +

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + + diff --git a/doc/rsyslog_conf_modules.html b/doc/rsyslog_conf_modules.html new file mode 100644 index 00000000..890a55c8 --- /dev/null +++ b/doc/rsyslog_conf_modules.html @@ -0,0 +1,53 @@ + +Modules - rsyslog.conf + +

This is a part of the rsyslog.conf documentation.

+back +

Modules

+

Rsyslog has a modular design. Consequently, there is a growing +number of modules. Here is the entry point to their documentation and +what they do (list is currently not complete)

+ +

Please note that each module provides configuration +directives, which are NOT necessarily being listed below. Also +remember, that a modules configuration directive (and functionality) is +only available if it has been loaded (using $ModLoad).

+

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + diff --git a/doc/rsyslog_conf_output.html b/doc/rsyslog_conf_output.html new file mode 100644 index 00000000..c52aaa5e --- /dev/null +++ b/doc/rsyslog_conf_output.html @@ -0,0 +1,81 @@ + +Output Channels - rsyslog.conf + +

This is a part of the rsyslog.conf documentation.

+back +

Output Channels

+

Output Channels are a new concept first introduced in rsyslog +0.9.0. As of this writing, it is most likely that they will +be replaced by something different in the future. 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. +they can only be used to write to files - not pipes, ttys or whatever +Output channels define the output definition, only. As of this build, +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. +This command always has exactly one parameter. The binary is that part +of action-on-max-size before the first space, its parameter is +everything behind that space.
+
+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 reached, 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.

+

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.

+ +

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + + diff --git a/doc/rsyslog_conf_templates.html b/doc/rsyslog_conf_templates.html new file mode 100644 index 00000000..90b5fafe --- /dev/null +++ b/doc/rsyslog_conf_templates.html @@ -0,0 +1,150 @@ + +Templates - rsyslog.conf + +

This is a part of the rsyslog.conf - documentation.

+back +

Templates

+

Templates are a key feature of rsyslog. They allow to specify +any +format a user might want. They are also used for dynamic file name +generation. 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 rsyslogd. +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 +influencing 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:

+

sql - format the string suitable for a SQL +statement in MySQL format. This will replace single quotes ("'") and +the backslash character by their backslash-escaped counterpart ("\'" +and "\\") inside each field. Please note that in MySQL configuration, +the NO_BACKSLASH_ESCAPES +mode must be turned off for this format to work (this is the default).

+

stdsql - format the string suitable for a +SQL statement that is to be sent to a standards-compliant sql server. +This will replace single quotes ("'") by two single quotes ("''") +inside each field. You must use stdsql together with MySQL if in MySQL +configuration the +NO_BACKSLASH_ESCAPES is +turned on.

+

Either the sql or stdsql  +option must be specified when a template is used +for writing to a database, otherwise injection might occur. Please note +that due to the unfortunate fact that several vendors have violated the +sql standard and introduced their own escape methods, it is impossible +to have a single option doing all the work.  So you yourself +must make sure you are using the right format. If you choose +the wrong one, you are still vulnerable to sql injection.
+
+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 accidental 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 ;)

+

The default template for the write to database action has the +sql option set. As we currently support only MySQL and the sql option +matches the default MySQL configuration, this is a good choice. +However, if you have turned on +NO_BACKSLASH_ESCAPES in +your MySQL config, you need to supply a template with the stdsql +option. Otherwise you will become vulnerable to SQL injection.
+
+To escape:
+% = \%
+\ = \\ --> '\' is used to escape (as in C)
+$template TraditionalFormat,%timegenerated% %HOSTNAME% +%syslogtag%%msg%\n"
+
+Properties can be accessed by the property +replacer (see there for details).

+

Please note that templates can also by +used to generate selector lines with dynamic file names. For +example, if you would like to split syslog messages from different +hosts to different files (one per host), you can define the following +template:

+
$template +DynFile,"/var/log/system-%HOSTNAME%.log"
+

This template can then be used when defining an output +selector line. It will result in something like +"/var/log/system-localhost.log"

+

Template +names beginning with "RSYSLOG_" are reserved for rsyslog use. Do NOT +use them if, otherwise you may receive a conflict in the future (and +quite unpredictable behaviour). There is a small set of pre-defined +templates that you can use without the need to define it:

+ + +

[manual index] +[rsyslog.conf] +[rsyslog site]

+

This documentation is part of the +rsyslog project.
+Copyright © 2008 by Rainer Gerhards and +Adiscon. Released under the GNU GPL +version 2 or higher.

+ + + -- cgit