diff options
author | Rainer Gerhards <rgerhards@adiscon.com> | 2008-05-06 10:23:35 +0200 |
---|---|---|
committer | Rainer Gerhards <rgerhards@adiscon.com> | 2008-05-06 10:23:35 +0200 |
commit | 4ec4f4ddae4285adf0a40618360ec5cea02d85c3 (patch) | |
tree | 0f9951d4c9ed95331194a833fe72723dbd4dca84 /doc | |
parent | e7adb587845aedd332b5e2cb9d55e0add03571d1 (diff) | |
download | rsyslog-4ec4f4ddae4285adf0a40618360ec5cea02d85c3.tar.gz rsyslog-4ec4f4ddae4285adf0a40618360ec5cea02d85c3.tar.xz rsyslog-4ec4f4ddae4285adf0a40618360ec5cea02d85c3.zip |
updated doc set to reflect TLS support
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/features.html | 35 | ||||
-rw-r--r-- | doc/rsyslog_ng_comparison.html | 33 | ||||
-rw-r--r-- | doc/rsyslog_stunnel.html | 488 | ||||
-rw-r--r-- | doc/rsyslog_tls.html | 170 |
5 files changed, 452 insertions, 275 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 6eb82b81..90be2725 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_stunnel.html \ syslog-protocol.html \ version_naming.html \ diff --git a/doc/features.html b/doc/features.html index f9d17818..9fbebedf 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 (Deceber 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 @@ -105,11 +118,9 @@ to the bugzilla tracker.</p> <ul> <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 @@ -122,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> +</body></html>
\ No newline at end of file diff --git a/doc/rsyslog_ng_comparison.html b/doc/rsyslog_ng_comparison.html index 0d57a374..72fee210 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 @@ -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 @@ -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> + +</body></html>
\ No newline at end of file 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..c0ebb9c8 --- /dev/null +++ b/doc/rsyslog_tls.html @@ -0,0 +1,170 @@ +<!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.<i></i></p> +<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<br>$DefaultNetstreamDriver gtls<br><br># certificate files<br>$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem<br>$DefaultNetstreamDriverCertFile /path/to/contrib/gnutls/cert.pem<br>$DefaultNetstreamDriverKeyFile /path/to/contrib/gnutls/key.pem<br><br>$ModLoad /home/rger/proj/rsyslog/plugins/imtcp/.libs/imtcp # load listener<br><br>$InputTCPServerStreamDriverMode 1 # run driver in TLS-only mode<br>$InputTCPServerRun 10514 # start up listener at port 10514<br></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<br>$DefaultNetstreamDriverCAFile /path/to/contrib/gnutls/ca.pem<br><br># set up the action<br>$DefaultNetstreamDriver gtls # use gtls netstream driver<br>$ActionSendStreamDriverMode 1 # require TLS for the connection<br>*.* @@(o)server.example.net:10514 # send (all) messages<br><br></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>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></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 |