diff options
| -rw-r--r-- | doc/features.html | 93 | ||||
| -rw-r--r-- | doc/history.html | 3 | ||||
| -rw-r--r-- | doc/rsyslog_conf.html | 129 |
3 files changed, 162 insertions, 63 deletions
diff --git a/doc/features.html b/doc/features.html index 14cee12c..0624e503 100644 --- a/doc/features.html +++ b/doc/features.html @@ -1,47 +1,46 @@ -<html>
-<head>
-<title>rsyslog features</title>
-</head>
-<body>
-<h1>RSyslog - Features</h1>
-<p><b>This page lists both current features as well as those being considered
-for future versions of rsyslog.</b> If you think a feature is missing, drop
-<a href="mailto:rgerhards@adiscon.com">Rainer</a> a note. Rsyslog is a vital
-project. Features are added each few days. If you would like to keep up of what
-is going on, you can also subscribe to the <a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a>.
-</p>
-<h2>Current Features</h2>
-<ul>
-
- <li>native support for <a href="rsyslog_mysql.html">writing to MySQL databases</a><li>support for (plain) tcp
- based syslog - much better reliability<li>control of log output format,
- including ability to present channel and priority as visible log data<li>good timestamp format control; at a minimum, ISO 8601/RFC 3339
- second-resolution UTC zone<li>ability to reformat message contents and work with substrings<li>support for
- log files larger than 2gb<li>support for file size limitation and automatic
- rollover command execution<li>support for running multiple rsyslogd
- instances on a single machine<li>support for <a href="rsyslog_stunnel.html">
- ssl-protected syslog</a> (via stunnel)<li>ability to filter on any part of
- the message, not just facility and severity<li>support for discarding
- messages based on filters<li>ability to execute shell scripts on received
- messages<li>control of whether the local hostname or the hostname of the
- origin of the data is shown as the hostname in the output<li>ability to
- preserve the orginal hostname in NAT environments and relay chains
- <li>ability to limit the allowed network senders
- </ul>
-<h2>Upcoming Features</h2>
-<ul>
- <li>support for
- <a href="http://www.syslog.cc/ietf/drafts/draft-ietf-syslog-protocol-14.txt">
- syslog-protocol-14</a> compliant messages
- (pending, as IETF will change proposed format)<li>support for native SSL enryption of plain tcp syslog sessions
- <li>RFC 3195 support - planned (but late)
- <li>pcre filtering - maybe (depending on feedback) - simple regex already
- partly added
- <li>multi-threaded redesign - maybe (depending on feedback; also
- opens Pandorra's cross-platform development box ;))
- </ul>
-<p>To see when each feature was added, see the
-<a href="http://www.rsyslog.com/Topic4.phtml">rsyslog change log</a> (online
-only).</p>
-</body>
-</html>
+<html>
+<head>
+<title>rsyslog features</title>
+</head>
+<body>
+<h1>RSyslog - Features</h1>
+<p><b>This page lists both current features as well as those being considered
+for future versions of rsyslog.</b> If you think a feature is missing, drop
+<a href="mailto:rgerhards@adiscon.com">Rainer</a> a note. Rsyslog is a vital
+project. Features are added each few days. If you would like to keep up of what
+is going on, you can also subscribe to the <a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a>.
+</p>
+<h2>Current Features</h2>
+<ul>
+
+ <li>native support for <a href="rsyslog_mysql.html">writing to MySQL databases</a><li>support for (plain) tcp
+ based syslog - much better reliability<li>control of log output format,
+ including ability to present channel and priority as visible log data<li>good timestamp format control; at a minimum, ISO 8601/RFC 3339
+ second-resolution UTC zone<li>ability to reformat message contents and work with substrings<li>support for
+ log files larger than 2gb<li>support for file size limitation and automatic
+ rollover command execution<li>support for running multiple rsyslogd
+ instances on a single machine<li>support for <a href="rsyslog_stunnel.html">
+ ssl-protected syslog</a> (via stunnel)<li>ability to filter on any part of
+ the message, not just facility and severity<li>support for discarding
+ messages based on filters<li>ability to execute shell scripts on received
+ messages<li>control of whether the local hostname or the hostname of the
+ origin of the data is shown as the hostname in the output<li>ability to
+ preserve the original hostname in NAT environments and relay chains
+ <li>ability to limit the allowed network senders</ul>
+<h2>Upcoming Features</h2>
+<ul>
+ <li>support for
+ <a href="http://www.syslog.cc/ietf/drafts/draft-ietf-syslog-protocol-14.txt">
+ syslog-protocol-14</a> compliant messages
+ (pending, as IETF will change proposed format)<li>support for native SSL enryption of plain tcp syslog sessions
+ <li>RFC 3195 support - planned (but late)
+ <li>pcre filtering - maybe (depending on feedback) - simple regex already
+ partly added
+ <li>multi-threaded redesign - maybe (depending on feedback; also
+ opens Pandorra's cross-platform development box ;))
+ </ul>
+<p>To see when each feature was added, see the
+<a href="http://www.rsyslog.com/Topic4.phtml">rsyslog change log</a> (online
+only).</p>
+</body>
+</html>
diff --git a/doc/history.html b/doc/history.html index de427ce5..d40d13ca 100644 --- a/doc/history.html +++ b/doc/history.html @@ -42,8 +42,7 @@ we intend to advance the code and introduce new features. </p><p>
The database support was included so that our web-based syslog interface
can be used. This is another open source project which can be found
-under <a href="http://www.liblogging.org/">http://www.liblogging.org</a> (this
-site needs serious redesign!). We highly recommend having a look at
+under <a href="http://www.liblogging.org/">http://www.liblogging.org</a>. We highly recommend having a look at
it. It might not work for you if you expect thousands of messages per
second (because your database won't be able to provide adequate performance),
but in many cases it is a very handy analysis and troubleshooting tool.
diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html index 30dd025f..38a0ab80 100644 --- a/doc/rsyslog_conf.html +++ b/doc/rsyslog_conf.html @@ -3,11 +3,11 @@ <title>rsyslog.conf file</title>
</head>
<body>
-<h1>sqrsyslog.conf configuration file</h1>
+<h1>rsyslog.conf configuration file</h1>
<p><b>This document is currently being enhanced. Please pardon its current
appearance.</b></p>
<p><b>Rsyslogd is configured via the rsyslog.conf file</b>, typically found in
-/etc. By default, rsyslog reads the file /etc/rsyslog.conf.</p>
+/etc. By default, rsyslogd reads the file /etc/rsyslog.conf.</p>
<p>While rsyslogd contains enhancements over standard syslogd, efforts have been
made to keep the configuration file as compatible as possible. While, for
obvious reasons, <a href="features.html">enhanced features</a> require a
@@ -15,12 +15,54 @@ different config file syntax, rsyslogd should be able to work with a standard syslog.conf file. This is especially useful while you are migrating from syslogd
to rsyslogd.</p>
<h2>Basic Structure</h2>
-<p>Every rule consists of two fields, a selector field and an action field.
+<p>Rsyslog supports standard sysklogd's configuration file format and extends
+it. So in general, you can take a "normal" syslog.conf and use it together with
+rsyslogd. It will understand everything. However, to use most of rsyslogd's
+unique features, you need to add extended configuration directives.<p>Rsyslogd
+supports the classical, selector-based rule lines. They are still at the heart
+of it and all actions are initiated via rule lines. A rule lines is any line not
+starting with a $ or the comment sign (#). Lines starting with $ carry
+rsyslog-specific directives.<p>Every rule line consists of two fields, a selector field and an action field.
These two fields are separated by one or more spaces or tabs. The selector field
specifies a pattern of facilities and priorities belonging to the specified
action.<br>
<br>
-Lines starting with a hash mark (``#'') and empty lines are ignored.
+Lines starting with a hash mark ("#'') and empty lines are ignored.
+<h2>Allowed Sender Lists</h2>
+<p>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).</p>
+<p>Allowed sender lists can be defined for UDP and TCP senders seperately. There
+can be as many allowed senders as needed. The syntax to specify them is:</p>
+<p><code><b>$AllowedSender <protocol>, ip[/bits], ip[/bits]</b></code></p>
+<p>"$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, they are adjusted to 32.
+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.</p>
+<p>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.</p>
+<p><b>WARNING:</b> by UDP design, rsyslogd can not identify a spoofed sender
+address in UDP syslog packets. As such, a malicous person could spoof the adress
+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.</p>
+<p>An example for an allowed sender list is as follows:</p>
+<p><code><b>$AllowedSender UDP, 127.0.0.1, 192.0.2.0/24</b></code></p>
<h2>Templates</h2>
<p>Templates are a key feature of rsyslog. They allow to specify any format a user
might want. Every output in rsyslog uses templates - this holds true for files,
@@ -187,8 +229,7 @@ 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<br>
<br>The behavior of the original BSD syslogd is that all messages of the specified
-priority and higher are logged according to the given action. This rsyslogd(8)
-behaves the same, but has some extensions.<br><br>In addition to the above mentioned names the rsyslogd(8) understands the
+priority and higher are logged according to the given action. Rsyslogd behaves the same, but has some extensions.<br><br>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.<br><br>You can specify multiple facilities with the same priority pattern in one
@@ -222,7 +263,7 @@ 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:</p>
-<p><code><b>:property, compare-operation, "value"</b></code></p>
+<p><code><b>:property, [!]compare-operation, "value"</b></code></p>
<p>The following <b>compare-operations</b> are currently supported:</p>
<table border="1" width="100%" id="table1">
<tr>
@@ -231,10 +272,48 @@ brief, the syntax is as follows:</p> There must be an exact match, wildcards are not supported.</td>
</tr>
<tr>
+ <td>isequal</td>
+ <td>Compares the "value" string provided and the property contents.
+ These two values must be exactly equal to match. The difference to
+ contains is that contains searchs 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.</td>
+ </tr>
+ <tr>
+ <td>startswith</td>
+ <td>Checks if the value is found exactly at the beginning of the
+ property value. For example, if you search for "val" with<p><code><b>:msg,
+ startswith, "val"</b></code></p>
+ <p>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".</td>
+ </tr>
+ <tr>
<td>regex</td>
<td><b>NOT YET IMPLEMENTED</b> - value holds an regular expression</td>
</tr>
</table>
+<p>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:</p>
+<p><code><b>:msg, contains, "error"</b></code></p>
+<p>but this one matches:</p>
+<p><code><b>:msg, !contains, "error"</b></code></p>
+<p>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:</p>
+<p><code><b>*.* /var/log/allmsgs-including-informational.log<br>
+:msg, contains, "informational" <font color="#FF0000" size="4">~</font>
+<br>*.* /var/log/allmsgs-but-informational.log</b></code></p>
+<p>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.</p>
<p><b>Value</b> is a quoted string. It supports some escape sequences:</p>
<p>\" - the quote character (e.g. "String with \"Quotes\"")<br>
\\ - the backslash character (e.g. "C:\\tmp")</p>
@@ -249,10 +328,15 @@ content (e.g. the presence of a specific code), this can be done easily by:</p> <p>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.</p>
+<p>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.</p>
<p>Boolean operations inside property based filters (like 'message contains
-"ID17" or message contains "ID18"') are currently not supported. Please note
-that it is possible to query facility and severity via property-based filters,
-but it is far more advisable to use classic selectors (see above) for those
+"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.</p>
<h2>ACTIONS</h2>
<p>The action field of a rule describes what to do with the message. In general,
@@ -271,7 +355,7 @@ in a selectore line that is above its definition. If you do this, the selector line will be ignored.</p>
<h3>Regular File</h3>
<p>Typically messages are logged to real files. The file has to be specified with
-full pathname, beginning with a slash ``/''.<br>
+full pathname, beginning with a slash "/''.<br>
<br>
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
@@ -279,7 +363,7 @@ right behind a write attempt. Nevertheless this might give you back some performance, especially if you run programs that use<br>
logging in a very verbose manner.</p>
<p>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<br>
+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. </p>
<h3>Named Pipes</h3>
<p>This version of rsyslogd(8) has support for logging output to named pipes (fifos).
@@ -306,13 +390,13 @@ it has received from the network to another host. Specify the<br> <h3>List of Users</h3>
<p>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
+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.</p>
<h3>Everyone logged on</h3>
<p>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 (``*'').</p>
+use an asterisk ("*'').</p>
<h3>Database Table</h3>
<p>This allows logging of the message to a database table. Currently, only MySQL
databases are supported. By default, a MonitorWare-compatible schema is required
@@ -329,6 +413,23 @@ template is to be used, a semicolong followed by the template name can follow the connect information. This is as follows:<br>
<br>
>dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
+<h3>Discard</h3>
+<p>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 retrive it in later configuration file lines.</p>
+<p>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.</p>
+<p>Discard is just the single tilde character with no further parameters:</p>
+<p>~</p>
+<p>For example,</p>
+<p>*.* ~</p>
+<p>discards everything (ok, you can achive the same by not running rsyslogd at
+all...).</p>
<h3>Output Channel</h3>
<p>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
|