diff options
Diffstat (limited to 'doc/rsyslog_stunnel.html')
| -rw-r--r-- | doc/rsyslog_stunnel.html | 249 |
1 files changed, 0 insertions, 249 deletions
diff --git a/doc/rsyslog_stunnel.html b/doc/rsyslog_stunnel.html deleted file mode 100644 index f0c0b3a..0000000 --- a/doc/rsyslog_stunnel.html +++ /dev/null @@ -1,249 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html><head> -<a href="features.html">back</a> - -<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 straightforward 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> -<p>[<a href="manual.html">manual index</a>] -[<a href="rsyslog_conf.html">rsyslog.conf</a>] -[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> -<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 2 or higher.</font></p> - -</body></html> |