diff options
Diffstat (limited to 'doc')
31 files changed, 1601 insertions, 326 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore deleted file mode 100644 index 282522db..00000000 --- a/doc/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -Makefile -Makefile.in diff --git a/doc/Makefile.am b/doc/Makefile.am index 653ed627..03b18f96 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,6 +21,7 @@ html_files = \ rsyslog_high_database_rate.html \ rsyslog_php_syslog_ng.html \ rsyslog_recording_pri.html \ + rsyslog_tls.html \ rsyslog_reliable_forwarding.html \ rsyslog_stunnel.html \ syslog-protocol.html \ @@ -37,9 +38,10 @@ html_files = \ imklog.html \ professional_support.html \ queues.html \ - queueWorkerLogic.dia \ + src/queueWorkerLogic.dia \ queueWorkerLogic.jpg \ queueWorkerLogic_small.jpg \ + tls_cert.jpg \ rainerscript.html \ rscript_abnf.html \ rsconf1_actionexeconlywhenpreviousissuspended.html \ @@ -72,6 +74,7 @@ html_files = \ rsconf1_resetconfigvariables.html \ rsconf1_umask.html \ v3compatibility.html \ + src/tls_cert.dia \ src/classes.dia EXTRA_DIST = $(html_files) diff --git a/doc/features.html b/doc/features.html index 13fc34c6..2b3b31d9 100644 --- a/doc/features.html +++ b/doc/features.html @@ -1,5 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>rsyslog features</title></head> +<html><head><title>rsyslog features</title> + +</head> <body> <h1>RSyslog - Features</h1> <p><b>This page lists both current features as well as @@ -23,13 +25,18 @@ to MySQL databases</a></li> <li> native support for writing to Postgres databases</li> <li>direct support for Firebird/Interbase, OpenTDS (MS SQL, Sybase), SQLLite, Ingres, Oracle, and mSQL via libdbi, -a database abstraction layer (almost as good as native)</li><li>native support for <a href="ommail.html">sending mail messages</a> (first seen in 3.17.0)</li> +a database abstraction layer (almost as good as native)</li> +<li>native support for <a href="ommail.html">sending +mail messages</a> (first seen in 3.17.0)</li> <li>support for (plain) tcp based syslog - much better reliability</li> <li>support for sending and receiving compressed syslog messages</li> <li>support for on-demand on-disk spooling of messages that can not be processed fast enough (a great feature for <a href="rsyslog_high_database_rate.html">writing massive -amounts of syslog messages to a database</a>)</li><li>support for selectively <a href="http://wiki.rsyslog.com/index.php/OffPeakHours">processing messages only during specific timeframes</a> and spooling them to disk otherwise</li> +amounts of syslog messages to a database</a>)</li> +<li>support for selectively <a href="http://wiki.rsyslog.com/index.php/OffPeakHours">processing +messages only during specific timeframes</a> and spooling them to +disk otherwise</li> <li>ability to monitor text files and convert their contents into syslog messages (one per line)</li> <li>ability to configure backup syslog/database servers - if @@ -49,8 +56,9 @@ substrings</li> command execution</li> <li>support for running multiple rsyslogd instances on a single machine</li> -<li>support for <a href="rsyslog_stunnel.html"> -ssl-protected syslog</a> (via stunnel)</li> +<li>support for <a href="rsyslog_tls.html">TLS-protected +syslog</a> (both <a href="rsyslog_tls.html">natively</a> +and via <a href="rsyslog_stunnel.html">stunnel</a>)</li> <li>ability to filter on any part of the message, not just facility and severity</li> <li>ability to use regular expressions in filters</li> @@ -70,8 +78,7 @@ high log volume on multicore machines)</li> compliant messages (it is volatile because standardization is currently underway and this is a proof-of-concept implementation to aid this effort)</li> -<li> experimental support for syslog-transport-tls based -framing on syslog/tcp connections</li> +<li> world's first implementation of syslog-transport-tls</li> <li> the sysklogd's klogd functionality is implemented as the <i>imklog</i> input plug-in. So rsyslog is a full replacement for the sysklogd package</li> <li> support for IPv6</li> @@ -90,7 +97,13 @@ via custom plugins</li> <li>support for arbitrary complex boolean, string and arithmetic expressions in message filters</li> </ul> -<p> </p> +<h2>World's first</h2> +Rsyslog has an interesting number of "world's firsts" - things that +were implemented for the first time ever in rsyslog. Some of them are still features not available elsewhere.<br><ul> +<li>world's first implementation of IETF I-D syslog-protocol (February 2006, version 1.12.2 and above)</li><li>world's first implementation of dynamic syslog on-the-wire compression (December 2006, version 1.13.0 and above)</li><li>world's first open-source implementation of a disk-queueing syslogd (January 2008, version 3.11.0 and above)</li> +<li>world's first implementation of IETF I-D +syslog-transport-tls (May 2008, version 3.19.0 and above)</li> +</ul> <h2>Upcoming Features</h2> <p>The list below is something like a repository of ideas we'd like to implement. Features on this list are typically NOT scheduled @@ -101,17 +114,13 @@ typically within reach of implementation. Users are encouraged to submit feature requests there (or via our forums). If we like them but they look quite long-lived (aka "not soon to be implemented"), they will possibly be migrated to this list here and at some time moved back -to the sourceforge tracker.</p> +to the bugzilla tracker.</p> <ul> -<li>implement native email-functionality in selector (probably -best done as a plug-in)</li> <li>port it to more *nix variants (eg AIX and HP UX) - this needs volunteers with access to those machines and knowledge </li> -<li>support for native SSL enryption of plain tcp syslog -sessions. This will most probably happen based on syslog-transport-tls.</li> <li>pcre filtering - maybe (depending on feedback) - simple regex already partly added. So far, this seems sufficient so -that there is no urgent need to do pcre</li> +that there is no urgent need to do pcre. If done, it will be a loadable RainerScript function.</li> <li>support for <a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC 3195</a> as a sender - this is currently unlikely to happen, because there is no real demand for it. Any work on RFC 3195 has been @@ -124,4 +133,4 @@ future of RFC 3195 in rsyslog</a>.</li> <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>
\ No newline at end of file +</body></html> diff --git a/doc/im3195.html b/doc/im3195.html new file mode 100644 index 00000000..d6f2f2ed --- /dev/null +++ b/doc/im3195.html @@ -0,0 +1,46 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head> +<title>RFC3195 Input Module (im3195)</title> + +</head> +<body> +<h1>RFC3195 Input Module</h1> +<p><b>Module Name: im3195</b></p> +<p><b>Author: </b>Rainer Gerhards +<rgerhards@adiscon.com></p> +<p><b>Description</b>:</p> +<p>Receives syslog messages via RFC 3195. The RAW profile is fully implemented and the +COOKED profile is provided in an experimental state. This module uses +<a href="http://www.liblogging.org">liblogging</a> for the actual protocol handling.</p> +<p><b>Configuration Directives</b>:</p> +<ul> +<li><strong>$Input3195ListenPort <port></strong><br> +The port on which imklog listens for RFC 3195 messages. The default port is 601 +(the IANA-assigned port)</li> +</ul> +<b>Caveats/Known Bugs:</b> +<p>Due to no demand at all for RFC3195, we have converted rfc3195d +to this input module, but we have NOT conducted any testing. Also, +the module does not yet properly handle the recovery case. If someone +intends to put this module into production, good testing should be +cunducted. It also is a good idea to notify the rsyslog project that you intend to use +it in production. In this case, we'll probably give the module another +cleanup. We don't do this now because so far it looks just like a big +waste of time. +<p>Currently only a single listener can be defined. That one binds to all interfaces.</p> +<p><b>Sample:</b></p> +<p>The following sample accepts syslog messages via RFC 3195 on port 1601. +<br> +</p> +<textarea rows="15" cols="60">$ModLoad im3195 +$Input3195ListenPort 1601 +</textarea> +<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] +[<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 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></html> diff --git a/doc/imtcp.html b/doc/imtcp.html index b2c6d21d..12f8020d 100644 --- a/doc/imtcp.html +++ b/doc/imtcp.html @@ -1,8 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head> -<meta http-equiv="Content-Language" content="en"><title>TCP Syslog Input Module</title> - -</head> +<meta http-equiv="Content-Language" content="en"><title>TCP Syslog Input Module</title></head> <body> <h1>TCP Syslog Input Module</h1> <p><b>Module Name: imtcp</b></p> @@ -22,8 +20,13 @@ $InputTCPServerRun multiple times. This is not currently supported. <ul> <li>$InputTCPServerRun <port><br> Starts a TCP server on selected port</li> -<li>$InputTCPMaxSessions <number><br> -Sets the maximum number of sessions supported</li> +<li><ul><li>$InputTCPMaxSessions <number></li></ul> +Sets the maximum number of sessions supported</li><li>$InputTCPServerStreamDriverMode <number><br> +Sets the driver mode for the currently selected <a href="netstream.html">network stream driver</a>. <number> is driver specifc.</li><li>$InputTCPServerStreamDriverAuthMode <mode-string><br> +Sets the authentication mode for the currently selected <a href="netstream.html">network stream driver</a>. <mode-string> is driver specifc.</li><li>$InputTCPServerStreamDriverPermittedPeer <id-string><br> +Sets permitted peer IDs. Only these peers are able to connect to the +listener. <id-string> semantics depend on the currently selected +AuthMode and <a href="netstream.html">network stream driver</a>. PermittedPeers may not be set in anonymous modes.</li> </ul> <b>Caveats/Known Bugs:</b> <ul> diff --git a/doc/manual.html b/doc/manual.html index a416277a..d1b670aa 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -11,12 +11,12 @@ control, high precision timestamps, queued operations and the ability to filter part.</b> It is quite compatible to stock sysklogd and can be used as a drop-in replacement. Its <a href="features.html"> -advanced features</a> make it suitable for enterprise-class, <a href="rsyslog_stunnel.html">encryption protected syslog</a> +advanced features</a> make it suitable for enterprise-class, <a href="rsyslog_tls.html">encryption protected syslog</a> relay chains while at the same time being very easy to setup for the novice user. And as we know what enterprise users really need, there is also <a href="professional_support.html">professional rsyslog support</a> available directly from the source!</p> -<p><b>This documentation is for version 3.17.5 (beta branch) of rsyslog.</b> +<p><b>This documentation is for version 3.19.8 (devel branch) of rsyslog.</b> Visit the <i> <a href="http://www.rsyslog.com/doc-status.html">rsyslog status page</a></i></b> to obtain current version information and project status. </p><p><b>If you like rsyslog, you might @@ -51,6 +51,7 @@ modules</a></li><li><a href="man_rsyslogd.html">rsyslogd man page</a> <ul> <li><a href="install.html">installing rsyslog</a></li> <li><a href="ipv6.html">rsyslog and IPv6</a> (which is fully supported)</li> +<li><a href="rsyslog_tls.html">native TLS encryption for syslog</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> <li><a href="rsyslog_high_database_rate.html">writing massive amounts of syslog messages to a database</a></li> diff --git a/doc/netstream.html b/doc/netstream.html new file mode 100644 index 00000000..e7d54c12 --- /dev/null +++ b/doc/netstream.html @@ -0,0 +1,21 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>Network Stream Drivers</title> + +</head> +<body> +<h1>Network Stream Drivers</h1><p>Network stream drivers are a layer +between various parts of rsyslogd (e.g. the imtcp module) and the +transport layer. They provide sequenced delivery, authentication and +confidentiality to the upper layers. Drivers implement different +capabilities.</p><p> Users need to know about netstream drivers because +they need to configure the proper driver, and proper driver properties, +to achieve desired results (e.g. a <a href="rsyslog_tls.html">TLS-protected syslog transmission</a>).</p><p>The following drivers exist:</p><ul><li><a href="ns_ptcp.html">ptcp</a> - the plain tcp network transport (no security)</li><li><a href="ns_gtls.html">gtls</a> - a secure TLS transport implemented via the GnuTLS library</li></ul>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] +[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>] +<p><font size="2">This documentation is part of the +<a href="http://www.rsyslog.com/">rsyslog</a> +project.<br> +Copyright © 2008 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></html>
\ No newline at end of file diff --git a/doc/ns_gtls.html b/doc/ns_gtls.html new file mode 100644 index 00000000..0d02ad02 --- /dev/null +++ b/doc/ns_gtls.html @@ -0,0 +1,59 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>gtls Network Stream Driver</title> + +</head> +<body> +<h1>gtls Network Stream Driver</h1> +<p>This <a href="netstream.html">network stream +driver</a> implements a TLS protected transport via the <a href="http://www.gnu.org/software/gnutls/" target="_blank">GnuTLS +library</a>.</p> +<p><b>Available since:</b> 3.19.0 (suggested minimum 3.19.8 and above)</p> +<p style="font-weight: bold;">Supported Driver Modes</p> +<ul> +<li>0 - unencrypted trasmission (just like <a href="ns_ptcp.html">ptcp</a> driver)</li> +<li>1 - TLS-protected operation</li> +</ul> +Note: mode 0 does not provide any benefit over the ptcp driver. This +mode exists for technical reasons, but should not be used. It may be +removed in the future.<br> +<span style="font-weight: bold;">Supported Authentication +Modes</span><br> +<ul> +<li><span style="font-weight: bold;">anon</span> +- anonymous authentication as +described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft</li> +<li><span style="font-weight: bold;">x509/fingerprint</span> +- certificate fingerprint authentication as +described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft</li> +<li><span style="font-weight: bold;">x509/certvalid</span> +- certificate validation only</li> +<li><span style="font-weight: bold;">x509/name</span> +- certificate validation and subject name authentication as +described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft +</li> +</ul> +Note: "anon" does not permit to authenticate the remote peer. As such, +this mode is vulnerable to man in the middle attacks as well as +unauthorized access. It is recommended NOT to use this mode.</p> +<p>x509/certvalid is a nonstandard mode. It validates the remote +peers certificate, but does not check the subject name. This is +weak authentication that may be useful in scenarios where multiple +devices are deployed and it is sufficient proof of authenticy when +their certificates are signed by the CA the server trusts. This is +better than anon authentication, but still not recommended. +<b>Known Problems</b><br> +<p>Even in x509/fingerprint mode, both the client and sever +certificate currently must be signed by the same root CA. This is an +artifact of the underlying GnuTLS library and the way we use it. It is +expected that we can resolve this issue in the future.</p> +<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] +[<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 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></html> diff --git a/doc/ns_ptcp.html b/doc/ns_ptcp.html new file mode 100644 index 00000000..c028d6c0 --- /dev/null +++ b/doc/ns_ptcp.html @@ -0,0 +1,16 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>ptcp Network Stream Driver</title> + +</head> +<body> +<h1>ptcp Network Stream Driver</h1> +<p>This <a href="netstream.html">network stream driver</a> implement a plain tcp transport without security properties.</p><p>Supported Driver Modes</p><ul><li>0 - unencrypted trasmission</li></ul>Supported Authentication Modes<br><ul><li>"anon" - no authentication</li></ul>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] +[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>] +<p><font size="2">This documentation is part of the +<a href="http://www.rsyslog.com/">rsyslog</a> +project.<br> +Copyright © 2008 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></html>
\ No newline at end of file diff --git a/doc/professional_support.html b/doc/professional_support.html index 1a9e6524..2cb6c1e1 100644 --- a/doc/professional_support.html +++ b/doc/professional_support.html @@ -4,11 +4,11 @@ </head> <body> -<h1>Professional Support for Rsyslog</h1> -<p>Professional Support is offered by <a href="http://www.adiscon.com">Adiscon</a>, the company -that sponsors rsyslog development. For details, please contact <a href="mailto:info%40adiscon.com">Adiscon Sales</a>.</p> -<p></p> -<h3><u>EMail Support Service</u></h3> +<h1>Professional Services for Rsyslog</h1> +<p>Professional services are being offered by <a href="http://www.adiscon.com">Adiscon</a>, the company +that sponsors rsyslog development. For details, please contact <a href="mailto:info%40adiscon.com">Adiscon Sales</a>. </p> + +<h3>EMail Support Service</h3> Price: 99.00 EURO <br> Duration: 180 days <br> @@ -19,14 +19,19 @@ need to provide proof of software support in your organization. This contract provides</p> <ul> <li>unlimited email support tickets during validity -</li><li><span style="font-weight: bold;">fixes for</span> +</li> +<li><span style="font-weight: bold;">fixes for</span> current and <span style="font-weight: bold;">past rsyslog releases</span> -</li><li>advise on how to implement rsyslog in the best possible way. -</li></ul> +</li> +<li>advise on how to implement rsyslog in the best possible +way. +</li> +</ul> <p>Under this contract, fixes for old rsyslog releases will be provided / created, provided that it is possible to do that with the -code base in question. Phone support is not included.</p><h3><u>Custom-Written Config File</u></h3> +code base in question. Phone support is not included.</p> +<h3>Custom-Written Config File</h3> Price: 29.00 EURO <br> Duration: N/A @@ -43,9 +48,35 @@ faster). For security reasons, we will not put passwords into the configuration file, but will place easy to read comments in the places where you need to put them in. The agreement is governed under German law. You may also purchase this service if you would like to have your -own configuration file reviewed, e.g. for auditing purposes.</p><br><p>All agreements are +own configuration file reviewed, e.g. for auditing purposes.</p> +<h3>Custom Development</h3> +<p>Do you need an exotic feature that otherwise would not be implemented? +Do you need something really quick, quicker than it is available via +the regular development schedule? Then, you may consider funding +development for a specific functionality. We are always looking for +interesting projects. If you hire us to to do the job, you can be sure +to get the best possible and probably quickest solution, because we are +obviously at the heart of the source code. No need to get aquainted to +anything, no risk of misunderstanding program concepts. Benefit from +our vast syslog experience.</p> +<p>Please note that custom development is not limited to rsyslog. We offer +a number of logging solutions and can also work as part of your time +for specific requirements. The opportunities are endless, just ask. We +will work with you on your requirements and provide a quote on the +estimated cost. Just write to <a href="mailto:sales@adiscon.com">sales@adiscon.com</a> for details.</p><h3>Consulting Services</h3> +<p>Do you have demanding logging requirements? Why not talk to a +real logging professional? Instead of trying to find the solution +like a needle in the haystack, talk to the team that brought rsyslog, +phpLogCon, the Windows MonitorWare products and other logging +solutions. We sweat logging for over 15 years now and can help quickly. +Depending on your needs, consulting can be carried out via email, the +phone or on your premises (for larger or local projects). Everything is +possible, it just depends on your needs. Consulting services are +available in English and German. Just mail <a href="mailto:sales@adiscon.com">sales@adiscon.com</a> what you are interested in and we will work with you on a proposal that fits your needs. +</p><p></p><p>All agreements are governed under German law. -</p><p></p> +</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> @@ -54,4 +85,4 @@ Copyright © 2008 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></html> +</body></html>
\ No newline at end of file diff --git a/doc/property_replacer.html b/doc/property_replacer.html index a2efaede..2675e8fb 100644 --- a/doc/property_replacer.html +++ b/doc/property_replacer.html @@ -44,7 +44,13 @@ socket. Should be useful for debugging.</td> <td><b>fromhost</b></td> <td>hostname of the system the message was received from (in a relay chain, this is the system immediately in front of us and -not necessarily the original sender)</td> +not necessarily the original sender). This is a DNS-resolved name, except +if that is not possible or DNS resolution has been disabled.</td> +</tr> +<tr> +<td><b>fromhost-ip</b></td> +<td>The same as fromhost, but alsways as an IP address. Local inputs +(like imklog) use 127.0.0.1 in this property.</td> </tr> <tr> <td><b>syslogtag</b></td> @@ -198,8 +204,33 @@ not become part of it. If you are using regular expressions, the property replacer will return the part of the property text that matches the regular expression. An example for a property replacer sequence with a regular expression is: "%msg:R:.*Sev:. \(.*\) -\[.*--end%"<br> -</p> +\[.*--end%"</p> +<p>It is possible to specify some parametes after the "R". These are +comma-separated. They are: +<p>R,<regexp-type>,<submatch>,<nomatch>,<match-number> +<p>regexp-type is either "BRE" for Posix basic regular expressions or +"ERE" for extended ones. The string must be given in upper case. The +default is "BRE" to be consistent with earlier versions of rsyslog that +did not support ERE. The submatch identifies the submatch to be used +with the result. A single digit is supported. Match 0 is the full match, +while 1 to 9 are the acutal submatches. The match-number identifies which match to +use, if the expression occurs more than once inside the string. Please note +that the first match is number 0, the second 1 and so on. Up to 10 matches +(up to number 9) are supported. Please note that it would be more +natural to have the match-number in front of submatch, but this would break +backward-compatibility. So the match-number must be specified after "nomatch". +<p>nomatch is either "DFLT", "BLANK" or "FIELD" (all upper case!). It tells +what to use if no match is found. With "DFLT", the strig "**NO MATCH**" is +used. This was the only supported value up to rsyslog 3.19.5. With "BLANK" +a blank text is used (""). Finally, "FIELD" uses the full property text +instead of the expression. Some folks have requested that, so it seems +to be useful. +<p>The following is a sample of an ERE expression that takes the first +submatch from the message string and replaces the expression with +the full field if no match is found: +<p>%msg:R,ERE,1,FIELD:for (vlan[0-9]*):--end% +<p>and this takes the first submatch of the second match of said expression: +<p>%msg:R,ERE,1,FIELD,1:for (vlan[0-9]*):--end% <p><b>Also, extraction can be done based on so-called "fields"</b>. To do so, place a "F" into FromChar. A field in its current definition is anything that is delimited by a delimiter @@ -253,6 +284,10 @@ Especially useful for PIX.</td> <td>format as RFC 3339 date</td> </tr> <tr> +<td><b>date-subseconds</b></td> +<td>just the subseconds of a timestamp (always 0 for a low precision timestamp)</td> +</tr> +<tr> <td><b>escape-cc</b></td> <td>replace control characters (ASCII value 127 and values less then 32) with an escape sequence. The sequnce is @@ -286,4 +321,4 @@ to record severity and facility of a message)</li> <li><a href="rsyslog_conf.html">Configuration file syntax</a>, this is where you actually use the property replacer.</li> </ul> -</body></html>
\ No newline at end of file +</body></html> diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html index 9325f73c..3946a2d3 100644 --- a/doc/rsyslog_conf.html +++ b/doc/rsyslog_conf.html @@ -50,6 +50,8 @@ input plugin for plain tcp and GSS-enable syslog</li> <li><a href="imklog.html">imklog</a> - kernel logging</li> <li><a href="imuxsock.html">imuxsock</a> - unix sockets, including the system log socket</li> +<li><a href="im3195.html">im3195</a> - +accepts syslog messages via RFC 3195</li> </ul> <p>Please note that each module provides configuration directives, which are NOT necessarily being listed below. Also @@ -114,19 +116,25 @@ default 60000 (1 minute)]</li> <li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li> <li>$ActionQueueSaveOnShutdown [on/<b>off</b>] </li> -<li>$ActionQueueWorkerThreads <number>, num -worker threads, default 1, recommended 1</li> -<li>$ActionQueueWorkerThreadMinumumMessages -<number>, default 100</li> +<li>$ActionQueueWorkerThreads <number>, num worker threads, default 1, recommended 1</li> +<li>$ActionQueueWorkerThreadMinumumMessages <number>, default 100</li> <li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li> -<li>$ActionResumeRetryCount <number> [default 0, --1 means eternal]</li> +<li>$ActionResumeRetryCount <number> [default 0, -1 means eternal]</li> +<li>$ActionSendResendLastMsgOnReconn <[on/<b>off</b>]> specifies if the last message is to be resend when a connecition broken and has been reconnedcted. May increase reliability, but comes at the risk of message duplication. +<li>$ActionSendStreamDriver <driver basename> just like $DefaultNetstreamDriver, but for the specific action +</li><li>$ActionSendStreamDriverMode <mode>, default 0, mode to use with the stream driver +(driver-specific)</li><li>$ActionSendStreamDriverAuthMode <mode>, authentication mode to use with the stream driver +(driver-specific)</li><li>$ActionSendStreamDriverPermittedPeer <ID>, accepted fingerprint (SHA1) or name of remote peer +(driver-specific) -<span style="font-weight: bold;"> directive may go away</span>!</li> <li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li> <li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li> <li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li> <li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li> <li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li> +<li>$DefaultNetstreamDriver <drivername>, the default <a href="netstream.html">network stream driver</a> to use. Defaults to ptcp.$DefaultNetstreamDriverCAFile </path/to/cafile.pem></li> +<li>$DefaultNetstreamDriverCertFile </path/to/certfile.pem></li> +<li>$DefaultNetstreamDriverKeyFile </path/to/keyfile.pem></li> <li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li> <li><a href="rsconf1_dirgroup.html">$DirGroup</a></li> <li><a href="rsconf1_dirowner.html">$DirOwner</a></li> @@ -347,6 +355,10 @@ all relatively recent versions of rsyslog. Other syslogd's may get hopelessly confused if receiving that format, so check before you use it. Note that the format is unlikely to change when the final RFC comes out, but this may happen.</li> +<li><span style="font-weight: bold;">RSYSLOG_DebugFormat</span> +- a special format used for troubleshooting property problems. This format +is meant to be written to a log file. Do <b>not</b> use for production or remote +forwarding.</li> </ul> <h2>Output Channels</h2> <p>Output Channels are a new concept first introduced in rsyslog @@ -1190,4 +1202,4 @@ additional and database support). For obvious reasons, the syntax for defining such features is available in rsyslogd, only.<br> </p> -</body></html>
\ No newline at end of file +</body></html> diff --git a/doc/rsyslog_mysql.html b/doc/rsyslog_mysql.html index 57a779d5..ad2850cc 100644 --- a/doc/rsyslog_mysql.html +++ b/doc/rsyslog_mysql.html @@ -172,7 +172,7 @@ such a password is NOT a good idea...). If your MySQL database is on the local machine, your rsyslog.conf line might look like in this sample:</p> <blockquote> -<p><code>*.* :ommysql:127.0.0.1,syslog,syslogwriter,topsecret</code></p> +<p><code>*.* :ommysql:127.0.0.1,Syslog,syslogwriter,topsecret</code></p> </blockquote> <p>Save rsyslog.conf, restart rsyslogd - and you should see syslog messages being stored in the "systemevents" table!</p> @@ -259,4 +259,4 @@ document under the terms of the GNU Free Documentation License, Version 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>
\ No newline at end of file +</body></html> diff --git a/doc/rsyslog_ng_comparison.html b/doc/rsyslog_ng_comparison.html index 28413337..600875a8 100644 --- a/doc/rsyslog_ng_comparison.html +++ b/doc/rsyslog_ng_comparison.html @@ -1,11 +1,9 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head><title>rsyslog vs. syslog-ng - a comparison</title> - -</head> +<html><head><title>rsyslog vs. syslog-ng - a comparison</title></head> <body> <h1>rsyslog vs. syslog-ng</h1> <p><small><i>Written by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> -(2008-04-08)</i></small></p> +(2008-05-06)</i></small></p> <p>We have often been asked about a comparison sheet between rsyslog and syslog-ng. Unfortunately, I do not know much about syslog-ng, I did not even use it once. Also, there seems to be no @@ -57,7 +55,7 @@ comparison sheet, so please don't be shy ;)</p> </tr> <tr> <td valign="top">RFC 3195/BEEP</td> -<td valign="top">yes (needs separate build process)</td> +<td valign="top">yes (via <a href="im3195.html">im3195</a>)</td> <td valign="top">no</td> <td></td> </tr> @@ -101,7 +99,7 @@ Network (Protocol) Support</b><br> <tr> <td valign="top">support for GSS-API</td> <td valign="top">yes</td> -<td valign="top">no (?)</td> +<td valign="top">no</td> </tr> <tr> <td valign="top">ability to limit the allowed @@ -122,7 +120,7 @@ based framing on syslog/tcp connections</td> </tr> <tr> <td valign="top">syslog over RELP<br> -truly reliable message delivery (<a href="http://rgerhards.blogspot.com/2008/04/on-unreliability-of-plain-tcp-syslog.html">Why +truly reliable message delivery (<a href="http://blog.gerhards.net/2008/05/why-you-cant-build-reliable-tcp.html">Why is plain tcp syslog not reliable?</a>)</td> <td valign="top">yes</td> <td valign="top">no</td> @@ -141,20 +139,24 @@ reliable <a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC <td valign="top">no</td> </tr> <tr> -<td valign="top">support for <a href="rsyslog_stunnel.html">ssl-protected +<td valign="top">support for <a href="rsyslog_tls.html">TLS/SSL-protected syslog</a> </td> -<td valign="top"><a href="rsyslog_stunnel.html">via +<td valign="top"><a href="rsyslog_tls.html">natively</a> (since 3.19.0)<br><a href="rsyslog_stunnel.html">via stunnel</a></td> <td valign="top">via stunnel<br> paid edition natively</td> </tr> <tr> -<td valign="top">support for IETF's new -syslog-protocol draft</td> +<td valign="top">support for IETF's new syslog-protocol draft</td> <td valign="top">yes</td> <td valign="top">no</td> </tr> <tr> +<td valign="top">support for IETF's new syslog-transport-tls draft</td> +<td valign="top">yes<br>(since 3.19.0 - world's first implementation)</td> +<td valign="top">no</td> +</tr> +<tr> <td valign="top">support for IPv6</td> <td valign="top">yes</td> <td valign="top">yes</td> @@ -162,7 +164,7 @@ syslog-protocol draft</td> <tr> <td valign="top">native ability to send SNMP traps</td> <td valign="top">yes</td> -<td valign="top">?</td> +<td valign="top">no</td> </tr> <tr> <td valign="top">ability to preserve the original @@ -426,8 +428,10 @@ including ability to present channel and priority as visible log data</td> <td valign="top">yes</td> <td valign="top">not sure...</td> </tr> -<tr><td valign="top">native ability to send mail messages</td> -<td valign="top">yes (<a href="ommail.html">ommail</a>, introduced in 3.17.0)</td> +<tr> +<td valign="top">native ability to send mail messages</td> +<td valign="top">yes (<a href="ommail.html">ommail</a>, +introduced in 3.17.0)</td> <td valign="top">not sure...</td> </tr> <tr> @@ -578,6 +582,5 @@ feature sheet. I have not yet been able to fully work through it. In the mean time, you may want to read it in parallel. It is available at <a href="http://www.balabit.com/network-security/syslog-ng/features/detailed/">Balabit's site</a>.</p> -<p>This document is current as of 2008-04-08 and definitely -incomplete (I did not yet manage to complete it!).</p> -</body></html>
\ No newline at end of file + +</body></html> diff --git a/doc/rsyslog_secure_tls.html b/doc/rsyslog_secure_tls.html new file mode 100644 index 00000000..be2811f4 --- /dev/null +++ b/doc/rsyslog_secure_tls.html @@ -0,0 +1,127 @@ +<!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> +I 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_stunnel.html b/doc/rsyslog_stunnel.html index 9d944521..104a672e 100644 --- a/doc/rsyslog_stunnel.html +++ b/doc/rsyslog_stunnel.html @@ -1,248 +1,240 @@ -<html><head>
-<title>SSL Encrypting syslog with stunnel</title>
-<meta name="KEYWORDS" content="syslog encryption, rsyslog, stunnel, secure syslog, tcp, reliable, howto, ssl">
-</head>
-<body>
-<h1>SSL Encrypting Syslog with Stunnel</h1>
- <P><small><i>Written by
- <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
- Gerhards</a> (2005-07-22)</i></small></P>
-<h2>Abstract</h2>
-<p><i><b>In this paper, I describe how to encrypt <a href="http://www.monitorware.com/en/topics/syslog/">syslog</a>
-messages on the network.</b> Encryption
-is vital to keep the confidiental content of syslog messages secure. I describe the overall
-approach and provide an HOWTO do it with the help of
-<a href="http://www.rsyslog.com">rsyslogd</a> and <a href="http://www.stunnel.org">stunnel</a>.</i></p>
-<h2>Background</h2>
-<P><b>Syslog is a
-clear-text protocol. That means anyone with a sniffer can have
-a peek at your data.</b> In some environments, this is no problem at all. In
-others, it is a huge setback, probably even preventing deployment of syslog
-solutions. Thankfully, there is an easy way to encrypt syslog communication. I
-will describe one approach in this paper.</P>
-<P>The most straigthforward solution would be that the syslogd itself encrypts
-messages. Unfortuantely, encryption is only standardized in
-<a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC 3195</a>. But there
-is currently no syslogd that implements RFC 3195's encryption features,
-so this route leads to nothing. Another approach would be to use vendor- or
-project-specific syslog extensions. There are a few around, but the problem here
-is that they have compatibility issues. However, there is one surprisingly easy
-and interoperable solution: though not standardized, many vendors and projects
-implement plain tcp syslog. In a nutshell, plain tcp syslog is a mode where
-standard syslog messages are transmitted via tcp and records are separated by
-newline characters. This mode is supported by all major syslogd's (both on Linux/Unix
-and Windows) as well as log sources (for example,
-<a href="http://www.eventreporter.com/en/">EventReporter</a> for Windows
-Event Log forwarding). Plain tcp syslog offers reliability, but it does not
-offer encryption in itself. However, since it operates on a tcp stream, it is now easy
-to add encryption. There are various ways to do that. In this paper, I will
-describe how it is done with stunnel (an
-other alternative would be <a href="http://en.wikipedia.org/wiki/IPSec">IPSec</a>, for example).</P>
-<P>Stunnel is open source and it is available both for Unix/Linux and Windows.
-It provides a way to
- use ssl communication for any non-ssl aware client and server - in this case,
- our syslogd.</P>
- <P>Stunnel works much like a wrapper. Both on the client and on the server machine,
- tunnel portals are created. The non-ssl aware client and server software is
- configured to not directly talk to the remote partner, but to the local
- (s)tunnel portal instead. Stunnel, in turn, takes the data received from the
- client, encrypts it via ssl, sends it to the remote tunnel portal and that
- remote portal sends it to the recipient process on the remote machine. The
- transfer to the portals is done via unencrypted communication. As such,
- it is vital that
- the portal and the respective program that is talking to it are on the same
- machine, otherwise data would travel partly unencrypted. Tunneling, as done by stunnel,
- requires connection oriented communication. This is why you need to use
- tcp-based syslog. As a side-note, you can also encrypt a plain-text RFC
- 3195 session via stunnel, though this definitely is not what the
- protocol designers had on their mind ;)</P>
-<P>In the rest of this document, I assume that you use rsyslog on both the
-client and the server. For the samples, I use <a href="http://www.debian.org/">Debian</a>.
-Interestingly, there are
-some annoying differences between stunnel implementations. For example, on
-Debian a comment line starts with a semicolon (';'). On
-<a href="http://www.redhat.com">Red Hat</a>, it starts with
-a hash sign ('#'). So you need to watch out for subtle issues when setting up
-your system.</P>
-<h2>Overall System Setup</h2>
-<P>In ths paper, I assume two machines, one named "client" and the other named "server".
-It is obvious that, in practice, you will probably have multiple clients but
-only one server. Syslog traffic shall be transmitted via stunnel over the
-network. Port 60514 is to be used for that purpose. The machines are set up as
-follows:</P>
-<P><b>Client</b></P>
-<ul>
- <li>rsyslog forwards message to stunnel local portal at port 61514</li>
- <li>local stunnel forwards data via the network to port 60514 to its remote
- peer</li>
-</ul>
-<P><b>Server</b></P>
-<ul>
- <li>stunnel listens on port 60514 to connections from its client peers</li>
- <li>all connections are forwarded to the locally-running rsyslog listening
- at port 61514</li>
-</ul>
-<h2>Setting up the system</h2>
-<P>For Debian, you need the "stunnel4" package. The "stunnel" package is the
-older 3.x release, which will not support the configuration I describe below.
-Other distributions might have other names. For example, on Red Hat it is just "stunnel".
-Make sure that you install the appropriate package on both the client and the
-server. It is also a good idea to check if there are updates for either stunnel
-or openssl (which stunnel uses) - there are often security fixes available and
-often the latest fixes are not included in the default package.</P>
-<P>In my sample setup, I use only the bare minimum of options. For example, I do
-not make the server check client cerficiates. Also, I do not talk much about
-certificates at all. If you intend to really secure your system, you should
-probably learn about certificates and how to manage and deploy them. This is
-beyond the scope of this paper. For additional information,
-<a href="http://www.stunnel.org/faq/certs.html">
-http://www.stunnel.org/faq/certs.html</a> is a good starting point.</P>
-<P>You also need to install rsyslogd on both machines. Do this before starting
-with the configuration. You should also familarize yourself with its
-configuration file syntax, so that you know which actions you can trigger with
-it. Rsyslogd can work as a drop-in replacement for stock
-<a href="http://www.infodrom.org/projects/sysklogd/">sysklogd</a>. So if you know
-the standard syslog.conf syntax, you do not need to learn any more to follow
-this paper.</P>
-<h3>Server Setup</h3>
-<P>At the server, you need to have a digital certificate. That certificate
-enables SSL operation, as it provides the necessary crypto keys being used to
-secure the connection. Many versions of stunnel come with a default certificate,
-often found in /etc/stunnel/stunnel.pem. If you have it, it is good for testing
-only. If you use it in production, it is very easy to break into your secure
-channel as everybody is able to get hold of your private key. I didn't find an
-stunnel.pem on my Debian machine. I guess the Debian folks removed it because of
-its insecurity.</P>
-<P>You can create your own certificate with a simple openssl tool - you need to
-do it if you have none and I highly recommend to create one in any case. To
-create it, cd to /etc/stunnel and type:</P>
-<p><blockquote><code>openssl req -new -x509 -days 3650 -nodes -out
-stunnel.pem -keyout stunnel.pem</code></blockquote></p>
-<P>That command will ask you a number of questions. Provide some answer for
-them. If you are unsure, read
-<a href="http://www.stunnel.org/faq/certs.html">
-http://www.stunnel.org/faq/certs.html</a>. After the command has finished, you
-should have a usable stunnel.pem in your working directory.</P>
-<P>Next is to create a configuration file for stunnel. It will direct stunnel
-what to do. You can used the following basic file:</P>
-<P><blockquote><code><pre>; Certificate/key is needed in server mode
-cert = /etc/stunnel/stunnel.pem
-
-<i>; Some debugging stuff useful for troubleshooting
-debug = 7
-foreground=yes</i>
-
-[ssyslog]
-accept = 60514
-connect = 61514</pre>
-</code></blockquote></P>
-<p>Save this file to e.g. /etc/stunnel/syslog-server.conf. Please note that the
-settings in <i>italics</i> are for debugging only. They run stunnel
-with a lot of debug information in the foreground. This is very valuable while
-you setup the system - and very useless once everything works well. So be sure
-to remove these lines when going to production.</p>
-<p>Finally, you need to start the stunnel daemon. Under Debian, this is done via
-"stunnel /etc/stunnel/syslog.server.conf". If you have enabled the debug
-settings, you will immediately see a lot of nice messages.</p>
-<p>Now you have stunnel running, but it obviously unable to talk to rsyslog -
-because it is not yet running. If not already done, configure it so that it does
-everything you want. If in doubt, you can simply copy /etc/syslog.conf to /etc/rsyslog.conf
-and you probably have what you want. The really important thing in rsyslogd
-configuration is that you must make it listen to tcp port 61514 (remember: this
-is where stunnel send the messages to). Thankfully, this is easy to achive: just
-add "-t 61514" to the rsyslogd startup options in your system startup script.
-After done so, start (or restart) rsyslogd.</p>
-<p>The server should now be fully operational.</p>
-<h3>Client Setup</h3>
-<P>The client setup is simpler. Most importantly, you do not need a certificate
-(of course, you can use one if you would like to authenticate the client, but
-this is beyond the scope of this paper). So the basic thing you need to do is
-create the stunnel configuration file.</P>
-<P><blockquote><code><pre><i>; Some debugging stuff useful for troubleshooting
-debug = 7
-foreground=yes</i>
-
-<b>client=yes</b>
-
-[ssyslog]
-accept = 127.0.0.1:61514
-connect = <font color="#FF0000">192.0.2.1</font>:60514
-</pre>
-</code></blockquote></P>
-<P>Again, the text in <i>italics</i> is for debugging purposes only. I suggest
-you leave it in during your initial testing and then remove it. The most
-important difference to the server configuration outlined above is the "client=yes"
-directive. It is what makes this stunnel behave like a client. The accept
-directive binds stunnel only to the local host, so that it is protected from
-receiving messages from the network (somebody might fake to be the local sender).
-The address "192.0.2.1" is the address of the server machine. You must change it
-to match your configuration. Save this file to /etc/stunnel/syslog-client.conf.</P>
-<P>Then, start stunnel via "stunnel4 /etc/stunnel/syslog-client.conf". Now
-you should see some startup messages. If no errors appear, you have a running
-client stunnel instance.</P>
-<P>Finally, you need to tell rsyslogd to send data to the remote host. In stock
-syslogd, you do this via the "@host" forwarding directive. The same works with
-rsyslog, but it suppports extensions to use tcp. Add the following line to your
-/etc/rsyslog.conf:</P>
-<P><blockquote><code><pre>*.* @<font color="#FF0000">@</font>127.0.0.1:61514
-</pre>
-</code></blockquote><i></P>
-
-</i>
-
-<P>Please note the double at-sign (@@). This is no typo. It tells rsyslog to use
-tcp instead of udp delivery. In this sample, all messages are forwarded to the
-remote host. Obviously, you may want to limit this via the usual rsyslog.conf
-settings (if in doubt, use man rsyslog.con).</P>
-<P>You do not need to add any special startup settings to rsyslog on the client.
-Start or restart rsyslog so that the new configuration setting takes place.</P>
-<h3>Done</h3>
-<P>After following these steps, you should have a working secure syslog
-forwarding system. To verify, you can type "logger test" or a similar smart
-command on the client. It should show up in the respective server log file. If
-you dig out you sniffer, you should see that the traffic on the wire is actually
-protected. In the configuration use above, the two stunnel endpoints should be
-quite chatty, so that you can follow the action going on on your system.</P>
-<P>If you have only basic security needs, you can probably just remove the debug
-settings and take the rest of the configuration to production. If you are
-security-sensitve, you should have a look at the various stunnel settings that
-help you further secure the system.</P>
-<h2>Preventing Systems from talking directly to the rsyslog Server</h2>
-<P>It is possible that remote systems (or attackers) talk to the rsyslog server
-by directly connecting to its port 61514. Currently (July of 2005), rsyslog does
-not offer the ability to bind to the local host, only. This feature is planned,
-but as long as it is missing, rsyslog must be protected via a firewall. This can
-easily be done via e.g iptables. Just be sure not to forget it.</P>
-<h2>Conclusion</h2>
-<P>With minumal effort, you can set up a secure logging infrastructure employing
-ssl encrypted syslog message transmission. As a side note, you also have the
-benefit of reliable tcp delivery which is far less prone to message loss than
-udp.</P>
-<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>2005-07-22 *
- <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Initial Version created</li>
- <li>2005-07-26 *
- <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Some text brush-up, hyperlinks added</li>
- <li>2005-08-03 *
- <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
- * license added</li>
-</ul>
-<h2>Copyright</h2>
-<p>Copyright (c) 2005
-<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>
\ No newline at end of file +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head> + +<title>SSL Encrypting syslog with stunnel</title><meta name="KEYWORDS" content="syslog encryption, rsyslog, stunnel, secure syslog, tcp, reliable, howto, ssl"></head><body> +<h1>SSL Encrypting Syslog with Stunnel</h1> + <p><small><i>Written by + <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer + Gerhards</a> (2005-07-22)</i></small></p> +<h2>Abstract</h2> +<p><i><b>In this paper, I describe how to encrypt <a href="http://www.monitorware.com/en/topics/syslog/">syslog</a> +messages on the network.</b> Encryption +is vital to keep the confidiental content of syslog messages secure. I describe the overall +approach and provide an HOWTO do it with the help of +<a href="http://www.rsyslog.com">rsyslogd</a> and <a href="http://www.stunnel.org">stunnel</a>.</i></p><p><span style="font-weight: bold;">Please note that starting with rsyslog 3.19.0, </span><a style="font-weight: bold;" href="rsyslog_tls.html">rsyslog provides native TLS/SSL encryption</a><span style="font-weight: bold;"> <span style="font-style: italic;">without</span> the need of stunnel. </span>I +strongly recomend to use that feature instead of stunnel. The stunnel +documentation here is mostly provided for backwards compatibility. New +deployments are advised to use native TLS mode.<i></i></p> +<h2>Background</h2> +<p><b>Syslog is a +clear-text protocol. That means anyone with a sniffer can have +a peek at your data.</b> In some environments, this is no problem at all. In +others, it is a huge setback, probably even preventing deployment of syslog +solutions. Thankfully, there is an easy way to encrypt syslog communication. I +will describe one approach in this paper.</p> +<p>The most straigthforward solution would be that the syslogd itself encrypts +messages. Unfortuantely, encryption is only standardized in +<a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC 3195</a>. But there +is currently no syslogd that implements RFC 3195's encryption features, +so this route leads to nothing. Another approach would be to use vendor- or +project-specific syslog extensions. There are a few around, but the problem here +is that they have compatibility issues. However, there is one surprisingly easy +and interoperable solution: though not standardized, many vendors and projects +implement plain tcp syslog. In a nutshell, plain tcp syslog is a mode where +standard syslog messages are transmitted via tcp and records are separated by +newline characters. This mode is supported by all major syslogd's (both on Linux/Unix +and Windows) as well as log sources (for example, +<a href="http://www.eventreporter.com/en/">EventReporter</a> for Windows +Event Log forwarding). Plain tcp syslog offers reliability, but it does not +offer encryption in itself. However, since it operates on a tcp stream, it is now easy +to add encryption. There are various ways to do that. In this paper, I will +describe how it is done with stunnel (an +other alternative would be <a href="http://en.wikipedia.org/wiki/IPSec">IPSec</a>, for example).</p> +<p>Stunnel is open source and it is available both for Unix/Linux and Windows. +It provides a way to + use ssl communication for any non-ssl aware client and server - in this case, + our syslogd.</p> + <p>Stunnel works much like a wrapper. Both on the client and on the server machine, + tunnel portals are created. The non-ssl aware client and server software is + configured to not directly talk to the remote partner, but to the local + (s)tunnel portal instead. Stunnel, in turn, takes the data received from the + client, encrypts it via ssl, sends it to the remote tunnel portal and that + remote portal sends it to the recipient process on the remote machine. The + transfer to the portals is done via unencrypted communication. As such, + it is vital that + the portal and the respective program that is talking to it are on the same + machine, otherwise data would travel partly unencrypted. Tunneling, as done by stunnel, + requires connection oriented communication. This is why you need to use + tcp-based syslog. As a side-note, you can also encrypt a plain-text RFC + 3195 session via stunnel, though this definitely is not what the + protocol designers had on their mind ;)</p> +<p>In the rest of this document, I assume that you use rsyslog on both the +client and the server. For the samples, I use <a href="http://www.debian.org/">Debian</a>. +Interestingly, there are +some annoying differences between stunnel implementations. For example, on +Debian a comment line starts with a semicolon (';'). On +<a href="http://www.redhat.com">Red Hat</a>, it starts with +a hash sign ('#'). So you need to watch out for subtle issues when setting up +your system.</p> +<h2>Overall System Setup</h2> +<p>In ths paper, I assume two machines, one named "client" and the other named "server". +It is obvious that, in practice, you will probably have multiple clients but +only one server. Syslog traffic shall be transmitted via stunnel over the +network. Port 60514 is to be used for that purpose. The machines are set up as +follows:</p> +<p><b>Client</b></p> +<ul> + <li>rsyslog forwards message to stunnel local portal at port 61514</li> + <li>local stunnel forwards data via the network to port 60514 to its remote + peer</li> +</ul> +<p><b>Server</b></p> +<ul> + <li>stunnel listens on port 60514 to connections from its client peers</li> + <li>all connections are forwarded to the locally-running rsyslog listening + at port 61514</li> +</ul> +<h2>Setting up the system</h2> +<p>For Debian, you need the "stunnel4" package. The "stunnel" package is the +older 3.x release, which will not support the configuration I describe below. +Other distributions might have other names. For example, on Red Hat it is just "stunnel". +Make sure that you install the appropriate package on both the client and the +server. It is also a good idea to check if there are updates for either stunnel +or openssl (which stunnel uses) - there are often security fixes available and +often the latest fixes are not included in the default package.</p> +<p>In my sample setup, I use only the bare minimum of options. For example, I do +not make the server check client cerficiates. Also, I do not talk much about +certificates at all. If you intend to really secure your system, you should +probably learn about certificates and how to manage and deploy them. This is +beyond the scope of this paper. For additional information, +<a href="http://www.stunnel.org/faq/certs.html"> +http://www.stunnel.org/faq/certs.html</a> is a good starting point.</p> +<p>You also need to install rsyslogd on both machines. Do this before starting +with the configuration. You should also familarize yourself with its +configuration file syntax, so that you know which actions you can trigger with +it. Rsyslogd can work as a drop-in replacement for stock +<a href="http://www.infodrom.org/projects/sysklogd/">sysklogd</a>. So if you know +the standard syslog.conf syntax, you do not need to learn any more to follow +this paper.</p> +<h3>Server Setup</h3> +<p>At the server, you need to have a digital certificate. That certificate +enables SSL operation, as it provides the necessary crypto keys being used to +secure the connection. Many versions of stunnel come with a default certificate, +often found in /etc/stunnel/stunnel.pem. If you have it, it is good for testing +only. If you use it in production, it is very easy to break into your secure +channel as everybody is able to get hold of your private key. I didn't find an +stunnel.pem on my Debian machine. I guess the Debian folks removed it because of +its insecurity.</p> +<p>You can create your own certificate with a simple openssl tool - you need to +do it if you have none and I highly recommend to create one in any case. To +create it, cd to /etc/stunnel and type:</p> +<p></p><blockquote><code>openssl req -new -x509 -days 3650 -nodes -out +stunnel.pem -keyout stunnel.pem</code></blockquote><p></p> +<p>That command will ask you a number of questions. Provide some answer for +them. If you are unsure, read +<a href="http://www.stunnel.org/faq/certs.html"> +http://www.stunnel.org/faq/certs.html</a>. After the command has finished, you +should have a usable stunnel.pem in your working directory.</p> +<p>Next is to create a configuration file for stunnel. It will direct stunnel +what to do. You can used the following basic file:</p> +<p></p><blockquote><code></code><pre>; Certificate/key is needed in server mode<br>cert = /etc/stunnel/stunnel.pem<br><br><i>; Some debugging stuff useful for troubleshooting<br>debug = 7<br>foreground=yes</i> + +[ssyslog] +accept = 60514 +connect = 61514</pre> +</blockquote><p></p> +<p>Save this file to e.g. /etc/stunnel/syslog-server.conf. Please note that the +settings in <i>italics</i> are for debugging only. They run stunnel +with a lot of debug information in the foreground. This is very valuable while +you setup the system - and very useless once everything works well. So be sure +to remove these lines when going to production.</p> +<p>Finally, you need to start the stunnel daemon. Under Debian, this is done via +"stunnel /etc/stunnel/syslog.server.conf". If you have enabled the debug +settings, you will immediately see a lot of nice messages.</p> +<p>Now you have stunnel running, but it obviously unable to talk to rsyslog - +because it is not yet running. If not already done, configure it so that it does +everything you want. If in doubt, you can simply copy /etc/syslog.conf to /etc/rsyslog.conf +and you probably have what you want. The really important thing in rsyslogd +configuration is that you must make it listen to tcp port 61514 (remember: this +is where stunnel send the messages to). Thankfully, this is easy to achive: just +add "-t 61514" to the rsyslogd startup options in your system startup script. +After done so, start (or restart) rsyslogd.</p> +<p>The server should now be fully operational.</p> +<h3>Client Setup</h3> +<p>The client setup is simpler. Most importantly, you do not need a certificate +(of course, you can use one if you would like to authenticate the client, but +this is beyond the scope of this paper). So the basic thing you need to do is +create the stunnel configuration file.</p> +<p></p><blockquote><code></code><pre><i>; Some debugging stuff useful for troubleshooting<br>debug = 7<br>foreground=yes</i> + +<b>client=yes</b> + +[ssyslog] +accept = 127.0.0.1:61514 +connect = <font color="#ff0000">192.0.2.1</font>:60514<br></pre> +</blockquote><p></p> +<p>Again, the text in <i>italics</i> is for debugging purposes only. I suggest +you leave it in during your initial testing and then remove it. The most +important difference to the server configuration outlined above is the "client=yes" +directive. It is what makes this stunnel behave like a client. The accept +directive binds stunnel only to the local host, so that it is protected from +receiving messages from the network (somebody might fake to be the local sender). +The address "192.0.2.1" is the address of the server machine. You must change it +to match your configuration. Save this file to /etc/stunnel/syslog-client.conf.</p> +<p>Then, start stunnel via "stunnel4 /etc/stunnel/syslog-client.conf". Now +you should see some startup messages. If no errors appear, you have a running +client stunnel instance.</p> +<p>Finally, you need to tell rsyslogd to send data to the remote host. In stock +syslogd, you do this via the "@host" forwarding directive. The same works with +rsyslog, but it suppports extensions to use tcp. Add the following line to your +/etc/rsyslog.conf:</p> +<p></p><blockquote><code></code><pre>*.* @<font color="#ff0000">@</font>127.0.0.1:61514<br></pre> +</blockquote><i><p></p> + +</i> + +<p>Please note the double at-sign (@@). This is no typo. It tells rsyslog to use +tcp instead of udp delivery. In this sample, all messages are forwarded to the +remote host. Obviously, you may want to limit this via the usual rsyslog.conf +settings (if in doubt, use man rsyslog.con).</p> +<p>You do not need to add any special startup settings to rsyslog on the client. +Start or restart rsyslog so that the new configuration setting takes place.</p> +<h3>Done</h3> +<p>After following these steps, you should have a working secure syslog +forwarding system. To verify, you can type "logger test" or a similar smart +command on the client. It should show up in the respective server log file. If +you dig out you sniffer, you should see that the traffic on the wire is actually +protected. In the configuration use above, the two stunnel endpoints should be +quite chatty, so that you can follow the action going on on your system.</p> +<p>If you have only basic security needs, you can probably just remove the debug +settings and take the rest of the configuration to production. If you are +security-sensitve, you should have a look at the various stunnel settings that +help you further secure the system.</p> +<h2>Preventing Systems from talking directly to the rsyslog Server</h2> +<p>It is possible that remote systems (or attackers) talk to the rsyslog server +by directly connecting to its port 61514. Currently (July of 2005), rsyslog does +not offer the ability to bind to the local host, only. This feature is planned, +but as long as it is missing, rsyslog must be protected via a firewall. This can +easily be done via e.g iptables. Just be sure not to forget it.</p> +<h2>Conclusion</h2> +<p>With minumal effort, you can set up a secure logging infrastructure employing +ssl encrypted syslog message transmission. As a side note, you also have the +benefit of reliable tcp delivery which is far less prone to message loss than +udp.</p> +<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>2005-07-22 * + <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Initial Version created</li> + <li>2005-07-26 * + <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Some text brush-up, hyperlinks added</li> + <li>2005-08-03 * + <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> + * license added</li><li>2008-05-05 * <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> + * updated to reflect native TLS capability of rsyslog 3.19.0 and above</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>
\ No newline at end of file diff --git a/doc/rsyslog_tls.html b/doc/rsyslog_tls.html new file mode 100644 index 00000000..7d156c3a --- /dev/null +++ b/doc/rsyslog_tls.html @@ -0,0 +1,307 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>TLS (SSL) Encrypting syslog</title> + +<meta name="KEYWORDS" content="syslog encryption, rsyslog, secure syslog, tcp, reliable, howto, ssl, tls"> +</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-05-06)</i></small></p> +<h2>Abstract</h2> +<p><i><b>In this paper, I describe how to encrypt <a href="http://www.monitorware.com/en/topics/syslog/">syslog</a> +messages on the network.</b> Encryption +is vital to keep the confidiental content of syslog messages secure. I +describe the overall +approach and provide an HOWTO do it with <a href="http://www.rsyslog.com">rsyslog's</a> TLS +features. </i></p> +<p>Please +note that TLS is the more secure successor of SSL. While people often +talk about "SSL encryption" they actually mean "TLS encryption". So +don't look any further if you look for how to SSL-encrypt syslog. You +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>. +<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 +some environments, this is no problem at all. In others, it is a huge +setback, probably even preventing deployment of syslog solutions. +Thankfully, there are easy ways to encrypt syslog +communication. </p> +The traditional approach involves <a href="rsyslog_stunnel.html">running +a wrapper like stunnel around the syslog session</a>. This works +quite well and is in widespread use. However, it is not thightly +coupled with the main syslogd and some, even severe, problems can +result from this (follow a mailing list thread that describes <a href="http://lists.adiscon.net/pipermail/rsyslog/2008-March/000580.html">total +loss of syslog messages due to stunnel mode</a> and the <a href="http://rgerhards.blogspot.com/2008/04/on-unreliability-of-plain-tcp-syslog.html">unreliability +of TCP syslog</a>). +<p><a href="gssapi.html">Rsyslog supports syslog via +GSSAP</a>I since long to overcome these limitatinos. However, +syslog via GSSAPI is a rsyslog-exclusive transfer mode and it requires +a proper Kerberos environment. As such, it isn't a really universal +solution. The <a href="http://www.ietf.org/">IETF</a> +has begun standardizing syslog over plain tcp over +TLS for a while now. While I am not fully satisfied with the results so +far, this obviously has the potential to become the long-term +solution. The Internet Draft in question, syslog-transport-tls has been +dormant for some time but is now (May of 2008) again being worked on. I +expect it to turn into a RFC within the next 12 month (but don't take +this for granted ;)). I didn't want to wait for it, because there +obviously is need for TLS syslog right now (and, honestly, I have +waited long enough...). Consequently, I have +implemented the current draft, with some interpretations I made (there +will be a compliance doc soon). So in essence, a TLS-protected syslog +transfer mode is available right now. As a side-note, Rsyslog +is the world's first +implementation of syslog-transport-tls.</p> +<p>Please note that in theory it should be compatible with other, +non IETF syslog-transport-tls implementations. If you would like to run +it with something else, please let us know so that we can create a +compatibility list (and implement compatbility where it doesn't yet +exist). </p> +<h2>Overall System Setup</h2> +<p>Encryption requires a reliable stream. So It will not work +over UDP syslog. In rsyslog, network transports utilize a so-called +"network stream layer" (netstream for short). This layer provides a +unified view of the transport to the application layer. The plain TCP +syslog sender and receiver are the upper layer. The driver layer +currently consists of the "ptcp" and "gtls" library plugins. "ptcp" +stands for "plain tcp" and is used for unencrypted message transfer. It +is also used internally by the gtls driver, so it must always be +present on a system. The "gtls" driver is for GnutTLS, a TLS library. +It is used for encrypted message transfer. In the future, additional +drivers will become available (most importantly, we would like to +include a driver for NSS).</p> +<p>What you need to do to build an encrypted syslog channel is to +simply use the proper netstream drivers on both the client and the +server. Client, in the sense of this document, is the rsyslog system +that is sending syslog messages to a remote (central) loghost, which is +called the server. In short, the setup is as follows:</p> +<p><b>Client</b></p> +<ul> +<li>forwards messages via plain tcp syslog using gtls netstream +driver to central sever on port 10514<br> +</li> +</ul> +<p><b>Server</b></p> +<ul> +<li>accept incoming messages via plain tcp syslog using gtls +netstream driver on port 10514</li> +</ul> +<h2>Setting up the system</h2> +<h3>Server Setup</h3> +<p>At the server, you need to have a digital certificate. That +certificate enables SSL operation, as it provides the necessary crypto +keys being used to secure the connection. There is a set of default +certificates in ./contrib/gnutls. These are key.pem and cert.pem. These +are good for testing. If you use it in production, +it is very easy to break into your secure channel as everybody is able +to get hold of your private key. So it is a good idea to +generate the key and certificate yourself.</p> +<p>You also need a root CA certificate. Again, there is a sample +CA certificate in ./contrib/gnutls, named ca.cert. It is suggested to +generate your own.</p> +<p>To configure the server, you need to tell it where are its +certificate files, to use the gtls driver and start up a listener. This +is done as follows:<br> +</p> +<blockquote><code></code> +<pre># make gtls driver the default +$DefaultNetstreamDriver gtls + +# certificate files +$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem +$DefaultNetstreamDriverCertFile /path/to/contrib/gnutls/cert.pem +$DefaultNetstreamDriverKeyFile /path/to/contrib/gnutls/key.pem + +$ModLoad /home/rger/proj/rsyslog/plugins/imtcp/.libs/imtcp # load listener + +$InputTCPServerStreamDriverMode 1 # run driver in TLS-only mode +$InputTCPServerStreamDriverAuthMode anon # client is NOT authenticated +$InputTCPServerRun 10514 # start up listener at port 10514 +</pre> +</blockquote> +This is all you need to do. You can use the rest of your rsyslog.conf +together with this configuration. The way messages are received does +not interfer with any other option, so you are able to do anything else +you like without any restrictions. +<p>Restart (or HUP) rsyslogd. The server should now be fully +operational.</p> +<h3>Client Setup</h3> +<p>The client setup is equally simple. You need less +certificates, just the CA cert. </p> +<blockquote> +<pre># certificate files - just CA for a client +$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem + +# set up the action +$DefaultNetstreamDriver gtls # use gtls netstream driver +$ActionSendStreamDriverMode 1 # require TLS for the connection +$ActionSendStreamDriverAuthMode anon # server is NOT authenticated +*.* @@(o)server.example.net:10514 # send (all) messages + +</pre> +</blockquote> +<p>Note that we use the regular TCP forwarding syntax (@@) here. +There is nothing special, because the encryption is handled by the +netstream driver. So I have just forwarded every message (*.*) for +simplicity - you can use any of rsyslog's filtering capabilities (like +epxression-based filters or regular expressions). Note that the "(o)" +part is not strictly necessary. It selects octet-based framing, which +provides compatiblity to IETF's syslog-transport-tls draft. Besides +compatibility, this is also a more reliable transfer mode, so I suggest +to always use it.</p> +<h3>Done</h3> +<p>After +following these steps, you should have a working secure +syslog forwarding system. To verify, you can type "logger test" or a +similar "smart" command on the client. It should show up in the +respective server log file. If you dig out your sniffer, you should see +that the traffic on the wire is actually protected.</p> +<h3>Limitations</h3> +<p>The current implementation has a number of limitations. These +are +being worked on. Most importantly, neither the client nor the server +are authenticated. So while the message transfer is encrypted, you can +not be sure which peer you are talking to. Please note that this is a +limitation found in most real-world SSL syslog systems. Of course, that +is not an excuse for not yet providing this feature - but it tells you +that it is acceptable and can be worked around by proper firewalling, +ACLs and other organizational measures. Mutual authentication will be +added shortly to rsyslog.</p> +<p>Secondly, the plain tcp syslog listener +can currently listen to a single port, in a single mode. So if you use +a TLS-based listener, you can not run unencrypted syslog on the same +instance at the same time. A work-around is to run a second rsyslogd +instance. This limitation, too, is scheduled to be removed soon.</p> +<p>The +RELP transport can currently not be protected by TLS. A work-around is +to use stunnel. TLS support for RELP will be added once plain TCP +syslog has sufficiently matured.</p> +<h2>Certificates</h2> +<p>In order to be really secure, certificates are needed. This is +a short summary on how to generate the necessary certificates with +GnuTLS' certtool. You can also generate certificates via other tools, +but as we currently support GnuTLS as the only TLS library, we thought +it is a good idea to use their tools.<br> +</p> +<p>Note that this section aims at people who are not involved +with PKI at all. The main goal is to get them going in a reasonable +secure way. </p> +<h3>CA Certificate</h3> +<p>This is used to sign all of your other certificates. The CA +cert must be trusted by all clients and servers. The private key must +be well-protected and not given to any third parties. The certificate +itself can (and must) be distributed. To generate it, do the following:</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 authrity. The certificate is used to +sign other certificates.<br> +</li> +<li>You need to distribute this certificate +to all peers and you need to point to it via the +$DefaultNetstreamDriverCAFile config directive. All other certificates +will be issued by this CA.<br> +Important: do only distribute the ca.pem, NOT ca-key.pem (the private +key). Distributing the CA private key would totally breach security as +everybody could issue new certificates on the behalf of this CA. +</li> +</ol> +<h3>Individual Peer Certificate</h3> +<p>Each peer (be it client, server or both), needs a certificate +that conveys its identity. Access control is based on these +certificates. You can, for example, configure a server to accept +connections only from configured clients. The client ID is taken from +the client instances certificate. So as a general rule of thumb, you +need to create a certificate for each instance of rsyslogd that you +run. That instance also needs the private key, so that it can properly +decrypt the traffic. Safeguard the peer's private key file. If somebody +gets hold of it, it can malicously pretend to be the compromised host. +If such happens, regenerate the certificate and make sure you use a +different name instead of the compromised one (if you use name-based +authentication). </p> +<p>These are the steps to generate the indivudual certificates +(repeat: you need to do this for every instance, do NOT share the +certificates created in this step):</p> +<ol> +<li>generate a private key (do NOT mistake this with the CA's +private key - this one is different):<br> +<pre>certtool --generate-privkey --outfile key.pem</pre> +Again, this takes a short while.</li> +<li>generate a certificate request:<br> +<pre>certtool --generate-request --load-privkey key.pem --outfile request.pem</pre> +If you do not have the CA's private key (because you are not authorized +for this), you can send the certificate request to the responsible +person. If you do this, you can skip the remaining steps, as the CA +will provide you with the final certificate. If you submit the request +to the CA, you need to tell the CA the answers that you would normally +provide in step 3 below. +</li> +<li>Sign (validate, authorize) the certificate request and +generate the instances certificate. You need to have the CA's +certificate and private key for this:<br> +<pre>certtool --generate-certificate --load-request request.pem --outfile cert.pem \<br> --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem</pre> +Answer questions as follows: Cert does not belogn to an authority; it +is a TLS web server and client certificate; the dnsName MUST be the +name of the peer in question (e.g. centralserver.example.net) - this is +the name used for authenticating the peers. Please note that you may +use an IP address in dnsName. This is a good idea if you would like to +use default server authentication and you use selector lines with IP +addresses (e.g. "*.* @@192.168.0.1") - in that case you need to select +a dnsName of 192.168.0.1. But, of course, changing the server IP then +requires generating a new certificate.</li> +</ol> +After you have generated the certificate, you need to place it onto the +local machine running rsyslogd. Specify the certificate and key via the +$DefaultNetstreamDriverCertFile /path/to/cert.pem and +$DefaultNetstreamDriverKeyFile /path/to/key.pem configuration +directives. Make sure that nobody has access to key.pem, as that would +breach security. And, once again: do NOT use these files on more than +one instance. Doing so would prevent you from distinguising between the +instances and thus would disable useful authentication. +<h3>Troubleshooting Certificates</h3> +<p>If you experience trouble with your certificate setup, it may +be +useful to get some information on what is contained in a specific +certificate (file). To obtain that information, do </p> +<pre>$ certtool --certificate-info --infile cert.pem</pre> +<p>where "cert.pem" can be replaced by the various certificate pem files (but it does not work with the key files).</p> +<h2>Conclusion</h2> +<p>With minumal effort, you can set up a secure logging +infrastructure employing TLS encrypted syslog message transmission.</p> +<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-05-06 * <a href="http://www.gerhards.net/rainer">Rainer +Gerhards</a> * Initial Version created</li><li>2008-05-26 * <a href="http://www.gerhards.net/rainer">Rainer +Gerhards</a> * added information about certificates</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/queueWorkerLogic.dia b/doc/src/queueWorkerLogic.dia Binary files differindex 068ea50c..068ea50c 100644 --- a/doc/queueWorkerLogic.dia +++ b/doc/src/queueWorkerLogic.dia diff --git a/doc/src/tls.dia b/doc/src/tls.dia Binary files differnew file mode 100644 index 00000000..77e5d185 --- /dev/null +++ b/doc/src/tls.dia diff --git a/doc/src/tls_cert.dia b/doc/src/tls_cert.dia Binary files differnew file mode 100644 index 00000000..e76431df --- /dev/null +++ b/doc/src/tls_cert.dia diff --git a/doc/src/tls_cert_100.dia b/doc/src/tls_cert_100.dia Binary files differnew file mode 100644 index 00000000..baed5e0f --- /dev/null +++ b/doc/src/tls_cert_100.dia diff --git a/doc/src/tls_cert_ca.dia b/doc/src/tls_cert_ca.dia Binary files differnew file mode 100644 index 00000000..7ce27a8d --- /dev/null +++ b/doc/src/tls_cert_ca.dia diff --git a/doc/status.html b/doc/status.html index 63a3f588..47cd0700 100644 --- a/doc/status.html +++ b/doc/status.html @@ -2,22 +2,22 @@ <html><head><title>rsyslog status page</title></head> <body> <h2>rsyslog status page</h2> -<p>This page reflects the status as of 2008-04-15.</p> +<p>This page reflects the status as of 2008-06-27.</p> <h2>Current Releases</h2> -<p><b>development:</b> 3.17.1 - -<a href="http://www.rsyslog.com/Article213.phtml">change log</a> - -<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-98.phtml">download</a> +<p><b>development:</b> 3.19.7 [2008-06-11] - +<a href="http://www.rsyslog.com/Article240.phtml">change log</a> - +<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-112.phtml">download</a> -<br><b>beta:</b> 3.15.1 - -<a href="http://www.rsyslog.com/Article210.phtml">change log</a> - -<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-97.phtml">download</a></p> +<br><b>beta:</b> 3.17.4 [2008-06-16] - +<a href="http://www.rsyslog.com/Article242.phtml">change log</a> - +<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-109.phtml">download</a></p> -<p><b>v3 stable:</b> 3.14.2 - <a href="http://www.rsyslog.com/Article209.phtml">change log</a> - -<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-96.phtml">download</a> +<p><b>v3 stable:</b> 3.16.2 [2008-06-25] - <a href="http://www.rsyslog.com/Article244.phtml">change log</a> - +<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-114.phtml">download</a> -<br><b>v2 stable:</b> 2.0.4 - <a href="http://www.rsyslog.com/Article197.phtml">change log</a> - -<a href="http://www.rsyslog.com/Downloads-index-req-getit-lid-90.phtml">download</a> +<br><b>v2 stable:</b> 2.0.5 [2008-05-15] - <a href="http://www.rsyslog.com/Article226.phtml">change log</a> - +<a href="http://www.rsyslog.com/Downloads-req-viewdownloaddetails-lid-104.phtml">download</a> <br>v0 and v1 are deprecated and no longer supported. If you absolutely do not like to upgrade, you may consider purchasing a <a href="professional_support.html">commercial rsyslog support package</a>. Just let us point diff --git a/doc/tls_cert.jpg b/doc/tls_cert.jpg Binary files differnew file mode 100644 index 00000000..920e998d --- /dev/null +++ b/doc/tls_cert.jpg diff --git a/doc/tls_cert_100.jpg b/doc/tls_cert_100.jpg Binary files differnew file mode 100644 index 00000000..beeedc58 --- /dev/null +++ b/doc/tls_cert_100.jpg diff --git a/doc/tls_cert_ca.html b/doc/tls_cert_ca.html new file mode 100644 index 00000000..7427bb03 --- /dev/null +++ b/doc/tls_cert_ca.html @@ -0,0 +1,163 @@ +<!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): </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_ca.jpg b/doc/tls_cert_ca.jpg Binary files differnew file mode 100644 index 00000000..f2da0454 --- /dev/null +++ b/doc/tls_cert_ca.jpg diff --git a/doc/tls_cert_errmsgs.html b/doc/tls_cert_errmsgs.html new file mode 100644 index 00000000..d002174c --- /dev/null +++ b/doc/tls_cert_errmsgs.html @@ -0,0 +1,103 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><title>TLS-protected syslog: error messages</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>Error Messages</h3> +<p>This page covers error message you may see when setting up +<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 href="http://www.rsyslog.com">rsyslog</a> with TLS. Please note that many +of the message stem back to the TLS library being used. In those cases, there is +not always a good explanation available in rsyslog alone. +<p>A single error typically results in two or more message being emitted: (at +least) one is the actual error cause, followed by usually one message with additional +information (like certificate contents). In a typical system, these message should +immediately follow each other in your log. Kepp in mind that they are reported +as syslog.err, so you need to capture these to actually see errors (the default +rsyslog.conf's shipped by many systems will do that, recording them e.g. in +/etc/messages). +<h3>certificate invalid</h3> +<p>Sample: +<code> +not permitted to talk to peer, certificate invalid: <font color="red">insecure algorithm</font> +</code> +<p>This message may occur during connection setup. It indicates that the remote peer's +certificate can not be accepted. The reason for this is given in the message part that +is shown in red. Please note that this red part directly stems back to the TLS library, +so rsyslog does acutally not have any more information about the reason. +<p>With GnuTLS, the following reasons have been seen in practice: +<h4>insecure algorith</h4> +<p>The certificate contains information on which encryption algorithms are to be used. +This information is entered when the certificate is created. +Some older alogrithms are no longer secure and the TLS library does not accept +them. Thus the connection request failed. The cure is to use a certificate with sufficiently secure +alogorithms. +<p>Please note that noi encryption algorithm is totally secure. It only is secure based +on our current knowledge AND on computing power available. As computers get more and more +powerful, previously secure algorithms become insecure over time. As such, algorithms +considered secure today may not be accepted by the TLS library in the future. +<p>So in theory, after a system upgrade, a connection request may fail with the "insecure +algorithm" failure without any change in rsyslog configuration or certificates. This could be +caused by a new perception of the TLS library of what is secure and what not. +<h3>GnuTLS error -64</h3> +<p>Sample: <code>unexpected GnuTLS error -64 in nsd_gtls.c:517: Error while reading file.</code> +<p>This error points to an encoding error witht the pem file in question. It means "base 64 encoding error". +From my experience, it can be caused by a couple of things, some of them not obvious: +<ul> +<li>You specified a wrong file, which is not actually in .pem format +<li>The file was incorrectly generated +<li>I think I have also seen this when I accidently swapped private key files and +certificate files. So double-check the type of file you are using. +<li>It may even be a result of an access (permission) problem. In theory, that +should lead to another error, but in practice it sometimes seems to lead to +this -64 error. +</ul> +<h3>info on invalid cert</h3> +<p>Sample: +<code> +info on invalid cert: peer provided 1 certificate(s). Certificate 1 info: certificate valid from Wed Jun 18 11:45:44 2008 to Sat Jun 16 11:45:53 2018; Certificate public key: RSA; DN: C=US,O=Sample Corp,OU=Certs,L=Somehwere,ST=CA,CN=somename; Issuer DN: C=US,O=Sample Corp,OU=Certs,L=Somewhere,ST=CA,CN=somename,EMAIL=xxx@example.com; SAN:DNSname: machine.example.net; +</code> +<p>This is <b>not</b> an error message in itself. It always follows the actual error message and +tells you what is seen in the peer's certificate. This is done to give you a chance to evaluate +the certificate and better understand why the initial error message was issued. +<p>Please note that you can NOT diagnose problems based on this message alone. It follows +in a number of error cases and does not pinpoint any problems by itself. +<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_machine.html b/doc/tls_cert_machine.html new file mode 100644 index 00000000..0d2955f7 --- /dev/null +++ b/doc/tls_cert_machine.html @@ -0,0 +1,165 @@ +<!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 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. +<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 challenge password: +[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. +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> +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 new file mode 100644 index 00000000..7973532b --- /dev/null +++ b/doc/tls_cert_scenario.html @@ -0,0 +1,63 @@ +<!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 new file mode 100644 index 00000000..51ad7bed --- /dev/null +++ b/doc/tls_cert_server.html @@ -0,0 +1,118 @@ +<!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>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 /home/rger/proj/rsyslog/plugins/imuxsock/.libs/imuxsock # local messages +$ModLoad /home/rger/proj/rsyslog/plugins/imtcp/.libs/imtcp + +# 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> |
