From 4459faa3799e4804402327e8fc4ea92abc96a0e1 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 8 Aug 2007 13:59:43 +0000 Subject: somewhat improved config file doc - thanks to Florian Riedl for doing the bulk of work --- doc/rsyslog_conf.html | 325 ++++---------------------------------------------- 1 file changed, 24 insertions(+), 301 deletions(-) (limited to 'doc/rsyslog_conf.html') diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html index af9263a6..dcbf5dad 100644 --- a/doc/rsyslog_conf.html +++ b/doc/rsyslog_conf.html @@ -19,7 +19,30 @@ to rsyslogd.

start with a dollar-sign. Here is a list in alphabetical order. Follow links for a description.

Basic Structure

Rsyslog supports standard sysklogd's configuration file format and extends @@ -35,307 +58,7 @@ specifies a pattern of facilities and priorities belonging to the specified action.

Lines starting with a hash mark ("#'') and empty lines are ignored. -

ActionExecOnlyIfPreviousIsSuspended

-

This directive allows to specify if actions should always be executed ("off," -the default) or only if the previous action is suspended ("on"). This directive -works hand-in-hand with the multiple actions per selector feature. It can be -used, for example, to create rules that automatically switch destination servers -or databases to a (set of) backup(s), if the primary server fails. Note that -this feature depends on proper implementation of the suspend feature in the -output module. All built-in output modules properly support it (most importantly -the database write and the syslog message forwarder).

-

The following is an example of what can be done with it (a config file -excerpt):

-

*.* @@primary-syslog.example.com
-$ActionExecOnlyIfPreviousIsSuspended on
-&   @@secondary-1-syslog.example.com    # & is used to -have more than one action for
-&   @@secondary-2-syslog.example.com    # the same -selector - the mult-action feature
-&   /var/log/localbuffer
-$ActionExecOnlyIfPreviousIsSuspended off # to re-set it for the next selector

-

This selector processes all messages it receives (*.*).  It tries to -forward every message to primary-syslog.example.com (via tcp). If it can not -reach that server, it tries secondary-1-syslog.example.com, if that fails too, -it tries secondary-2-syslog.example.com. If neither of these servers can be -connected, the data is stored in /var/log/localbuffer. Please note that the -secondaries and the local log buffer are only used if the one before them does -not work. So ideally, /var/log/localbuffer will never receive a message. If one -of the servers resumes operation, it automatically takes over processing again.

-

We strongly advise not to use repeated line reduction together with -ActionExecOnlyIfPreviousIsSuspended. It may lead to "interesting" and undesired -results (but you can try it if you like).

-

Allowed Sender Lists

-

Allowed sender lists can be used to specify which remote systems are allowed -to send syslog messages to rsyslogd. With them, further hurdles can be placed -between an attacker and rsyslogd. If a message from a system not in the allowed -sender list is received, that message is discarded. A diagnostic message is -logged, so that the fact is recorded (this message can be turned off with the -"-w" rsyslogd command line option).

-

Allowed sender lists can be defined for UDP and TCP senders separately. There -can be as many allowed senders as needed. The syntax to specify them is:

-

$AllowedSender <protocol>, ip[/bits], ip[/bits]

-

"$AllowedSender" is the directive - it must be written exactly as shown and -the $ must start at the first column of the line. "<protocol>" is either "UDP" -or "TCP". It must immediately be followed by the comma, else you will receive an -error message. "ip[/bits]" is a machine or network ip address as in -"192.0.2.0/24" or "127.0.0.1". If the "/bits" part is omitted, a single host is -assumed (32 bits or mask 255.255.255.255). "/0" is not allowed, because that -would match any sending system. If you intend to do that, just remove all $AllowedSender -directives. If more than 32 bits are requested with IPv4, they are adjusted to 32. -For IPv6, the limit is 128 for obvious reasons. Hostnames, with and without -wildcards, may also be provided. If so, the result of revers DNS resolution is -used for filtering. -Multiple allowed senders can be specified in a comma-delimited list. Also, -multiple $AllowedSender lines can be given. They are all combined into one UDP -and one TCP list. Performance-wise, it is good to specify those allowed senders -with high traffic volume before those with lower volume. As soon as a match is -found, no further evaluation is necessary and so you can save CPU cycles.

-

Rsyslogd handles allowed sender detection very early in the code, nearly as -the first action after receiving a message. This keeps the access to potential -vulnerable code in rsyslog at a minimum. However, it is still a good idea to -impose allowed sender limitations via firewalling.

-

WARNING: by UDP design, rsyslogd can not identify a spoofed sender -address in UDP syslog packets. As such, a malicious person could spoof the -address -of an allowed sender, send such packets to rsyslogd and rsyslogd would accept -them as being from the faked sender. To prevent this, use syslog via TCP -exclusively. If you need to use UDP-based syslog, make sure that you do proper -egress and ingress filtering at the firewall and router level.

-

Rsyslog also detects some kind of malicious reverse DNS entries. In any case, -using DNS names adds an extra layer of vulnerability. We recommend to stick with -hard-coded IP addresses whereever possible.

-

An example for an allowed sender list is as follows:

-

$AllowedSender UDP, 127.0.0.1, 192.0.2.0/24, [::1]/128, -*.example.net, somehost.example.com

-

UMASK

-

The $umask directive allows to specify the rsyslogd processes' umask. If not -specified, the system-provided default is used. The value given must always be a -4-digit octal number, with the initial digit being zero. This sample removes all -umask-restriction:

-

$umask 0000

-

If $umask is specified multiple times in the configuration file, results may -be somewhat unpredictable. It is recommended to specify it only once.

-

FileCreateMode

-

The $FileCreateMode directive allows to specify the creation mode with which -rsyslogd creates new files. If not specified, the value 0644 is used (which -retains backward-compatibility with earlier releases). The value given must -always be a 4-digit octal number, with the initial digit being zero. This sample -lets rsyslog create files with read and write access only for the users it runs -under:

-

$FileCreateMode 0600

-

Please note that the actual permission depend on rsyslogd's process umask. If -in doubt, use "$umask 0000" right at the beginning of the configuration file to -remove any restrictions.

-

$FileCreateMode may be specified multiple times. If so, it specifies the -creation mode for all selector lines that follow until the next $FileCreateMode -directive. Order of lines is vitally important. Here is a sample (this is deemed -to be a complete rsyslog.conf):

-

$umask 0000 # make sure nothing interfers with the following -definitions
-*.* /var/log/file-with-0644-default
-$FileCreateMode 0600
-*.* /var/log/file-with-0600
-$FileCreateMode 0644
-*.* /var/log/file-with-0644

-

As you can see, open modes depend on position in the config file. Note the -first line, which is created with the hardcoded default creation mode.

-

DebugPrintCFSyslineHandlerList

-

Specifies whether or not the configuration file sysline handler list should be written to the debug -log. Possible values: on/off. Default is on. Does not affect operation if debugging is -disabled.

-

DebugPrintModuleList

-

Specifies whether or not the module list should be written to the debug -log. Possible values: on/off. Default is on. Does not affect operation if debugging is -disabled.

-

DebugPrintTemplateList

-

Specifies whether or not the template list should be written to the debug -log. Possible values: on/off. Default is on. Does not affect operation if debugging is -disabled.

-

DirCreateMode

-

This is the same as $FileCreateMode, but for directories automatically -generated.

-

DirGroup

-

Set the group for directories newly created. Please note that this setting -does not affect the group of directories already existing. The parameter is a -group name, for which the groupid is obtained by rsyslogd on startup and on -HUPing. Interim changes to the user mapping are not detected.

-

$DirGroup loggroup

-

DirOwner

-

Set the file owner for directories newly created. Please note that this -setting does not affect the owner of directories already existing. The parameter -is a user name, for which the userid is obtained by rsyslogd on startup and on -HUPing. Interim changes to the user mapping are not detected.

-

$DirOwner loguser

-

IncludeConfig

-

This directive allows to include other files into the main configuration -file. As soon as an IncludeConfig directive is found, the contents of the new -file is processed. IncludeConfigs can be nested. Please note that from a logical -point of view the files are merged. Thus, if the include modifies some -parameters (e.g. $DynaFileChacheSize), these new parameters are in place for the -"calling" configuration file when the include is completed. To avoid any side -effects, do a $ResetConfigVariables after the $IncludeConfig. It may also be a -good idea to do a $ResetConfigVariables right at the start of the include, so -that the module knows exactly what it does. Of course, one might specifically -NOT do this to inherit parameters from the main file. As always, use it as it -best fits...

-

$IncludeConfig /etc/some-included-file.conf

-

Directories can also be included. To do so, the name must end on a slash:

-

$IncludeConfig /etc/rsyslog.d/

-

In this case, all regular files in the /etc/rsyslog.d directory are included. -Files starting with "." are ignored - so you can use them to place comments into -the dir (e.g. "/etc/rsyslog.d/.mycomment" will be ignored). - -Michael Biebl had the idea to this functionality. Let me quote hím:

-
-

Say you can add an option
-$IncludeConfig /etc/rsyslog.d/
-(which probably would make a good default)
-to /etc/rsyslog.conf, which would then merge and include all *.conf files
-in /etc/rsyslog.d/.
-
-This way, a distribution can modify its packages easily to drop a simple
-config file into this directory upon installation.
-
-As an example, the network-manager package could install a simple config
-file /etc/rsyslog.d/network-manager.conf which would contain.
-:programname, contains, "NetworkManager" -/var/log/NetworkManager.log
-
-Upon uninstallation, the file could be easily removed again. This approach
-would be much cleaner and less error prone, than having to munge around
-with the /etc/rsyslog.conf file directly.

-
-

Please note that in this description, only "*.conf" files would be read. The -actual implementation, however, reads all files except for those starting with a -dot. If you find this is a real big problem, please complain.

-

RepeatedMsgReduction

-

This directive specifies whether or not repeated messages should be reduced -(this is the "Last line repeated n times" feature). If set to on, repeated messages are reduced. If set to off, every -message is logged. Please note that -this directive overrides the -e command line option. In case -e is given, it is -just the default value until the first RepeatedMsgReduction directive is -encountered. Sample:

-

$RepeatedMsgReduction off    # log every message

-

Directives affects selector lines until a new directive is specified.

-

DynaFileCacheSize

-

This directive specifies the maximum size of the cache for -dynamically-generated file names. Selector lines with dynamic files names ('?' -indicator) support writing to multiple files with a single selector line. This -setting specifies how many open file handles should be cached. If, for example, -the file name is generated with the hostname in it and you have 100 different -hosts, a cache size of 100 would ensure that files are opened once and then stay -open. This can be a great way to increase performance. If the cache size is -lower than the number of different files, the least recently used one is -discarded (and the file closed). The hardcoded maximum is 10,000 - a value that -we assume should already be very extreme. Please note that if you expect to run -with a very large number of files, you probably need to reconfigure the kernel -to support such a large number. In practice, we do NOT recommend to use a cache -of more than 1,000 entries. The cache lookup would probably require more time -than the open and close operations. The minimum value is 1. Here is a sample:

-

$DynaFileCacheSize 100    # a cache of 100 files at -most

-

Numbers are always in decimal. Leading zeros should be avoided (in some later -version, they may be mis-interpreted as being octal). Multiple directives may be -given. They are applied to selector lines based on order of appearance.

-

DropMsgsWithMaliciousDnsPTRRecords

-

Rsyslog contains code to detect malicious DNS PTR records (reverse name -resolution). An attacker might use specially-crafted DNS entries to make you -think that a message might have originated on another IP address. Rsyslog can -detect those cases. It will log an error message in any case. It this option -here is set to "on", the malicious message will be completely dropped from your -logs. If the option is set to "off", the message will be logged, but the -original IP will be used instead of the DNS name.

-

$DropMsgsWithMaliciousDnsPTRRecords on

-

DropTrailingLFOnReception

-

Syslog messages frequently have the line feed character (LF) as the last -character of the message. In allmost all cases, this LF should not really become -part of the message. However, recent IETF syslog standardization recommends -against modifying syslog messages (e.g. to keep digital signatures valid). This -option allows to specify if trailing LFs should be dropped or not. The default -is to drop them, which is consistent with what sysklogd does. To not drop them, -use

-

$DropTrailingLFOnRecption off

-

ControlCharacterEscapePrefix

-

This option specifies the prefix character to be used for control character -escaping (see option $EscapeControlCharactersOnReceive). By default, it is '\', -which is backwards-compatible with sysklogd. Change it to '#' in order to be -compliant to the value that is somewhat suggested by Internet-Draft -syslog-protocol. The first non-whitespace character after the command is treated -as prefix:

-

$EscapeControlCharactersOnReceive #  # as of syslog-protocol

-

IMPORTANT: do not use the ' character. This is reserved and will most -probably be used in the future as a character delimiter. For the same reason, -the syntax of this directive will probably change in furture releases.

-

EscapeControlCharactersOnReceive

-

This directive instructs rsyslogd to replace control characters during -reception of the message. The intent is to provide a way to stop non-printable -messages from entering the syslog system as whole. If this option is truned on, -all control-characters are converted to a 3-digit octal number and be prefixed -with the $ControlCharacterEscapePrefix character (being '\' by default). For -example, if the BEL character (ctrl-g) is included in the message, it would be -converted to "\007". To be compatible to sysklogd, this option must be turned -on.

-

$EscapeControlCharactersOnReceive on

-

Warning:

- -

FailOnChownFailure

-

This option modifies behaviour of dynaFile creation. If different owners or -groups are specified for new files or directories and rsyslogd fails to set -these new owners or groups, it will log an error and NOT write to the file in -question if that option is set to "on". If it is set to "off", the error will be -ignored and processing continues. Keep in mind, that the files in this case may -be (in)accessible by people who should not have permission. The default is "on".

-

$FailOnChownFailure off

-

FileGroup

-

Set the group for dynaFiles newly created. Please note that this setting does -not affect the group of files already existing. The parameter is a group name, -for which the groupid is obtained by rsyslogd on startup and on HUPing. Interim -changes to the user mapping are not detected.

-

$FileGroup loggroup

-

FileOwner

-

Set the file owner for dynaFiles newly created. Please note that this setting -does not affect the owner of files already existing. The parameter is a user -name, for which the userid is obtained by rsyslogd on startup and on HUPing. -Interim changes to the user mapping are not detected.

-

$FileOwner loguser

-

ResetConfigVariables

-

Resets all configuration variables to their default value. Any settings made -will not be applied to configuration lines following the $ResetConfigVariables. -This is a good method to make sure no side-effects exists from previous -directives. This directive has no parameters.

-

$ResetConfigVariables

-

MainMsgQueueSize

-

This allows to specify the maximum size of the message queue. This directive -is only available when rsyslogd has been compiled with multithreading support. -In this mode, receiver and output modules are de-coupled via an in-memory queue. -This queue buffers messages when the output modules are not capable to process -them as fast as they are received. Once the queue size is exhausted, messages -will be dropped. The slower the output (e.g. MySQL), the larger the queue should -be. Buffer space for the actual queue entries is allocated on an as-needed -basis. Please keep in mind that a very large queue may exhaust available system -memory and swap space. Keep this in mind when configuring the max size. The -actual size of a message depends largely on its content and the orginator. As a -rule of thumb, typically messages should not take up more then roughtly 1k (this -is the memory structure, not what you see in a network dump!). For typical linux -messages, 512 bytes should be a good bet. Please also note that there is a -minimal amout of memory taken for each queue entry, no matter if it is used or -not. This is one pointer value, so on 32bit systems, it should typically be 4 -bytes and on 64bit systems it should typically be 8 bytes. For example, the -default queue size of 10,000 entries needs roughly 40k fixed overhead on a 32 -bit system.

-

$MainMsgQueueSize 100000 # 100,000 may be a value to handle bursty -traffic

-

ModLoad

-

This currently is a dummy directive. It will support the loading of plug-ins -in future releases of rsyslog supporting plug-ins. Currently, only

-

$ModLoad MySQL

-

is supported, which activates MySQL support (if rsyslog is compiled with -MySQL functionality).

+

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, -- cgit