From 4459faa3799e4804402327e8fc4ea92abc96a0e1 Mon Sep 17 00:00:00 2001
From: Rainer Gerhards
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.
-
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 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
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.
-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.
-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.
-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.
-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.
-This is the same as $FileCreateMode, but for directories automatically -generated.
-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
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
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.
-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.
-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.
-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
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
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.
-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:
-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
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
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
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
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
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 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