diff options
Diffstat (limited to 'doc')
33 files changed, 180 insertions, 995 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index e175764..56176d1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -65,15 +65,8 @@ html_files = \ tls_cert_ca.jpg \ tls_cert.jpg \ tls_cert_errmsgs.html \ - rsyslog_secure_tls.html \ - tls_cert_server.html \ - tls_cert_ca.html \ - tls_cert_summary.html \ - tls_cert_machine.html \ - tls_cert_udp_relay.html \ - tls_cert_client.html \ - tls_cert_scenario.html \ rainerscript.html \ + global.html \ lookup_tables.html \ rscript_abnf.html \ rsconf1_actionexeconlywhenpreviousissuspended.html \ diff --git a/doc/Makefile.in b/doc/Makefile.in index 1e2237a..ce66409 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -310,15 +310,8 @@ html_files = \ tls_cert_ca.jpg \ tls_cert.jpg \ tls_cert_errmsgs.html \ - rsyslog_secure_tls.html \ - tls_cert_server.html \ - tls_cert_ca.html \ - tls_cert_summary.html \ - tls_cert_machine.html \ - tls_cert_udp_relay.html \ - tls_cert_client.html \ - tls_cert_scenario.html \ rainerscript.html \ + global.html \ lookup_tables.html \ rscript_abnf.html \ rsconf1_actionexeconlywhenpreviousissuspended.html \ diff --git a/doc/build_from_repo.html b/doc/build_from_repo.html index a06863e..6e018a5 100644 --- a/doc/build_from_repo.html +++ b/doc/build_from_repo.html @@ -12,17 +12,9 @@ The later may especially be the case if you are asked to try out an experimental tarball, but some files are missing because they are output files and thus do not belong into the repository. <h2>Obtaining the Source</h2> -<p>First of all, you need to download the sources. Rsyslog is currently kept in a git -repository. You can clone this repository either via http or git protocol (with the later -being much faster. URLS are: -<ul> -<li>git://git.adiscon.com/git/rsyslog.git -<li>http://git.adiscon.com/git/rsyslog.git -</ul> -<p>There is also a browsable version (gitweb) available at -<a href="http://git.adiscon.com/?p=rsyslog.git;a=summary">http://git.adiscon.com/?p=rsyslog.git;a=summary</a>. -This version also offers snapshots of each commit for easy download. You can use these if -you do not have git present on your system. +<p>First of all, you need to download the sources. Rsyslog is kept in git. The +"<a href="http://www.rsyslog.com/where-to-find-the-rsyslog-source-code/">Where to find the rsyslog +source code</a>" page on the project site will point you to the current repository location. <p>After you have cloned the repository, you are in the master branch by default. This is where we keep the devel branch. If you need any other branch, you need to do a "git checkout --track -b branch origin/branch". For example, the command to check out @@ -66,13 +58,13 @@ follows: <p><pre><code> ./configure CFLAGS="-march=i586 -mcpu=i686" --enable-imfile ... (whatever you need) </code></pre> -<p>These settings should resolve the issue . +<p>These settings should resolve the issue. <p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> <p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a> project.<br> -Copyright © 2008, 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and +Copyright © 2008-2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 3 or higher.</font></p> </body> diff --git a/doc/debug.html b/doc/debug.html index 557ca6d..229aeb0 100644 --- a/doc/debug.html +++ b/doc/debug.html @@ -160,7 +160,11 @@ enable DebugOnDemand mode only for a reason. Note that when no debug mode is ena SIGUSR1 and SIGUSR2 are completely ignored. <p>When running in any of the debug modes (including on demand mode), an interactive instance of rsyslogd can be aborted by pressing ctl-c. -<p> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/how-to-use-debug-on-demand/">How to use debug on demand</a></li> +</ul> +</p> <p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> <p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a> project.<br> diff --git a/doc/global.html b/doc/global.html new file mode 100644 index 0000000..a58f5c6 --- /dev/null +++ b/doc/global.html @@ -0,0 +1,34 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head> +<title>global() configuration object</title> +</head> + +<body> +<h1>global() configuration object</h1> + +<p>The global configuration object permits to set global parameters. +Note that each parameter can only be set once and cannot be re-set +thereafter. If a parameter is set multiple times, the behaviour is +unpredictable. + +<p>The following paramters can be set: +<ul> +<li>workDirectory +<li>dropMsgsWithMaliciousDNSPtrRecords +<li>localHostname +<li>preserveFQDN +<li>defaultNetstreamDriverCAFile +<li>defaultNetstreamDriverKeyFile +<li>defaultNetstreamDriver +<li>maxMessageSize +</ul> + +<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] +[<a href="rainerscript.html">RainerScript reference</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> +<p><font size="2">This documentation is part of the +<a href="http://www.rsyslog.com/">rsyslog</a> project.<br> +Copyright © 2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and +<a href="http://www.adiscon.com/">Adiscon</a>. +Released under ASL 2.0 or higher.</font></p> +</body> +</html> diff --git a/doc/imjournal.html b/doc/imjournal.html index a4b232e..8f29169 100644 --- a/doc/imjournal.html +++ b/doc/imjournal.html @@ -7,7 +7,7 @@ <h1>Systemd Journal Input Module</h1> <p><b>Module Name: imjournal</b></p> <p><b>Author: </b>Milan Bartos -<mbartos@redhat.com></p> +<mbartos@redhat.com> (This module is not project-supported)</p> <p><b>Description</b>:</p> <p>Provides the ability to import structured log messages from systemd journal to syslog.</p> diff --git a/doc/impstats.html b/doc/impstats.html index 8db9c6f..770f67a 100644 --- a/doc/impstats.html +++ b/doc/impstats.html @@ -24,6 +24,13 @@ settings, this impact may be noticable (for high-load environments). <p>The rsyslog website has an updated overview of available <a href="http://rsyslog.com/rsyslog-statistic-counter/">rsyslog statistic counters</a>. </p> +<p><b>Note that there is a +<a href="http://www.rsyslog.com/impstats-analyzer/">rsyslog statistics +online analyzer</a> available.</b> It can be given a impstats-generated file and +will return problems it detects. Note that the analyzer cannot replace a +human in getting things right, but it is expected to be a good aid in starting +to understand and gain information from the pstats logs. +<7p> <p><b>Module Confguration Parameters</b>:</p> <p>This module supports module parameters, only. <ul> @@ -81,6 +88,12 @@ If set to on, stats messages are emitted as structured cee-enhanced syslog. If set to off, legacy format is used (which is compatible with pre v6-rsyslog). </li> </ul> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/rsyslog-statistic-counter/">rsyslog statistics counter</a></li> +<li><a href="http://www.rsyslog.com/impstats-delayed-or-lost/">impstats delayed or lost</a> - cause and cure +</ul> +</p> <b>Caveats/Known Bugs:</b> <ul> <li>This module MUST be loaded right at the top of rsyslog.conf, otherwise diff --git a/doc/imuxsock.html b/doc/imuxsock.html index 0affe8c..123771f 100644 --- a/doc/imuxsock.html +++ b/doc/imuxsock.html @@ -94,7 +94,8 @@ burst in number of messages. Default is 200. <li><b>SysSock.RateLimit.Severity</b> [numerical severity] - specifies the severity of messages that shall be rate-limited. </li> -<li><b>SysSock.UseSysTimeStamp</b> [<b>on</b>/off] the same as $InputUnixListenSocketUseSysTimeStamp, but for the system log socket. +<li><b>SysSock.UseSysTimeStamp</b> [<b>on</b>/off] the same as the input parameter +UseSysTimeStamp, but for the system log socket. See description there. </li> <li><b>SysSock.Annotate</b> <on/<b>off</b>> turn on annotation/trusted properties for the system log socket.</li> @@ -144,7 +145,7 @@ be obtained from the log socket itself. If so, the TAG part of the message is re It is recommended to turn this option on, but the default is "off" to keep compatible with earlier versions of rsyslog. </li> <li><b>UseSysTimeStamp</b> [<b>on</b>/off] instructs imuxsock -to obtain message time from the system (via control messages) insted of using time +to obtain message time from the system (via control messages) instead of using time recorded inside the message. This may be most useful in combination with systemd. Note: this option was introduced with version 5.9.1. Due to the usefulness of it, we decided to enable it by default. As such, 5.9.1 and above behave slightly different @@ -180,7 +181,13 @@ oneself has the advantage that a limited amount of messages may be queued by the OS if rsyslog is not running. </li> </ul> - +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/what-are-trusted-properties/">What are "trusted properties"?</a></li> +<li><a href="http://www.rsyslog.com/why-does-imuxsock-not-work-on-solaris/">Why does imuxsock not work +on Solaris?</a></li> +</ul> +</p> <b>Caveats/Known Bugs:</b><br> <ul> <li>There is a compile-time limit of 50 concurrent sockets. If you need more, you need to diff --git a/doc/lookup_tables.html b/doc/lookup_tables.html index d72810f..4ef5d59 100644 --- a/doc/lookup_tables.html +++ b/doc/lookup_tables.html @@ -190,8 +190,8 @@ be sufficiently secured, e.g. via TLS mutual auth. <h2>Implementation Details</h2> <p>The lookup table functionality is implemented via highly efficient algorithms. -The string lookup is based on a parse tree and has O(1) time complexity. The array -lookup is also O(1). In case of sparseArray, we have O(log n). +The string lookup has O(log n) time complexity. The array +lookup is O(1). In case of sparseArray, we have O(log n). <p>To preserve space and, more important, increase cache hit performance, equal data values are only stored once, no matter how often a lookup index points to them. <p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] diff --git a/doc/manual.html b/doc/manual.html index dc6453b..a160ed3 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -19,7 +19,7 @@ professional services</a> available directly from the source!</p> <p><b>Please visit the <a href="http://www.rsyslog.com/sponsors">rsyslog sponsor's page</a> to honor the project sponsors or become one yourself!</b> We are very grateful for any help towards the project goals.</p> -<p><b>This documentation is for version 7.4.4 (v7.4-stable branch) of rsyslog.</b> +<p><b>This documentation is for version 7.4.8 (v7.4-stable branch) of rsyslog.</b> Visit the <i><a href="http://www.rsyslog.com/status">rsyslog status page</a></i></b> to obtain current version information and project status. </p><p><b>If you like rsyslog, you might @@ -58,7 +58,7 @@ if you do not read the doc, but doing so will definitely improve your experience <li><a href="install.html">installing rsyslog</a></li> <li><a href="build_from_repo.html">obtaining rsyslog from the source repository</a></li> <li><a href="ipv6.html">rsyslog and IPv6</a> (which is fully supported)</li> -<li><a href="rsyslog_secure_tls.html">native TLS encryption for syslog</a></li> +<li><a href="http://www.rsyslog.com/doc/rsyslog_secure_tls.html">native TLS encryption for syslog</a></li> <li><a href="multi_ruleset.html">using multiple rule sets in rsyslog</a></li> <li><a href="rsyslog_stunnel.html">ssl-encrypting syslog with stunnel</a></li> <li><a href="rsyslog_mysql.html">writing syslog messages to MySQL (and other databases as well)</a></li> diff --git a/doc/mmanon.html b/doc/mmanon.html index 16065a1..e14d75c 100644 --- a/doc/mmanon.html +++ b/doc/mmanon.html @@ -18,14 +18,7 @@ Note that anonymization will break digital signatures on the message, if they exist. <p><i>How are IP-Addresses defined?</i> <p>We assume that an IP address consists of four octets in dotted notation, -where each of the octets has a value between 0 and 255, inclusively. After -the last octet, there must be either a space or a colon. So, for example, -"1.2.3.4 Test" and "1.2.3.4:514 Test" are detected as containing valid IP -addresses, whereas this is not the case for "1.2.300.4 Test" or -"1.2.3.4-Test". The message text may contain multiple addresses. If so, -each of them is anonimized (according to the same rules). -<b>Important:</b> We may change the set of acceptable characters after -the last octet in the future, if there are good reasons to do so. +where each of the octets has a value between 0 and 255, inclusively. <p> </p> <p><b>Module Configuration Parameters</b>:</p> diff --git a/doc/mmnormalize.html b/doc/mmnormalize.html index 787bd95..8110023 100644 --- a/doc/mmnormalize.html +++ b/doc/mmnormalize.html @@ -46,6 +46,17 @@ parameter. <li>$mmnormalizeUseRawMsg <on/off> - equivalent to the "useRawMsg" parameter. </ul> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/normalizer-first-steps-for-mmnormalize/">First steps for mmnormalize</a></li> +<li><a href="http://www.rsyslog.com/log-normalization-and-special-characters/">Log normalization and +special characters</a></li> +<li><a href="http://www.rsyslog.com/log-normalization-and-the-leading-space/">Log normalization and +the leading space</a></li> +<li><a href="http://www.rsyslog.com/using-rsyslog-mmnormalize-module-effectively-with-adiscon-loganalyzer/">Using +mmnormalize effectively with Adiscon LogAnalyzer</a></li> +</ul> +</p> <b>Caveats/Known Bugs:</b> <p>None known at this time. </ul> diff --git a/doc/omfile.html b/doc/omfile.html index 7232092..0f64f26 100644 --- a/doc/omfile.html +++ b/doc/omfile.html @@ -97,6 +97,11 @@ sets a new default template for file actions.<br></li><br> </ul> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/how-to-sign-log-messages-through-signature-provider-guardtime/">Sign log messages through signature provider Guardtime</a></li> +</ul> +</p> <p><b>Caveats/Known Bugs:</b></p> <ul> <li>One needs to be careful with log rotation if signatures and/or encryption diff --git a/doc/omfwd.html b/doc/omfwd.html index 53f9e52..a541dd2 100644 --- a/doc/omfwd.html +++ b/doc/omfwd.html @@ -56,6 +56,11 @@ Permits to resend the last message when a connection is reconnected. This setting affects TCP-based syslog, only. It is most useful for traditional, plain TCP syslog. Using this protocol, it is not always possible to know which messages were successfully transmitted to the receiver when a connection breaks. In many cases, the last message sent is lost. By switching this setting to "yes", rsyslog will always retransmit the last message when a connection is reestablished. This reduces potential message loss, but comes at the price that some messages may be duplicated (what usually is more acceptable). <br></li><br> </ul> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/encrypted-disk-queues/">Encrypted Disk Queues</a></li> +</ul> +</p> <p><b>Caveats/Known Bugs:</b></p><ul><li>None.</li></ul> <p><b>Sample:</b></p> <p>The following command sends all syslog messages to a remote server via TCP port 10514.</p> diff --git a/doc/omruleset.html b/doc/omruleset.html index 41d6ccf..f0d5f7b 100644 --- a/doc/omruleset.html +++ b/doc/omruleset.html @@ -122,6 +122,11 @@ $ActionOmrulesetRulesetName nested # of course, we can have "regular" actions alongside :omrulset: actions *.* /path/to/general-message-file.log </textarea> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/rulesets-and-rsyslog-7-2/">Calling rulesets since rsyslog 7.2</a></li> +</ul> +</p> <p><b>Caveats/Known Bugs:</b> <p>The current configuration file language is not really adequate for a complex construct like omruleset. Unfortunately, more important work is currently preventing me from redoing the diff --git a/doc/property_replacer.html b/doc/property_replacer.html index 13ff41c..7218c22 100644 --- a/doc/property_replacer.html +++ b/doc/property_replacer.html @@ -746,13 +746,15 @@ use drop-cc and "drop-cc,escape-cc" will use escape-cc mode. options. It was initially introduced to support the "jsonf" option, for which it provides the capability to set an alternative field name. If it is not specified, it defaults to the property name. -<h2>Further Links</h2> +<b>See also</b> <ul> <li>Article on "<a href="rsyslog_recording_pri.html">Recording the Priority of Syslog Messages</a>" (describes use of templates to record severity and facility of a message)</li> <li><a href="rsyslog_conf.html">Configuration file format</a>, this is where you actually use the property replacer.</li> +<li><a href="http://www.rsyslog.com/what-is-the-difference-between-timereported-and-timegenerated/"> +Difference between timereported and timegenerated.</li> </ul> <p>[<a href="manual.html">manual index</a>] [<a href="rsyslog_conf.html">rsyslog.conf</a>] diff --git a/doc/queues.html b/doc/queues.html index 75b70fb..85df9fe 100644 --- a/doc/queues.html +++ b/doc/queues.html @@ -386,6 +386,11 @@ it terminates. This includes data elements there were begun being processed by workers that needed to be cancelled due to too-long processing. For a large queue, this operation may be lengthy. No timeout applies to a required shutdown save.</p> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/encrypted-disk-queues/">Encrypted Disk Queues</a></li> +</ul> +</p> [<a href="manual.html">manual index</a>] [<a href="rsyslog_conf.html">rsyslog.conf</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> diff --git a/doc/rainerscript.html b/doc/rainerscript.html index 7cbbfa9..b83184d 100644 --- a/doc/rainerscript.html +++ b/doc/rainerscript.html @@ -34,6 +34,16 @@ return a valid result, as you can't really add two letters (to concatenate them, use the concatenation operator &). However, all type conversions are automatically done by the script interpreter when there is need to do so.<br> +<h3>Constant Strings</h3> +<p>String constants are necessary in many places: comparisons, +configuration parameter values and function arguments, to name a +few important ones. +<p>In constant strings, special characters are escape by prepending a +backslash in front of them -- just in the same way this is done in the +C programming language or PHP. +<p>If in doubt how to properly escape, use the +<a href="http://www.rsyslog.com/rainerscript-constant-string-escaper/">RainerScript +String Escape Online Tool</a>. <h2>Expressions</h2> The language supports arbitrary complex expressions. All usual operators are supported. The precedence of operations is as follows @@ -51,6 +61,13 @@ of a and b should be tested as "a <> b". The "not" operator should be reserved to cases where it actually is needed to form a complex boolean expression. In those cases, parenthesis are highly recommended. +<h2>configuration objects</h2> +<h3>action()</h3> +The <a href="rsyslog_conf_actions.html">action</a> object is the primary +means of describing actions to be carried out. +<h3>global()</h3> +<p>This is used to set global configuration parameters. For details, please +see the <a href="global.html">rsyslog global configuration object</a>. <h2>Lookup Tables</h2> <p><a href="lookup_tables.html">Lookup tables</a> are a powerful construct to obtain "class" information based on message content (e.g. to build diff --git a/doc/rsyslog_conf_actions.html b/doc/rsyslog_conf_actions.html index fa240d9..50b13a0 100644 --- a/doc/rsyslog_conf_actions.html +++ b/doc/rsyslog_conf_actions.html @@ -24,9 +24,9 @@ implemented via <a href="rsyslog_conf_modules.html#om">outpout modules</a>. <li><b>type</b> string <br>Mandatory parameter for every action. The name of the module that should be used. </li> <li><b>action.writeAllMarkMessages</b> on/off - <br>Normally, mark messages are written to actions only if the action was not recently executed (by default, recently means within the past 20 minutes). If this setting is switched to "on", mark messages are always sent to actions, no matter how recently they have been executed. In this mode, mark messages can be used as a kind of heartbeat. Note that this option auto-resets to "off", so if you intend to use it with multiple actions, it must be specified in front off all selector lines that should provide this functionality. </li> + <br>Normally, mark messages are written to actions only if the action was not recently executed (by default, recently means within the past 20 minutes). If this setting is switched to "on", mark messages are always sent to actions, no matter how recently they have been executed. In this mode, mark messages can be used as a kind of heartbeat.</li> <li><b>action.execOnlyEveryNthTime</b> integer - <br>If configured, the next action will only be executed every n-th time. For example, if configured to 3, the first two messages that go into the action will be dropped, the 3rd will actually cause the action to execute, the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note: this setting is automatically re-set when the actual action is defined.</li> + <br>If configured, the next action will only be executed every n-th time. For example, if configured to 3, the first two messages that go into the action will be dropped, the 3rd will actually cause the action to execute, the 4th and 5th will be dropped, the 6th executed under the action, ... and so on.</li> <li><b>action.execOnlyEveryNthTimeout</b> integer <br>Has a meaning only if Action.ExecOnlyEveryNthTime is also configured for the same action. If so, the timeout setting specifies after which period the counting of "previous actions" expires and a new action count is begun. Specify 0 (the default) to disable timeouts. Why is this option needed? Consider this case: a message comes in at, eg., 10am. That's count 1. Then, nothing happens for the next 10 hours. At 8pm, the next one occurs. That's count 2. Another 5 hours later, the next message occurs, bringing the total count to 3. Thus, this message now triggers the rule. @@ -35,10 +35,19 @@ The question is if this is desired behavior? Or should the rule only be triggere <br>This directive will timeout previous messages seen if they are older than 20 minutes. In the example above, the count would now be always 1 and consequently no rule would ever be triggered. </li> <li><b>action.execOnlyOnceEveryInterval</b> integer <br>Execute action only if the last execute is at last <seconds> seconds in the past (more info in ommail, but may be used with any action)</li> - <li><b>action.execOnlyWhenpReviousIsSuspended</b> on/off - <br>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).</li> + <li><b>action.execOnlyWhenPreviousIsSuspended</b> on/off + <br>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).<br> + Note, however, that a failed action may not immediately be detected. For more information, see the + <a href="http://www.rsyslog.com/action-execonlywhenpreviousissuspended-preciseness/">rsyslog + execOnlyWhenPreviousIsSpuspended preciseness</a> FAQ article. + </li> <li><b>action.repeatedmsgcontainsoriginalmsg</b> on/off - <br>"last message repeated n times" messages, if generated, have a different format that contains the message that is being repeated. Note that only the first "n" characters are included, with n to be at least 80 characters, most probably more (this may change from version to version, thus no specific limit is given). The bottom line is that n is large enough to get a good idea which message was repeated but it is not necessarily large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.</li> + <br>"last message repeated n times" messages, if generated, have a different format that contains the message that is being repeated. Note that only the first "n" characters are included, with n to be at least 80 characters, most probably more (this may change from version to version, thus no specific limit is given). The bottom line is that n is large enough to get a good idea which message was repeated but it is not necessarily large enough for the whole message. (Introduced with 4.1.5).</li> <li><b>action.resumeRetryCount</b> integer <br>[default 0, -1 means eternal]</li> <li><b>action.resumeInterval</b> integer diff --git a/doc/rsyslog_conf_filter.html b/doc/rsyslog_conf_filter.html index a795193..c8a40b6 100644 --- a/doc/rsyslog_conf_filter.html +++ b/doc/rsyslog_conf_filter.html @@ -275,6 +275,11 @@ 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> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/filter-optimization-with-arrays/">Filter optimization with arrays</a></li> +</ul> +</p> <p>[<a href="manual.html">manual index</a>] [<a href="rsyslog_conf.html">rsyslog.conf</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> diff --git a/doc/rsyslog_conf_templates.html b/doc/rsyslog_conf_templates.html index 9a6e161..562aa9a 100644 --- a/doc/rsyslog_conf_templates.html +++ b/doc/rsyslog_conf_templates.html @@ -288,8 +288,8 @@ Note that the template string itself must be on a single line. <h4>Standard Template for Forwarding to a Remote Host (RFC3164 mode)</h4> <p><pre><code>template(name="ForwardFormat" type="list") { constant(value="<") - property(name="PRI") - constant(value="<") + property(name="pri") + constant(value=">") property(name="timestamp" dateFormat="rfc3339") constant(value=" ") property(name="hostname") @@ -524,7 +524,13 @@ $template TraditionalForwardFormat,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag:1:3 <br><br> $template StdSQLFormat,"insert into SystemEvents (Message, Facility, FromHost, Priority, DeviceReportedTime, ReceivedAt, InfoUnitID, SysLogTag) values ('%msg%', %syslogfacility%, '%HOSTNAME%', %syslogpriority%, '%timereported:::date-mysql%', '%timegenerated:::date-mysql%', %iut%, '%syslogtag%')",SQL </code></p> - +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/how-to-bind-a-template/">How to bind a template</a></li> +<li><a href="http://www.rsyslog.com/adding-the-bom-to-a-message/">Adding the BOM to a message</a></li> +<li><a href="http://www.rsyslog.com/article60/">How to separate log files by host name of the sending device</a></li> +</ul> +</p> <p>[<a href="manual.html">manual index</a>] [<a href="rsyslog_conf.html">rsyslog.conf</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> diff --git a/doc/rsyslog_packages.html b/doc/rsyslog_packages.html index 5bb62fa..014791a 100644 --- a/doc/rsyslog_packages.html +++ b/doc/rsyslog_packages.html @@ -81,5 +81,10 @@ of the distribution name. <p>If you do not find a suitable package for your distribution, there is no reason to panic. It is quite simple to install rsyslog from the source tarball, so you should consider that. +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/how-to-use-the-ubuntu-repository/">How to use the Ubuntu repository</a></li> +</ul> +</p> </body> </html> diff --git a/doc/rsyslog_secure_tls.html b/doc/rsyslog_secure_tls.html deleted file mode 100644 index b15e5a4..0000000 --- a/doc/rsyslog_secure_tls.html +++ /dev/null @@ -1,127 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: recommended scenario</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-06-17)</i></small></p> -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -<li><a href="tls_cert_errmsgs.html">Frequently seen Error Messages</a> -</ul> - -<h2>Overview</h2> -<p>This document describes a secure way to set up rsyslog TLS. A secure logging -environment requires more than just encrypting the transmission channel. This document -provides one possible way to create such a secure system. -<p>Rsyslog's TLS authentication can be used very flexible and thus supports a -wide range of security policies. This section tries to give some advise on a -scenario that works well for many environments. However, it may not be suitable -for you - please assess you security needs before using the recommendations -below. Do not blame us if it doesn't provide what you need ;)</p> -<p>Our policy offers these security benefits:</p> -<ul> - <li>syslog messages are encrypted while traveling on the wire</li> - <li>the syslog sender authenticates to the syslog receiver; thus, the - receiver knows who is talking to it</li> - <li>the syslog receiver authenticates to the syslog sender; thus, the sender - can check if it indeed is sending to the expected receiver</li> - <li>the mutual authentication prevents man-in-the-middle attacks</li> -</ul> -<p>Our secrity goals are achived via public/private key security. As such, it is -vital that private keys are well protected and not accessible to third parties. -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -If private keys have become known to third parties, the system does not provide -any security at all. Also, our solution bases on X.509 certificates and a (very -limited) chain of trust. We have one instance (the CA) that issues all machine -certificates. The machine certificate indentifies a particular machine. hile in -theory (and practice), there could be several "sub-CA" that issues machine -certificates for a specific adminitrative domain, we do not include this in our -"simple yet secure" setup. If you intend to use this, rsyslog supports it, but -then you need to dig a bit more into the documentation (or use the forum to ask). -In general, if you depart from our simple model, you should have good reasons -for doing so and know quite well what you are doing - otherwise you may -compromise your system security.</p> -<p>Please note that security never comes without effort. In the scenario -described here, we have limited the effort as much as possible. What remains is -some setup work for the central CA, the certificate setup for each machine as -well as a few configuration commands that need to be applied to all of them. -Proably the most important limiting factor in our setup is that all senders and -receivers must support IETF's syslog-transport-tls standard (which is not -finalized yet). We use mandatory-to-implement technology, yet you may have -trouble finding all required features in some implementations. More often, -unfortunately, you will find that an implementation does not support the -upcoming IETF standard at all - especially in the "early days" (starting May -2008) when rsyslog is the only implementation of said standard.</p> -<p>Fortunately, rsyslog supports allmost every protocol that is out there in the -syslog world. So in cases where transport-tls is not available on a sender, we -recommend to use rsyslog as the initial relay. In that mode, the not-capabe -sender sends to rsyslog via another protocol, which then relays the message via -transport-tls to either another interim relay or the final destination (which, -of course, must by transport-tls capable). In such a scenario, it is best to try -see what the sender support. Maybe it is possible to use industry-standard plain -tcp syslog with it. Often you can even combine it with stunnel, which then, too, -enables a secure delivery to the first rsyslog relay. If all of that is not -possible, you can (and often must...) resort to UDP. Even though this is now -lossy and insecure, this is better than not having the ability to listen to that -device at all. It may even be reasonale secure if the uncapable sender and the -first rsyslog relay communicate via a private channel, e.g. a dedicated network -link.</p> -<p>One final word of caution: transport-tls protects the connection between the -sender and the receiver. It does not necessarily protect against attacks that -are present in the message itself. Especially in a relay environment, the -message may have been originated from a malicious system, which placed invalid -hostnames and/or other content into it. If there is no provisioning against such -things, these records may show up in the receivers' repository. -transport-tls -does not protect against this (but it may help, properly used). Keep in mind -that syslog-transport-tls provides hop-by-hop security. It does not provide -end-to-end security and it does not authenticate the message itself (just the -last sender).</p> -<h3>A very quick Intro</h3> -<p>If you'd like to get all information very rapidly, the graphic below contains -everything you need to know (from the certificate perspective) in a very condensed -manner. It is no surprise if the graphic puzzles you. In this case, <a href="tls_cert_scenario.html">simply read on</a> -for full instructions. -<p> -<img align="center" alt="TLS/SSL protected syslog" src="tls_cert.jpg"> -<h3>Feedback requested</h3> -<p>I would appreciate feedback on this tutorial. If you have -additional ideas, comments or find bugs (I *do* bugs - no way... ;)), -please -<a href="mailto:rgerhards@adiscon.com">let me know</a>.</p> -<h2>Revision History</h2> -<ul> -<li>2008-06-06 * <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> * Initial Version created</li> -<li>2008-06-18 * <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> * Greatly enhanced and modularized the doc</li> -</ul> -<h2>Copyright</h2> -<p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/rsyslog_tls.html b/doc/rsyslog_tls.html index 286660d..de03db0 100644 --- a/doc/rsyslog_tls.html +++ b/doc/rsyslog_tls.html @@ -23,7 +23,7 @@ have found the right spot.</p> <p>This is a quick guide. There is a more elaborate guide currently under construction which provides a much more secure environment. It is highly recommended to -<a href="rsyslog_secure_tls.html">at least have a look at it</a>. +<a href="http://www.rsyslog.com/doc/rsyslog_secure_tls.html">at least have a look at it</a>. <h2>Background</h2> <p><b>Traditional syslog is a clear-text protocol. That means anyone with a sniffer can have a peek at your data.</b> In diff --git a/doc/sigprov_gt.html b/doc/sigprov_gt.html index caeee11..5ffd26d 100644 --- a/doc/sigprov_gt.html +++ b/doc/sigprov_gt.html @@ -64,6 +64,12 @@ sig.keepRecordHashes requries). Note that both Tree and Record hashes can be kept inside the signature file. </li> </ul> +<p><b>See Also</b> +<ul> +<li><a href="http://www.rsyslog.com/how-to-sign-log-messages-through-signature-provider-guardtime/">How +to sign log messages through signature provider Guardtime</a></li> +</ul> +</p> <b>Caveats/Known Bugs:</b> <ul> <li>currently none known diff --git a/doc/tls_cert_ca.html b/doc/tls_cert_ca.html deleted file mode 100644 index 2cae404..0000000 --- a/doc/tls_cert_ca.html +++ /dev/null @@ -1,168 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: scenario</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-06-17)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -</ul> - -<h3>Setting up the CA</h3> -<p>The first step is to set up a certificate authority (CA). It must be -maintained by a trustworthy person (or group) and approves the indentities of -all machines. It does so by issuing their certificates. In a small setup, the -administrator can provide the CA function. What is important is the the CA's -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -private key is well-protocted and machine certificates are only issued if it is -know they are valid (in a single-admin case that means the admin should not -issue certificates to anyone else except himself).</p> -<p>The CA creates a so-called self-signed certificate. That is, it approves its -own authenticy. This sounds useless, but the key point to understand is that -every machine will be provided a copy of the CA's certificate. Accepting this -certificate is a matter of trust. So by configuring the CA certificate, the -administrator tells <a href="http://www.rsyslog.com">rsyslog</a> which certificates to trust. This is the root of all -trust under this model. That is why the CA's private key is so important - -everyone getting hold of it is trusted by our rsyslog instances.</p> -<center><img src="tls_cert_ca.jpg"></center> -<p>To create a self-signed certificate, use the following commands with GnuTLS (which -is currently the only supported TLS library, what may change in the future). -Please note that GnuTLS' tools are not installed by default on many platforms. Also, -the tools do not necessarily come with the GnuTLS core package. If you do not -have certtool on your system, check if there is package for the GnuTLS tools available -(under Fedora, for example, this is named gnutls-utils-<version> and -it is NOT installed by default). </p> -<ol> -<li>generate the private key: -<pre>certtool --generate-privkey --outfile ca-key.pem</pre> -<br> -This takes a short while. Be sure to do some work on your workstation, -it waits for radom input. Switching between windows is sufficient ;) -</li> -<li>now create the (self-signed) CA certificate itself:<br> -<pre>certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem</pre> -This generates the CA certificate. This command queries you for a -number of things. Use appropriate responses. When it comes to -certificate validity, keep in mind that you need to recreate all -certificates when this one expires. So it may be a good idea to use a -long period, eg. 3650 days (roughly 10 years). You need to specify that -the certificates belongs to an authority. The certificate is used to -sign other certificates.<br> -</li> -</ol> -<h3>Sample Screen Session</h3> -<p>Text in red is user input. Please note that for some questions, there is no -user input given. This means the default was accepted by simply pressing the -enter key. -<code><pre> -[root@rgf9dev sample]# <font color="red">certtool --generate-privkey --outfile ca-key.pem --bits 2048</font> -Generating a 2048 bit RSA private key... -[root@rgf9dev sample]# <font color="red">certtool --generate-self-signed --load-privkey ca-key.pem --outfile ca.pem</font> -Generating a self signed certificate... -Please enter the details of the certificate's distinguished name. Just press enter to ignore a field. -Country name (2 chars): <font color="red">US</font> -Organization name: <font color="red">SomeOrg</font> -Organizational unit name: <font color="red">SomeOU</font> -Locality name: <font color="red">Somewhere</font> -State or province name: <font color="red">CA</font> -Common name: <font color="red">someName (not necessarily DNS!)</font> -UID: -This field should not be used in new certificates. -E-mail: -Enter the certificate's serial number (decimal): - - -Activation/Expiration time. -The certificate will expire in (days): <font color="red">3650</font> - - -Extensions. -Does the certificate belong to an authority? (Y/N): <font color="red">y</font> -Path length constraint (decimal, -1 for no constraint): -Is this a TLS web client certificate? (Y/N): -Is this also a TLS web server certificate? (Y/N): -Enter the e-mail of the subject of the certificate: <font color="red">someone@example.net</font> -Will the certificate be used to sign other certificates? (Y/N): <font color="red">y</font> -Will the certificate be used to sign CRLs? (Y/N): -Will the certificate be used to sign code? (Y/N): -Will the certificate be used to sign OCSP requests? (Y/N): -Will the certificate be used for time stamping? (Y/N): -Enter the URI of the CRL distribution point: -X.509 Certificate Information: - Version: 3 - Serial Number (hex): 485a365e - Validity: - Not Before: Thu Jun 19 10:35:12 UTC 2008 - Not After: Sun Jun 17 10:35:25 UTC 2018 - Subject: C=US,O=SomeOrg,OU=SomeOU,L=Somewhere,ST=CA,CN=someName (not necessarily DNS!) - Subject Public Key Algorithm: RSA - Modulus (bits 2048): - d9:9c:82:46:24:7f:34:8f:60:cf:05:77:71:82:61:66 - 05:13:28:06:7a:70:41:bf:32:85:12:5c:25:a7:1a:5a - 28:11:02:1a:78:c1:da:34:ee:b4:7e:12:9b:81:24:70 - ff:e4:89:88:ca:05:30:0a:3f:d7:58:0b:38:24:a9:b7 - 2e:a2:b6:8a:1d:60:53:2f:ec:e9:38:36:3b:9b:77:93 - 5d:64:76:31:07:30:a5:31:0c:e2:ec:e3:8d:5d:13:01 - 11:3d:0b:5e:3c:4a:32:d8:f3:b3:56:22:32:cb:de:7d - 64:9a:2b:91:d9:f0:0b:82:c1:29:d4:15:2c:41:0b:97 - Exponent: - 01:00:01 - Extensions: - Basic Constraints (critical): - Certificate Authority (CA): TRUE - Subject Alternative Name (not critical): - RFC822name: someone@example.net - Key Usage (critical): - Certificate signing. - Subject Key Identifier (not critical): - fbfe968d10a73ae5b70d7b434886c8f872997b89 -Other Information: - Public Key Id: - fbfe968d10a73ae5b70d7b434886c8f872997b89 - -Is the above information ok? (Y/N): <font color="red">y</font> - - -Signing certificate... -[root@rgf9dev sample]# <font color="red">chmod 400 ca-key.pem</font> -[root@rgf9dev sample]# <font color="red">ls -l</font> -total 8 --r-------- 1 root root 887 2008-06-19 12:33 ca-key.pem --rw-r--r-- 1 root root 1029 2008-06-19 12:36 ca.pem -[root@rgf9dev sample]# -</pre></code> -<p><font color="red"><b>Be sure to safeguard ca-key.pem!</b> Nobody except the CA itself -needs to have it. If some third party obtains it, you security is broken!</font> -<h2>Copyright</h2> -<p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/tls_cert_client.html b/doc/tls_cert_client.html deleted file mode 100644 index dbe7961..0000000 --- a/doc/tls_cert_client.html +++ /dev/null @@ -1,91 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: client setup</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-07-03)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -</ul> - -<h3>Setting up a client</h3> -<p>In this step, we configure a client machine. We from our scenario, we use -zuse.example.net. You need to do the same steps for all other clients, too (in the -example, that meanst turng.example.net). The client check's the server's identity and -talks to it only if it is the expected server. This is a very important step. -Without it, you would not detect man-in-the-middle attacks or simple malicious servers -who try to get hold of your valuable log data. -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -<p><center><img src="tls_cert_100.jpg"></center> -<p>Steps to do: -<ul> -<li>make sure you have a functional CA (<a href="tls_cert_ca.html">Setting up the CA</a>) -<li>generate a machine certificate for zuse.example.net (follow instructions in - <a href="tls_cert_machine.html">Generating Machine Certificates</a>) -<li>make sure you copy over ca.pem, machine-key.pem ad machine-cert.pem to the client. -Ensure that no user except root can access them (<b>even read permissions are really bad</b>). -<li>configure the client so that it checks the server identity and sends messages only -if the server identity is known. Please note that you have the same options as when -configuring a server. However, we now use a single name only, because there is only one -central server. No using wildcards make sure that we will exclusively talk to that server -(otherwise, a compromised client may take over its role). If you load-balance to different -server identies, you obviously need to allow all of them. It still is suggested to use -explcit names. -</ul> -<p><b>At this point, please be reminded once again that your security needs may be quite different from -what we assume in this tutorial. Evaluate your options based on your security needs.</b> -<h3>Sample syslog.conf</h3> -<p>Keep in mind that this rsyslog.conf sends messages via TCP, only. Also, we do not -show any rules to write local files. Feel free to add them. -<code><pre> -# make gtls driver the default -$DefaultNetstreamDriver gtls - -# certificate files -$DefaultNetstreamDriverCAFile /rsyslog/protected/ca.pem -$DefaultNetstreamDriverCertFile /rsyslog/protected/machine-cert.pem -$DefaultNetstreamDriverKeyFile /rsyslog/protected/machine-key.pem - -$ActionSendStreamDriverAuthMode x509/name -$ActionSendStreamDriverPermittedPeer central.example.net -$ActionSendStreamDriverMode 1 # run driver in TLS-only mode -*.* @@central.example.net:10514 # forward everything to remote server -</pre></code> -<p>Note: the example above forwards every message to the remote server. Of course, -you can use the normal filters to restrict the set of information that is sent. -Depending on your message volume and needs, this may be a smart thing to do. -<p><font color="red"><b>Be sure to safeguard at least the private key (machine-key.pem)!</b> -If some third party obtains it, you security is broken!</font> -<h2>Copyright</h2> -<p>Copyright © 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/tls_cert_machine.html b/doc/tls_cert_machine.html deleted file mode 100644 index 095e15c..0000000 --- a/doc/tls_cert_machine.html +++ /dev/null @@ -1,182 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: generating the machine certificate</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-06-18)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -</ul> - -<h3>generating the machine certificate</h3> -<p>In this step, we generate certificates for each of the machines. Please note -that both clients and servers need certificates. The certificate identifies each -machine to the remote peer. The DNSName specified inside the certificate can -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -be specified inside the $<object>PermittedPeer config statements. -<p>For now, we assume that a single person (or group) is responsible for the whole -rsyslog system and thus it is OK if that single person is in posession of all -machine's private keys. This simplification permits us to use a somewhat less -complicated way of generating the machine certificates. So, we generate both the private -and public key on the CA (which is NOT a server!) and then copy them over to the -respective machines. -<p>If the roles of machine and CA administrators are split, the private key must -be generated by the machine administrator. This is done via a certificate request. -This request is then sent to the CA admin, which in turn generates the certificate -(containing the public key). The CA admin then sends back the certificate to the -machine admin, who installs it. That way, the CA admin never get's hold of the -machine's private key. Instructions for this mode will be given in a later revision -of this document. -<p><b>In any case, it is vital that the machine's private key is protected. Anybody -able to obtain that private key can imporsonate as the machine to which it belongs, thus -breaching your security.</b> -<h3>Sample Screen Session</h3> -<p>Text in red is user input. Please note that for some questions, there is no -user input given. This means the default was accepted by simply pressing the -enter key. -<p><b>Please note:</b> you need to substitute the names specified below with values -that match your environment. Most importantly, machine.example.net must be replaced -by the actual name of the machine that will be using this certificate. For example, -if you generate a certificate for a machine named "server.example.com", you need -to use that name. If you generate a certificate for "client.example.com", you need -to use this name. Make sure that each machine certificate has a unique name. If not, -you can not apply proper access control. -<code><pre> -[root@rgf9dev sample]# <font color="red">certtool --generate-privkey --outfile key.pem --bits 2048</font> -Generating a 2048 bit RSA private key... -[root@rgf9dev sample]# <font color="red">certtool --generate-request --load-privkey key.pem --outfile request.pem</font> -Generating a PKCS #10 certificate request... -Country name (2 chars): <font color="red">US</font> -Organization name: <font color="red">SomeOrg</font> -Organizational unit name: <font color="red">SomeOU</font> -Locality name: <font color="red">Somewhere</font> -State or province name: <font color="red">CA</font> -Common name: <font color="red">machine.example.net</font> -UID: -Enter a dnsName of the subject of the certificate: -Enter the IP address of the subject of the certificate: -Enter the e-mail of the subject of the certificate: -Enter a challange password: -Does the certificate belong to an authority? (y/N): <font color="red">n</font> -Will the certificate be used for signing (DHE and RSA-EXPORT ciphersuites)? (y/N): -Will the certificate be used for encryption (RSA ciphersuites)? (y/N): -Is this a TLS web client certificate? (y/N): <font color="red">y</font> -Is this also a TLS web server certificate? (y/N): <font color="red">y</font> -[root@rgf9dev sample]# <font color="red">certtool --generate-certificate --load-request request.pem --outfile cert.pem --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem</font> -Generating a signed certificate... -Enter the certificate's serial number (decimal): - - -Activation/Expiration time. -The certificate will expire in (days): 1000 - - -Extensions. -Do you want to honour the extensions from the request? (y/N): -Does the certificate belong to an authority? (Y/N): <font color="red">n</font> -Is this a TLS web client certificate? (Y/N): <font color="red">y</font> -Is this also a TLS web server certificate? (Y/N): <font color="red">y</font> -Enter the dnsName of the subject of the certificate: <font color="red">machine.example.net</font> <i>{This is the name of the machine that will use the certificate}</i> -Enter the IP address of the subject of certificate: -Will the certificate be used for signing (DHE and RSA-EXPORT ciphersuites)? (Y/N): -Will the certificate be used for encryption (RSA ciphersuites)? (Y/N): -X.509 Certificate Information: - Version: 3 - Serial Number (hex): 485a3819 - Validity: - Not Before: Thu Jun 19 10:42:54 UTC 2008 - Not After: Wed Mar 16 10:42:57 UTC 2011 - Subject: C=US,O=SomeOrg,OU=SomeOU,L=Somewhere,ST=CA,CN=machine.example.net - Subject Public Key Algorithm: RSA - Modulus (bits 2048): - b2:4e:5b:a9:48:1e:ff:2e:73:a1:33:ee:d8:a2:af:ae - 2f:23:76:91:b8:39:94:00:23:f2:6f:25:ad:c9:6a:ab - 2d:e6:f3:62:d8:3e:6e:8a:d6:1e:3f:72:e5:d8:b9:e0 - d0:79:c2:94:21:65:0b:10:53:66:b0:36:a6:a7:cd:46 - 1e:2c:6a:9b:79:c6:ee:c6:e2:ed:b0:a9:59:e2:49:da - c7:e3:f0:1c:e0:53:98:87:0d:d5:28:db:a4:82:36:ed - 3a:1e:d1:5c:07:13:95:5d:b3:28:05:17:2a:2b:b6:8e - 8e:78:d2:cf:ac:87:13:15:fc:17:43:6b:15:c3:7d:b9 - Exponent: - 01:00:01 - Extensions: - Basic Constraints (critical): - Certificate Authority (CA): FALSE - Key Purpose (not critical): - TLS WWW Client. - TLS WWW Server. - Subject Alternative Name (not critical): - DNSname: machine.example.net - Subject Key Identifier (not critical): - 0ce1c3dbd19d31fa035b07afe2e0ef22d90b28ac - Authority Key Identifier (not critical): - fbfe968d10a73ae5b70d7b434886c8f872997b89 -Other Information: - Public Key Id: - 0ce1c3dbd19d31fa035b07afe2e0ef22d90b28ac - -Is the above information ok? (Y/N): <font color="red">y</font> - - -Signing certificate... -[root@rgf9dev sample]# <font color="red">rm -f request.pem</font> -[root@rgf9dev sample]# <font color="red">ls -l</font> -total 16 --r-------- 1 root root 887 2008-06-19 12:33 ca-key.pem --rw-r--r-- 1 root root 1029 2008-06-19 12:36 ca.pem --rw-r--r-- 1 root root 1074 2008-06-19 12:43 cert.pem --rw-r--r-- 1 root root 887 2008-06-19 12:40 key.pem -[root@rgf9dev sample]# # it may be a good idea to rename the files to indicate where they belong to -[root@rgf9dev sample]# <font color="red">mv cert.pem machine-cert.pem</font> -[root@rgf9dev sample]# <font color="red">mv key.pem machine-key.pem</font> -[root@rgf9dev sample]# -</pre></code> -<h3>Distributing Files</h3> -<p>Provide the machine with: -<ul> -<li>a copy of ca.pem -<li>cert.pem -<li>key.pem -</ul> -<p>This is how the relevant part of rsyslog.conf looks on the target machine: -<p> -<code><pre> -$DefaultNetstreamDriverCAFile /home/rger/proj/rsyslog/sample/ca.pem -$DefaultNetstreamDriverCertFile /home/rger/proj/rsyslog/sample/machine-cert.pem -$DefaultNetstreamDriverKeyFile /home/rger/proj/rsyslog/sample/machine-key.pem -</pre></code> -<p><b><font color="red">Never</font> provide anyone with ca-key.pem!</b> Also, make sure -nobody but the machine in question gets hold of key.pem. -<h2>Copyright</h2> -<p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/tls_cert_scenario.html b/doc/tls_cert_scenario.html deleted file mode 100644 index 7973532..0000000 --- a/doc/tls_cert_scenario.html +++ /dev/null @@ -1,63 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: scenario</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-06-17)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -<li><a href="tls_cert_errmsgs.html">Frequently seen Error Messages</a> -</ul> - -<h3>Sample Scenario</h3> -<p>We have a quite simple scenario. There is one central syslog server, -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -named central.example.net. These server is being reported to by two Linux -machines with name zuse.example.net and turing.example.net. Also, there is a -third client - ada.example.net - which send both its own messages to the central -server but also forwards messages receive from an UDP-only capable router. We -hav decided to use ada.example.net because it is in the same local network -segment as the router and so we enjoy TLS' security benefits for forwarding the -router messages inside the corporate network. All systems (except the router) use -<a href="http://www.rsyslog.com/">rsyslog</a> as the syslog software.</p> -<p><center><img src="tls_cert_100.jpg"></center> -<p>Please note that the CA must not necessarily be connected to the rest of the -network. Actually, it may be considered a security plus if it is not. If the CA -is reachable via the regular network, it should be sufficiently secured (firewal -rules et al). Keep in mind that if the CA's security is breached, your overall -system security is breached. -<p>In case the CA is compromised, you need to regenerate the CA's certificate as well -as all individual machines certificates. -<h2>Copyright</h2> -<p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/tls_cert_server.html b/doc/tls_cert_server.html deleted file mode 100644 index 9c024bc..0000000 --- a/doc/tls_cert_server.html +++ /dev/null @@ -1,127 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: central server setup</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-06-18)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -</ul> - -<h3>Setting up the Central Server</h3> -<p>In this step, we configure the central server. We assume it accepts messages only -via TLS protected plain tcp based syslog from those peers that are explicitely permitted -to send to it. The picture below show our configuration. This step configures -the server central.example.net. -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -<p><center><img src="tls_cert_100.jpg"></center> -<p><i><font color="red"><b>Important:</b> Keep in mind that the order of configuration directives -is very important in rsyslog. As such, the samples given below do only work if the given -order is preserved.</font> Re-ordering the directives can break configurations and has broken them -in practice. If you intend to re-order them, please be sure that you fully understand how -the configuration language works and, most importantly, which statements form a block together. -Please also note that we understand the the current configuration file format is -ugly. However, there has been more important work in the way of enhancing it. If you would like -to contribute some time to improve the config file language, please let us know. Any help -is appreciated (be it doc or coding work!).</i> -<p>Steps to do: -<ul> -<li>make sure you have a functional CA (<a href="tls_cert_ca.html">Setting up the CA</a>) -<li>generate a machine certificate for central.example.net (follow instructions in - <a href="tls_cert_machine.html">Generating Machine Certificates</a>) -<li>make sure you copy over ca.pem, machine-key.pem ad machine-cert.pem to the central server. -Ensure that no user except root can access them (<b>even read permissions are really bad</b>). -<li>configure the server so that it accepts messages from all machines in the -example.net domain that have certificates from your CA. Alternatively, you may also -precisely define from which machine names messages are accepted. See sample rsyslog.conf -below. -</ul> -In this setup, we use wildcards to ease adding new systems. We permit the server to accept -messages from systems whos names match *.example.net. -<pre><code> -$InputTCPServerStreamDriverPermittedPeer *.example.net -</code></pre> -This will match zuse.example.net and -turing.example.net, but NOT pascal.otherdepartment.example.net. If the later would be desired, -you can (and need) to include additional permitted peer config statments: -<pre><code> -$InputTCPServerStreamDriverPermittedPeer *.example.net -$InputTCPServerStreamDriverPermittedPeer *.otherdepartment.example.net -$InputTCPServerStreamDriverPermittedPeer *.example.com -</code></pre> -<p>As can be seen with example.com, the different permitted peers need NOT to be in a single -domain tree. Also, individual machines can be configured. For example, if only zuse, turing -and ada should be able to talk to the server, you can achive this by: -<pre><code> -$InputTCPServerStreamDriverPermittedPeer zuse.example.net -$InputTCPServerStreamDriverPermittedPeer turing.example.net -$InputTCPServerStreamDriverPermittedPeer ada.example.net -</code></pre> -<p>As an extension to the (upcoming) IETF syslog/tls standard, you can specify some text -together with a domain component wildcard. So "*server.example.net", "server*.example.net" -are valid permitted peers. However "server*Fix.example.net" is NOT a valid wildcard. The -IETF standard permits no text along the wildcards. -<p>The reason we use wildcards in the default setup is that it makes it easy to add systems -without the need to change the central server's configuration. It is important to understand that -the central server will accept names <b>only</b> (no exception) if the client certificate was -signed by the CA we set up. So if someone tries to create a malicious certificate with -a name "zuse.example.net", the server will <b>not</b> accept it. So a wildcard is safe -as long as you ensure CA security is not breached. Actually, you authorize a client by issuing -the certificate to it. -<p><b>At this point, please be reminded once again that your security needs may be quite different from -what we assume in this tutorial. Evaluate your options based on your security needs.</b> -<h3>Sample syslog.conf</h3> -<p>Keep in mind that this rsyslog.conf accepts messages via TCP, only. The only other -source accepted is messages from the server itself. -<code><pre> -$ModLoad imuxsock # local messages -$ModLoad imtcp # TCP listener - -# make gtls driver the default -$DefaultNetstreamDriver gtls - -# certificate files -$DefaultNetstreamDriverCAFile /rsyslog/protected/ca.pem -$DefaultNetstreamDriverCertFile /rsyslog/protected/machine-cert.pem -$DefaultNetstreamDriverKeyFile /rsyslog/protected/machine-key.pem - -$InputTCPServerStreamDriverAuthMode x509/name -$InputTCPServerStreamDriverPermittedPeer *.example.net -$InputTCPServerStreamDriverMode 1 # run driver in TLS-only mode -$InputTCPServerRun 10514 # start up listener at port 10514 -</pre></code> -<p><font color="red"><b>Be sure to safeguard at least the private key (machine-key.pem)!</b> -If some third party obtains it, you security is broken!</font> -<h2>Copyright</h2> -<p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/tls_cert_summary.html b/doc/tls_cert_summary.html deleted file mode 100644 index 8e003bc..0000000 --- a/doc/tls_cert_summary.html +++ /dev/null @@ -1,66 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: Summary</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-07-03)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -</ul> - -<h3>Summary</h3> -<p>If you followed the steps outlined in this documentation set, you now have -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -a reasonable (for most needs) secure setup for the following environment: -<center><img src="tls_cert_100.jpg"></center> -<p>You have learned about the security decisions involved and which we -made in this example. <b>Be once again reminded that you must make sure yourself -that whatever you do matches your security needs!</b> There is no guarantee that -what we generally find useful actually is. It may even be totally unsuitable for -your environment. -<p>In the example, we created a rsyslog certificate authority (CA). Guard the CA's -files. You need them whenever you need to create a new machine certificate. We also saw how -to generate the machine certificates themselfs and distribute them to the individual -machines. Also, you have found some configuration samples for a sever, a client and -a syslog relay. Hopefully, this will enable you to set up a similar system in many -environments. -<p>Please be warned that you defined some expiration dates for the certificates. -After they are reached, the certificates are no longer valid and rsyslog will NOT -accept them. At that point, syslog messages will no longer be transmitted (and rsyslogd -will heavily begin to complain). So it is a good idea to make sure that you renew the -certificates before they expire. Recording a reminder somewhere is probably a good -idea. -<p>If you have any more questions, please visit the <a href="http://kb.monitorware.com/rsyslog-f40.html">rsyslog forum</a> and simply ask ;) -<h2>Copyright</h2> -<p>Copyright (c) 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/tls_cert_udp_relay.html b/doc/tls_cert_udp_relay.html deleted file mode 100644 index f4740ce..0000000 --- a/doc/tls_cert_udp_relay.html +++ /dev/null @@ -1,105 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>TLS-protected syslog: UDP relay setup</title> -</head> -<body> - -<h1>Encrypting Syslog Traffic with TLS (SSL)</h1> -<p><small><i>Written by <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> (2008-07-03)</i></small></p> - -<ul> -<li><a href="rsyslog_secure_tls.html">Overview</a> -<li><a href="tls_cert_scenario.html">Sample Scenario</a> -<li><a href="tls_cert_ca.html">Setting up the CA</a> -<li><a href="tls_cert_machine.html">Generating Machine Certificates</a> -<li><a href="tls_cert_server.html">Setting up the Central Server</a> -<li><a href="tls_cert_client.html">Setting up syslog Clients</a> -<li><a href="tls_cert_udp_relay.html">Setting up the UDP syslog relay</a> -<li><a href="tls_cert_summary.html">Wrapping it all up</a> -</ul> - -<h3>Setting up the UDP syslog relay</h3> -<p>In this step, we configure the UDP relay ada.example.net. -As a reminder, that machine relays messages from a local router, which only -supports UDP syslog, to the central syslog server. The router does not talk -directly to it, because we would like to have TLS protection for its sensitve -logs. If the router and the syslog relay are on a sufficiently secure private -network, this setup can be considered reasonable secure. In any case, it is the -best alternative among the possible configuration scenarios. -<span style="float: left"> -<script type="text/javascript"><!-- -google_ad_client = "pub-3204610807458280"; -/* rsyslog doc inline */ -google_ad_slot = "5958614527"; -google_ad_width = 125; -google_ad_height = 125; -//--> -</script> -<script type="text/javascript" -src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> -</script> -</span> -<p><center><img src="tls_cert_100.jpg"></center> -<p>Steps to do: -<ul> -<li>make sure you have a functional CA (<a href="tls_cert_ca.html">Setting up the CA</a>) -<li>generate a machine certificate for ada.example.net (follow instructions in - <a href="tls_cert_machine.html">Generating Machine Certificates</a>) -<li>make sure you copy over ca.pem, machine-key.pem ad machine-cert.pem to the client. -Ensure that no user except root can access them (<b>even read permissions are really bad</b>). -<li>configure the client so that it checks the server identity and sends messages only -if the server identity is known. -</ul> -<p>These were essentially the same steps as for any -<a href="tls_cert_client.html">TLS syslog client</a>. We now need to add the -capability to forward the router logs: -<ul> -<li>make sure that the firewall rules permit message recpetion on UDP port 514 (if you use -a non-standard port for UDP syslog, make sure that port number is permitted). -<li>you may want to limit who can send syslog messages via UDP. A great place to do this -is inside the firewall, but you can also do it in rsyslog.conf via an $AllowedSender -directive. We have used one in the sample config below. Please be aware that this is -a kind of weak authentication, but definitely better than nothing... -<li>add the UDP input plugin to rsyslog's config and start a UDP listener -<li>make sure that your forwarding-filter permits to forward messages received -from the remote router to the server. In our sample scenario, we do not need to -add anything special, because all messages are forwarded. This includes messages -received from remote hosts. -</ul> -<p><b>At this point, please be reminded once again that your security needs may be quite different from -what we assume in this tutorial. Evaluate your options based on your security needs.</b> -<h3>Sample syslog.conf</h3> -<p>Keep in mind that this rsyslog.conf sends messages via TCP, only. Also, we do not -show any rules to write local files. Feel free to add them. -<code><pre> -# start a UDP listener for the remote router -$ModLoad imudp # load UDP server plugin -$AllowedSender UDP, 192.0.2.1 # permit only the router -$UDPServerRun 514 # listen on default syslog UDP port 514 - -# make gtls driver the default -$DefaultNetstreamDriver gtls - -# certificate files -$DefaultNetstreamDriverCAFile /rsyslog/protected/ca.pem -$DefaultNetstreamDriverCertFile /rsyslog/protected/machine-cert.pem -$DefaultNetstreamDriverKeyFile /rsyslog/protected/machine-key.pem - -$ActionSendStreamDriverAuthMode x509/name -$ActionSendStreamDriverPermittedPeer central.example.net -$ActionSendStreamDriverMode 1 # run driver in TLS-only mode -*.* @@central.example.net:10514 # forward everything to remote server -</pre></code> -<p><font color="red"><b>Be sure to safeguard at least the private key (machine-key.pem)!</b> -If some third party obtains it, you security is broken!</font> -<h2>Copyright</h2> -<p>Copyright © 2008 <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer -Gerhards</a> and -<a href="http://www.adiscon.com/en/">Adiscon</a>.</p> -<p> Permission is granted to copy, distribute and/or modify this -document under the terms of the GNU Free Documentation License, Version -1.2 or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover -Texts. A copy of the license can be viewed at -<a href="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</a>.</p> -</body></html> diff --git a/doc/troubleshoot.html b/doc/troubleshoot.html index 0f0c7fc..a0303a2 100644 --- a/doc/troubleshoot.html +++ b/doc/troubleshoot.html @@ -88,15 +88,19 @@ passwords or other sensitive data. If it does, you can change it to some <b>cons meaningless value. <b>Do not delete the lines</b>, as this renders the debug log unusable (and makes Rainer quite angry for wasted time, aka significantly reduces the chance he will remain motivated to look at your problem ;)). For the same reason, make sure -whatever you change is change consistently. Really! -<p>Debug log file can get quite large. Before submitting them, it is a good idea to zip them. -Rainer has handled files of around 1 to 2 GB. If your's is larger ask before submitting. Often, -it is sufficient to submit the first 2,000 lines of the log file and around another 1,000 around -the area where you see a problem. Also, -ask you can submit a file via private mail. Private mail is usually a good way to go for large files -or files with sensitive content. However, do NOT send anything sensitive that you do not want -the outside to be known. While Rainer so far made effort no to leak any sensitive information, -there is no guarantee that doesn't happen. If you need a guarantee, you are probably a +whatever you change is changed consistently. Really! +<p>While most debug log files are moderately large, some can get quite to extremly large. +For those on the larger side, it is a good idea to zip them. If the file is less than +around 100KiB, it's probably not necessary. +<p>A good place to post your debug log is at the +<a href="http://kb.monitorware.com/rsyslog-f40.html">rsyslog support forums</a>, together with +your question. This also enables us to keep track of the case. The forums accept attachments in +various common formats, but rejects others for security reasons. The zip, txt, and log extensions +are definitely permitted, so it probably is a good idea to use one of them. For others, please +simply try and revert to another format if the forum doesn't like what you used. +<p> +Please note that all information in your debug file is publically visiable. +If this is not acceptable for you, you are probably a candidate for a <a href="professional_support.html">commercial support contract</a>. Free support comes without any guarantees, include no guarantee on confidentiality [aka "we don't want to be sued for work were are not even paid for ;)]. @@ -156,7 +160,7 @@ need to program or do anything else except get a problem solved ;) [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> <p><font size="2">This documentation is part of the <a href="http://www.rsyslog.com/">rsyslog</a> project.<br> -Copyright © 2008-2010 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and +Copyright © 2008-2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 3 or higher.</font></p> </body> |