diff options
Diffstat (limited to '')
| -rw-r--r-- | source/historical/index.rst | 13 | ||||
| -rw-r--r-- | source/historical/module_devel.rst | 104 | ||||
| -rw-r--r-- | source/historical/multi_ruleset_legacy_format_samples.rst | 199 | ||||
| -rw-r--r-- | source/historical/php_syslog_ng.rst | 156 | ||||
| -rw-r--r-- | source/historical/stunnel.rst | 277 |
5 files changed, 749 insertions, 0 deletions
diff --git a/source/historical/index.rst b/source/historical/index.rst new file mode 100644 index 0000000..0b90205 --- /dev/null +++ b/source/historical/index.rst @@ -0,0 +1,13 @@ +Historical Documents +-------------------- +This part of the documentation set contains historical documents +which are still of interest or may be useful in some more exotic +environments. + +.. toctree:: + :maxdepth: 2 + + php_syslog_ng + stunnel + multi_ruleset_legacy_format_samples + module_devel diff --git a/source/historical/module_devel.rst b/source/historical/module_devel.rst new file mode 100644 index 0000000..4306bc3 --- /dev/null +++ b/source/historical/module_devel.rst @@ -0,0 +1,104 @@ +Developing rsyslog modules (outdated) +===================================== + +*Written by `Rainer Gerhards* <https://rainer.gerhards.net>`_ *(2007-07-28)* + +**This document is outdated and primarily contains historical +information. Do not trust it to build code. It currently is under +review.** + +Overview +-------- + +In theory, modules provide input and output, among other functions, in +rsyslog. In practice, modules are only utilized for output in the +current release. The module interface is not yet completed and a moving +target. We do not recommend to write a module based on the current +specification. If you do, please be prepared that future released of +rsyslog will probably break your module. + +A goal of modularization is to provide an easy to use plug-in interface. +However, this goal is not yet reached and all modules must be statically +linked. + +Module "generation" +------------------- + +There is a lot of plumbing that is always the same in all modules. For +example, the interface definitions, answering function pointer queries +and such. To get rid of these laborious things, I generate most of them +automatically from a single file. This file is named module-template.h. +It also contains the current best description of the interface +"specification". + +One thing that can also be achieved with it is the capability to cope +with a rapidly changing interface specification. The module interface is +evolving. Currently, it is far from being finished. As I moved the +monolithic code to modules, I needed (and still need) to make many +"non-clean" code hacks, just to get it working. These things are now +gradually being removed. However, this requires frequent changes to the +interfaces, as things move in and out while working towards a clean +interface. All the interim is necessary to reach the goal. This +volatility of specifications is the number one reasons I currently +advise against implementing your own modules (hint: if you do, be sure +to use module-template.h and be prepared to fix newly appearing and +disappearing data elements). + +Naming Conventions +------------------ + +Source +~~~~~~ + +Output modules, and only output modules, should start with a file name +of "om" (e.g. "omfile.c", "omshell.c"). Similarly, input modules will +use "im" and filter modules "fm". The third character shall not be a +hyphen. + +Module Security +--------------- + +Modules are directly loaded into rsyslog's address space. As such, any +module is provided a big level of trust. Please note that further module +interfaces might provide a way to load a module into an isolated address +space. This, however, is far from being completed. So the number one +rule about module security is to run only code that you know you can +trust. + +To minimize the security risks associated with modules, rsyslog provides +only the most minimalistic access to data structures to its modules. For +that reason, the output modules do not receive any direct pointers to +the selector\_t structure, the syslogd action structures and - most +importantly - the msg structure itself. Access to these structures would +enable modules to access data that is none of their business, creating a +potential security weakness. + +Not having access to these structures also simplifies further queueing +and error handling cases. As we do not need to provide e.g. full access +to the msg object itself, we do not need to serialize and cache it. +Instead, strings needed by the module are created by syslogd and then +the final result is provided to the module. That, for example, means +that in a queued case $NOW is the actual timestamp of when the message +was processed, which may be even days before it being dequeued. Think +about it: If we wouldn't cache the resulting string, $NOW would be the +actual date if the action were suspended and messages queued for some +time. That could potentially result in big confusion. + +It is thought that if an output module actually needs access to the +while msg object, we will (then) introduce a way to serialize it (e.g. +to XML) in the property replacer. Then, the output module can work with +this serialized object. The key point is that output modules never deal +directly with msg objects (and other internal structures). Besides +security, this also greatly simplifies the job of the output module +developer. + +Action Selectors +---------------- + +Modules (and rsyslog) need to know when they are called. For this, there +must an action identification in selector lines. There are two +syntaxes: the single-character syntax, where a single characters +identifies a module (e.g. "\*" for a wall message) and the modules +designator syntax, where the module name is given between colons (e.g. +":ommysql:"). The single character syntax is depreciated and should not +be used for new plugins. diff --git a/source/historical/multi_ruleset_legacy_format_samples.rst b/source/historical/multi_ruleset_legacy_format_samples.rst new file mode 100644 index 0000000..607f79f --- /dev/null +++ b/source/historical/multi_ruleset_legacy_format_samples.rst @@ -0,0 +1,199 @@ +Legacy Format Samples for Multiple Rulesets +=========================================== + +This chapter complements rsyslog's documentation of +:doc:`rulesets <../concepts/multi_ruleset>`. +While the base document focusses on RainerScript format, it +does not provide samples in legacy format. These are included +in this document. + +**Important:** do **not** use legacy ruleset definitions for new +configurations. Especially with rulesets, legacy format is extremely +hard to get right. The information in this page is included in order +to help you understand already existing configurations using the +ruleset feature. We even recommend to convert any such configs +to RainerScript format because of its increased robustness +and simplicity. + +Legacy ruleset support was available starting with version 4.5.0 +and 5.1.1. + +Split local and remote logging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Let's say you have a pretty standard system that logs its local messages +to the usual bunch of files that are specified in the default +rsyslog.conf. As an example, your rsyslog.conf might look like this: + +:: + + # ... module loading ... + # The authpriv file has restricted access. + authpriv.* /var/log/secure + # Log all the mail messages in one place. + mail.* /var/log/maillog + # Log cron stuff + cron.* /var/log/cron + # Everybody gets emergency messages + *.emerg * + ... more ... + +Now, you want to add receive messages from a remote system and log these +to a special file, but you do not want to have these messages written to +the files specified above. The traditional approach is to add a rule in +front of all others that filters on the message, processes it and then +discards it: + +:: + + # ... module loading ... + # process remote messages + :fromhost-ip, isequal, "192.0.2.1" /var/log/remotefile + & ~ + # only messages not from 192.0.21 make it past this point + + # The authpriv file has restricted access. + authpriv.* /var/log/secure + # Log all the mail messages in one place. + mail.* /var/log/maillog + # Log cron stuff + cron.* /var/log/cron + # Everybody gets emergency messages + *.emerg * + ... more ... + +Note the tilde character, which is the discard action!. Also note that +we assume that 192.0.2.1 is the sole remote sender (to keep it simple). + +With multiple rulesets, we can simply define a dedicated ruleset for the +remote reception case and bind it to the receiver. This may be written +as follows: + +:: + + # ... module loading ... + # process remote messages + # define new ruleset and add rules to it: + $RuleSet remote + *.* /var/log/remotefile + # only messages not from 192.0.21 make it past this point + + # bind ruleset to tcp listener + $InputTCPServerBindRuleset remote + # and activate it: + $InputTCPServerRun 10514 + + # switch back to the default ruleset: + $RuleSet RSYSLOG_DefaultRuleset + # The authpriv file has restricted access. + authpriv.* /var/log/secure + # Log all the mail messages in one place. + mail.* /var/log/maillog + # Log cron stuff + cron.* /var/log/cron + # Everybody gets emergency messages + *.emerg * + ... more ... + +Here, we need to switch back to the default ruleset after we have +defined our custom one. This is why I recommend a different ordering, +which I find more intuitive. The sample below has it, and it leads to +the same results: + +:: + + # ... module loading ... + # at first, this is a copy of the unmodified rsyslog.conf + # The authpriv file has restricted access. + authpriv.* /var/log/secure + # Log all the mail messages in one place. + mail.* /var/log/maillog + # Log cron stuff + cron.* /var/log/cron + # Everybody gets emergency messages + *.emerg * + ... more ... + # end of the "regular" rsyslog.conf. Now come the new definitions: + + # process remote messages + # define new ruleset and add rules to it: + $RuleSet remote + *.* /var/log/remotefile + + # bind ruleset to tcp listener + $InputTCPServerBindRuleset remote + # and activate it: + $InputTCPServerRun 10514 + +Here, we do not switch back to the default ruleset, because this is not +needed as it is completely defined when we begin the "remote" ruleset. + +Now look at the examples and compare them to the single-ruleset +solution. You will notice that we do **not** need a real filter in the +multi-ruleset case: we can simply use "\*.\*" as all messages now means +all messages that are being processed by this rule set and all of them +come in via the TCP receiver! This is what makes using multiple rulesets +so much easier. + +Split local and remote logging for three different ports +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example is almost like the first one, but it extends it a little +bit. While it is very similar, I hope it is different enough to provide +a useful example why you may want to have more than two rulesets. + +Again, we would like to use the "regular" log files for local logging, +only. But this time we set up three syslog/tcp listeners, each one +listening to a different port (in this example 10514, 10515, and 10516). +Logs received from these receivers shall go into different files. Also, +logs received from 10516 (and only from that port!) with "mail.\*" +priority, shall be written into a specif file and **not** be written to +10516's general log file. + +This is the config: + +:: + + # ... module loading ... + # at first, this is a copy of the unmodified rsyslog.conf + # The authpriv file has restricted access. + authpriv.* /var/log/secure + # Log all the mail messages in one place. + mail.* /var/log/maillog + # Log cron stuff + cron.* /var/log/cron + # Everybody gets emergency messages + *.emerg * + ... more ... + # end of the "regular" rsyslog.conf. Now come the new definitions: + + # process remote messages + + #define rulesets first + $RuleSet remote10514 + *.* /var/log/remote10514 + + $RuleSet remote10515 + *.* /var/log/remote10515 + + $RuleSet remote10516 + mail.* /var/log/mail10516 + & ~ + # note that the discard-action will prevent this messag from + # being written to the remote10516 file - as usual... + *.* /var/log/remote10516 + + # and now define listeners bound to the relevant ruleset + $InputTCPServerBindRuleset remote10514 + $InputTCPServerRun 10514 + + $InputTCPServerBindRuleset remote10515 + $InputTCPServerRun 10515 + + $InputTCPServerBindRuleset remote10516 + $InputTCPServerRun 10516 + +Note that the "mail.\*" rule inside the "remote10516" ruleset does not +affect processing inside any other rule set, including the default rule +set. + diff --git a/source/historical/php_syslog_ng.rst b/source/historical/php_syslog_ng.rst new file mode 100644 index 0000000..f8f9f2a --- /dev/null +++ b/source/historical/php_syslog_ng.rst @@ -0,0 +1,156 @@ +Using php-syslog-ng with rsyslog +================================ + +*Written by* `Rainer Gerhards <https://rainer.gerhards.net>`_ *(2005-08-04)* + +Note: it has been reported that this guide is somewhat outdated. Most +importantly, this guide is for the **original** php-syslog-ng and +**cannot** be used for it successor logzilla. Please +use the guide with care. Also, please note that **rsyslog's "native" web frontend +is** `Adiscon LogAnalyzer <http://www.phplogcon.org>`_, which provides best +integration and a lot of extra functionality. + +Abstract +-------- + +**In this paper, I describe how to use** +`php-syslog-ng <http://www.vermeer.org/projects/php-syslog-ng>`_ **with** +`rsyslogd <http://www.rsyslog.com/>`_. Php-syslog-ng is a popular web +interface to syslog data. Its name stem from the fact that it usually +picks up its data from a database created by +`syslog-ng <http://www.balabit.com/products/syslog_ng/>`_ and some +helper scripts. However, there is nothing syslog-ng specific in the +database. With rsyslogd's high customizability, it is easy to write to a +syslog-ng like schema. I will tell you how to do this, enabling you to +use php-syslog-ng as a front-end for rsyslogd - or save the hassle with +syslog-ng database configuration and simply go ahead and use rsyslogd +instead.* + +Overall System Setup +-------------------- + +The setup is pretty straightforward. Basically, php-syslog-ng's +interface to the syslogd is the database. We use the schema that +php-syslog-ng expects and make rsyslogd write to it in its format. +Because of this, php-syslog-ng does not even know there is no syslog-ng +present. + +Setting up the system +--------------------- + +For php-syslog-ng, you can follow its usual setup instructions. Just +skip any steps referring to configure syslog-ng. Make sure you create the +database schema in `MySQL <http://www.mysql.com/>`_. As of this writing, +the expected schema can be created via this script: + +:: + + CREATE DATABASE syslog + USE syslog + CREATE TABLE logs(host varchar(32) default NULL, + facility varchar(10) + default NULL, + priority varchar(10) default NULL, + level varchar(10) default NULL, + tag varchar(10) default NULL, + date date default NULL, + time time default NULL, + program varchar(15) default NULL, + msg text, + seq int(10) unsigned NOT NULL auto_increment, + PRIMARY KEY (seq), + KEY host (host), + KEY seq (seq), + KEY program (program), + KEY time (time), + KEY date (date), + KEY priority (priority), + KEY facility (facility + ) TYPE=MyISAM;`` + +Please note that at the time you are reading this paper, the schema +might have changed. Check for any differences. As we customize rsyslogd +to the schema, it is vital to have the correct one. If this paper is +outdated, `let me know <mailto:rgerhards@adiscon.com>`_ so that I can +fix it. + +Once this schema is created, we simply instruct rsyslogd to store +received data in it. I wont go into too much detail here. If you are +interested in some more details, you might find my paper "`Writing +syslog messages to MySQL <rsyslog_mysql.html>`_\ " worth reading. For +this article, we simply modify `rsyslog.conf <rsyslog_conf.html>`_\ so +that it writes to the database. That is easy. Just these two lines are +needed: + +:: + + $template syslog-ng,"insert into logs(host, facility, priority, tag, date, time, msg) values ('%HOSTNAME%', %syslogfacility%, %syslogpriority%, '%syslogtag%', '%timereported:::date-mysql%', '%timereported:::date-mysql%', '%msg%')", SQL + *.*, mysql-server,syslog,user,pass;syslog-ng + +These are just **two** lines. I have color-coded them so that you see +what belongs together (the colors have no other meaning). The green line +is the actual SQL statement being used to take care of the syslog-ng +schema. Rsyslogd allows you to fully control the statement sent to the +database. This allows you to write to any database format, including +your homegrown one (if you so desire). Please note that there is a small +inefficiency in our current usage: the +``'%timereported:::date-mysql%'`` +property is used for both the time +and the date (if you wonder about what all these funny characters mean, +see the `rsyslogd property replacer manual <property_replacer.html>`_) . +We could have extracted just the date and time parts of the respective +properties. However, this is more complicated and also adds processing +time to rsyslogd's processing (substrings must be extracted). So we take +a full mysql-formatted timestamp and supply it to MySQL. The sql engine +in turn discards the unneeded part. It works pretty well. As of my +understanding, the inefficiency of discarding the unneeded part in MySQL +is lower than the efficiency gain from using the full timestamp in +rsyslogd. So it is most probably the best solution. + +Please note that rsyslogd knows two different timestamp properties: one +is timereported, used here. It is the timestamp from the message itself. +Sometimes that is a good choice, in other cases not. It depends on your +environment. The other one is the timegenerated property. This is the +time when rsyslogd received the message. For obvious reasons, that +timestamp is consistent, even when your devices are in multiple time +zones or their clocks are off. However, it is not "the real thing". It's +your choice which one you prefer. If you prefer timegenerated ... simply +use it ;) + +The line in red tells rsyslogd which messages to log and where to store +it. The "\*.\*" selects all messages. You can use standard syslog +selector line filters here if you do not like to see everything in your +database. The ">" tells rsyslogd that a MySQL connection must be +established. Then, "mysql-server" is the name or IP address of the +server machine, "syslog" is the database name (default from the schema) +and "user" and "pass" are the logon credentials. Use a user with low +privileges, insert into the logs table is sufficient. "syslog-ng" is the +template name and tells rsyslogd to use the SQL statement shown above. + +Once you have made the changes, all you need to do is restart rsyslogd. +Then, you should see syslog messages flow into your database - and show +up in php-syslog-ng. + +Conclusion +---------- + +With minimal effort, you can use php-syslog-ng together with rsyslogd. +For those unfamiliar with syslog-ng, this configuration is probably +easier to set up then switching to syslog-ng. For existing rsyslogd +users, php-syslog-ng might be a nice add-on to their logging +infrastructure. + +Please note that the `MonitorWare +family <http://www.monitorware.com/en/>`_ (to which rsyslog belongs) +also offers a web-interface: `Adiscon LogAnalyzer`_. +From my point of view, obviously, **phpLogCon is the more natural choice +for a web interface to be used together with rsyslog**. It also offers +superb functionality and provides, for example,native display of Windows +event log entries. I have set up a `demo +server <http://demo.phplogcon.org/>`_., You can have a peek at it +without installing anything. + +References and Additional Material +---------------------------------- + +- `php-syslog-ng <http://www.vermeer.org/projects/php-syslog-ng>`_ diff --git a/source/historical/stunnel.rst b/source/historical/stunnel.rst new file mode 100644 index 0000000..90a3e06 --- /dev/null +++ b/source/historical/stunnel.rst @@ -0,0 +1,277 @@ +SSL Encrypting Syslog with Stunnel +================================== + +*Written by* `Rainer Gerhards <https://rainer.gerhards.net>`_ *(2005-07-22)* + +**HISTORICAL DOCUMENT** + +**Note: this is an outdated HISTORICAL document.** A much better description on +`securing syslog with TLS <http://www.rsyslog.com/doc/master/tutorials/tls_cert_summary.html>`_ +is available. + +Abstract +-------- + +**In this paper, I describe how to encrypt** +`syslog <http://www.monitorware.com/en/topics/syslog/>`_ **messages on the +network.** Encryption is vital to keep the confidential content of +syslog messages secure. I describe the overall approach and provide an +HOWTO do it with the help of `rsyslogd <http://www.rsyslog.com>`_ and +`stunnel <http://www.stunnel.org>`_.* + +Please note that starting with rsyslog 3.19.0, `rsyslog provides native +TLS/SSL encryption <rsyslog_tls.html>`_ without the need of stunnel. I +strongly recommend 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.\ ** + +Background +---------- + +**Syslog is a clear-text protocol. That means anyone with a sniffer can +have a peek at your data.** 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. + +The most straightforward solution would be that the syslogd itself +encrypts messages. Unfortunately, encryption is only standardized in +`RFC 3195 <http://www.monitorware.com/Common/en/glossary/rfc3195.php>`_. +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, +`EventReporter <http://www.eventreporter.com/en/>`_ 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 `IPSec <http://en.wikipedia.org/wiki/IPSec>`_, for +example). + +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. + +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 ;) + +In the rest of this document, I assume that you use rsyslog on both the +client and the server. For the samples, I use +`Debian <http://www.debian.org/>`_. Interestingly, there are some +annoying differences between stunnel implementations. For example, on +Debian a comment line starts with a semicolon (';'). On `Red +Hat <http://www.redhat.com>`_, it starts with a hash sign ('#'). So you +need to watch out for subtle issues when setting up your system. + +Overall System Setup +-------------------- + +In this 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: + +**Client** + +- rsyslog forwards message to stunnel local portal at port 61514 +- local stunnel forwards data via the network to port 60514 to its + remote peer + +**Server** + +- stunnel listens on port 60514 to connections from its client peers +- all connections are forwarded to the locally-running rsyslog + listening at port 61514 + +Setting up the system +--------------------- + +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. + +In my sample setup, I use only the bare minimum of options. For example, +I do not make the server check client certificates. 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, +`http://www.stunnel.org/faq/certs.html <http://www.stunnel.org/faq/certs.html>`_ +is a good starting point. + +You also need to install rsyslogd on both machines. Do this before +starting with the configuration. You should also familiarize 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 `sysklogd <http://www.infodrom.org/projects/sysklogd/>`_. So if +you know the standard syslog.conf syntax, you do not need to learn any +more to follow this paper. + +Server Setup +~~~~~~~~~~~~ + +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. + +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: + + ``openssl req -new -x509 -days 3650 -nodes -out stunnel.pem -keyout stunnel.pem`` + +That command will ask you a number of questions. Provide some answer for +them. If you are unsure, read +`http://www.stunnel.org/faq/certs.html <http://www.stunnel.org/faq/certs.html>`_. +After the command has finished, you should have a usable stunnel.pem in +your working directory. + +Next is to create a configuration file for stunnel. It will direct +stunnel what to do. You can use the following basic file: + +:: + +; Certificate/key is needed in server modecert = /etc/stunnel/stunnel.pem; Some debugging stuff useful for troubleshootingdebug = 7foreground=yes + + [ssyslog] + accept = 60514 + connect = 61514 + +Save this file to e.g. /etc/stunnel/syslog-server.conf. Please note that +the settings in *italics* 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. + +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. + +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 achieve: just add "-t +61514" to the rsyslogd startup options in your system startup script. +After done so, start (or restart) rsyslogd. + +The server should now be fully operational. + +Client Setup +~~~~~~~~~~~~ + +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. + + :: + + ; Some debugging stuff useful for troubleshootingdebug = 7foreground=yes + + client=yes + + [ssyslog] + accept = 127.0.0.1:61514 + connect = 192.0.2.1:60514 + +Again, the text in *italics* 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. + +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. + +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 supports extensions to use tcp. Add the +following line to your /etc/rsyslog.conf: + + :: + + *.* @@127.0.0.1:61514 + + + +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). + +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. + +Done +~~~~ + +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. + +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-sensitive, you should have a look at the various stunnel +settings that help you further secure the system. + +Preventing Systems from talking directly to the rsyslog Server +-------------------------------------------------------------- + +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. + +Conclusion +---------- + +With minimal 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. |