diff options
Diffstat (limited to '')
8 files changed, 265 insertions, 0 deletions
diff --git a/source/configuration/input_directives/index.rst b/source/configuration/input_directives/index.rst new file mode 100644 index 0000000..796b73e --- /dev/null +++ b/source/configuration/input_directives/index.rst @@ -0,0 +1,28 @@ +Legacy Directives affecting Input Modules +========================================= + +Legacy Directives affecting multiple Input Modules +-------------------------------------------------- +While these directives only affect input modules, they are global in +the sense that they cannot be overwritten for specific input +instances. So they apply globally for all inputs that support these +directives. + +.. toctree:: + :glob: + + rsconf1_allowedsender + rsconf1_dropmsgswithmaliciousdnsptrrecords + rsconf1_controlcharacterescapeprefix + rsconf1_droptrailinglfonreception + rsconf1_escape8bitcharsonreceive + rsconf1_escapecontrolcharactersonreceive + +immark-specific Directives +-------------------------- + +.. toctree:: + :glob: + + rsconf1_markmessageperiod + diff --git a/source/configuration/input_directives/rsconf1_allowedsender.rst b/source/configuration/input_directives/rsconf1_allowedsender.rst new file mode 100644 index 0000000..eb30054 --- /dev/null +++ b/source/configuration/input_directives/rsconf1_allowedsender.rst @@ -0,0 +1,71 @@ +$AllowedSender +-------------- + +**Type:** input configuration parameter + +**Default:** all allowed + +**Description:** + +*Note:* this feature is supported for backward-compatibility, only. +The rsyslog team recommends to use proper firewalling instead of +this feature. + +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 <type>, ip[/bits], ip[/bits] + +"$AllowedSender" is the parameter - it must be written exactly as shown +and the $ must start at the first column of the line. "<type>" is either "UDP" +or "TCP" (or "GSS", if this is enabled during compilation). +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 parameters. 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 wherever possible. + +**Sample:** + +:: + + $AllowedSender UDP, 127.0.0.1, 192.0.2.0/24, [::1]/128, *.example.net, somehost.example.com + diff --git a/source/configuration/input_directives/rsconf1_controlcharacterescapeprefix.rst b/source/configuration/input_directives/rsconf1_controlcharacterescapeprefix.rst new file mode 100644 index 0000000..06ddb12 --- /dev/null +++ b/source/configuration/input_directives/rsconf1_controlcharacterescapeprefix.rst @@ -0,0 +1,24 @@ +$ControlCharacterEscapePrefix +----------------------------- + +**Type:** global configuration parameter + +**Default:** \\ + +**Description:** + +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. + +**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 parameter will probably change in future +releases. + +**Sample:** + +``$EscapeControlCharactersOnReceive # # as of syslog-protocol`` + diff --git a/source/configuration/input_directives/rsconf1_dropmsgswithmaliciousdnsptrrecords.rst b/source/configuration/input_directives/rsconf1_dropmsgswithmaliciousdnsptrrecords.rst new file mode 100644 index 0000000..81562ef --- /dev/null +++ b/source/configuration/input_directives/rsconf1_dropmsgswithmaliciousdnsptrrecords.rst @@ -0,0 +1,22 @@ +$DropMsgsWithMaliciousDnsPTRRecords +----------------------------------- + +**Type:** global configuration parameter + +**Default:** off + +**Description:** + +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. If 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. + +**Sample:** + +``$DropMsgsWithMaliciousDnsPTRRecords on`` + diff --git a/source/configuration/input_directives/rsconf1_droptrailinglfonreception.rst b/source/configuration/input_directives/rsconf1_droptrailinglfonreception.rst new file mode 100644 index 0000000..1f69195 --- /dev/null +++ b/source/configuration/input_directives/rsconf1_droptrailinglfonreception.rst @@ -0,0 +1,21 @@ +$DropTrailingLFOnReception +-------------------------- + +**Type:** global configuration parameter + +**Default:** on + +**Description:** + +Syslog messages frequently have the line feed character (LF) as the last +character of the message. In almost 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. + +**Sample:** + +``$DropTrailingLFOnReception on`` + diff --git a/source/configuration/input_directives/rsconf1_escape8bitcharsonreceive.rst b/source/configuration/input_directives/rsconf1_escape8bitcharsonreceive.rst new file mode 100644 index 0000000..7377f65 --- /dev/null +++ b/source/configuration/input_directives/rsconf1_escape8bitcharsonreceive.rst @@ -0,0 +1,39 @@ +$Escape8BitCharactersOnReceive +------------------------------ + +**Type:** global configuration parameter + +**Default:** off + +**Available Since:** 5.5.2 + +**Description:** + +This parameter instructs rsyslogd to replace non US-ASCII characters +(those that have the 8th bit set) during reception of the message. This +may be useful for some systems. Please note that this escaping breaks +Unicode and many other encodings. Most importantly, it can be assumed +that Asian and European characters will be rendered hardly readable by +this settings. However, it may still be useful when the logs themselves +are primarily in English and only occasionally contain local script. If +this option is turned on, all control-characters are converted to a +3-digit octal number and be prefixed with the +$ControlCharacterEscapePrefix character (being '#' by default). + +**Warning:** + +- turning on this option most probably destroys non-western character + sets (like Japanese, Chinese and Korean) as well as European + character sets. +- turning on this option destroys digital signatures if such exists + inside the message +- if turned on, the drop-cc, space-cc and escape-cc `property + replacer <property_replacer.html>`_ options do not work as expected + because control characters are already removed upon message + reception. If you intend to use these property replacer options, you + must turn off $Escape8BitCharactersOnReceive. + +**Sample:** + +``$Escape8BitCharactersOnReceive on`` + diff --git a/source/configuration/input_directives/rsconf1_escapecontrolcharactersonreceive.rst b/source/configuration/input_directives/rsconf1_escapecontrolcharactersonreceive.rst new file mode 100644 index 0000000..05cc623 --- /dev/null +++ b/source/configuration/input_directives/rsconf1_escapecontrolcharactersonreceive.rst @@ -0,0 +1,34 @@ +$EscapeControlCharactersOnReceive +--------------------------------- + +**Type:** global configuration parameter + +**Default:** on + +**Description:** + +This parameter 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 turned 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. + +**Warning:** + +- turning on this option most probably destroys non-western character + sets (like Japanese, Chinese and Korean) +- turning on this option destroys digital signatures if such exists + inside the message +- if turned on, the drop-cc, space-cc and escape-cc `property + replacer <property_replacer.html>`_ options do not work as expected + because control characters are already removed upon message + reception. If you intend to use these property replacer options, you + must turn off $EscapeControlCharactersOnReceive. + +**Sample:** + +``$EscapeControlCharactersOnReceive on`` + diff --git a/source/configuration/input_directives/rsconf1_markmessageperiod.rst b/source/configuration/input_directives/rsconf1_markmessageperiod.rst new file mode 100644 index 0000000..074cc95 --- /dev/null +++ b/source/configuration/input_directives/rsconf1_markmessageperiod.rst @@ -0,0 +1,26 @@ +$MarkMessagePeriod +------------------ + +**Type:** specific to immark input module + +**Default:** 1200 (20 minutes) + +**Description:** + +This specifies when mark messages are to be written to output modules. +The time specified is in seconds. Specifying 0 is possible and disables +mark messages. In that case, however, it is more efficient to NOT load +the immark input module. + +So far, there is only one mark message process and any subsequent +$MarkMessagePeriod overwrites the previous. + +**This parameter is only available after the immark input module has +been loaded.** + +**Sample:** + +``$MarkMessagePeriod 600 # mark messages appear every 10 Minutes`` + +**Available since:** rsyslog 3.0.0 + |