Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.