diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2007-04-10 06:39:11 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2007-04-10 06:39:11 +0000 |
| commit | 706fb36966f2c3c90946b3c4bb10f16eb2ab0eb5 (patch) | |
| tree | 83a9ddfa5b3d17c6be364ec85e0ce2dbe4f42046 | |
| parent | db9a92c4632692f930e3fb07aae7cffc99b1401e (diff) | |
| download | rsyslog-706fb36966f2c3c90946b3c4bb10f16eb2ab0eb5.tar.gz rsyslog-706fb36966f2c3c90946b3c4bb10f16eb2ab0eb5.tar.xz rsyslog-706fb36966f2c3c90946b3c4bb10f16eb2ab0eb5.zip | |
added doc: generic syslogd architecture
| -rw-r--r-- | doc/generic_design.html | 149 | ||||
| -rw-r--r-- | doc/manual.html | 2 |
2 files changed, 150 insertions, 1 deletions
diff --git a/doc/generic_design.html b/doc/generic_design.html new file mode 100644 index 00000000..03a55fae --- /dev/null +++ b/doc/generic_design.html @@ -0,0 +1,149 @@ +<html>
+<head>
+<title>syslogd generic design</title>
+</head>
+<body>
+<h2>Generic design of a syslogd</h2>
+<p>Written 2007-04-10 by
+<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a></p>
+<p>The text below describes a generic approach on how a syslogd can be
+implemented. I created this description for some other project, where it was not
+used. Instead of throwing it away, I thought it would be a good addition to the
+rsyslog documentation. While rsyslog differs in details from the description
+below, it is sufficiently close to it. Further development of rsyslog will
+probably match it even closer to the description.</p>
+<p>If you intend to read the rsyslog source code, I recommend reading this
+document here first. You will not find the same names and not all of the
+concepts inside rsyslog. However, I think your understanding will benefit from
+knowing the generic architecture.</p>
+<font size="3"><pre>
+
+ +-----------------+
+ | "remote" PLOrig |
+ +-----------------+
+ |
+ I +--------+-----+-----+ +-----+-------+------+-----+
+ P | PLOrig | GWI | ... | | GWO | Store | Disc | ... |
+ C +--------+-----+-----+ +-----+-------+------+-----+
+ | | ^
+ v v |
+ +--------------+ +------------+ +--------------+
+ | PLGenerator | | RelayEng | | CollectorEng |
+ +--------------+ +------------+ +--------------+
+ | ^ ^
+ | | |
+ v v |
+ +-------------+ +------------+ +--------------+
+ | PLG Ext | | RelEng Ext | | CollcEng Ext |
+ +-------------+ +------------+ +--------------+
+ | ^ ^
+ | | |
+ v v |
+ +--------------------------------------------------------------+
+ | Message Router |
+ +--------------------------------------------------------------+
+ | ^
+ v |
+ +--------------------------------------------------------------+
+ | Message CoDec (e.g. RFC 3164, RFCYYYY) |
+ +--------------------------------------------------------------+
+ | ^
+ v |
+ +---------------------+-----------------------+----------------+
+ | transport UDP | transport TLS | ... |
+ +---------------------+-----------------------+----------------+
+
+ Generic Syslog Application Architecture
+</pre></font>
+<ul>
+ <li>A "syslog application" is an application whos purpose is the
+processing of syslog messages. It may be part of a larger
+application with a broader purpose. An example: a database
+application might come with its own syslog send subsystem and not
+go through a central syslog application. In the sense of this
+document, that application is called a "syslog application" even
+though a casual observer might correctly call it a database
+application and may not even know that it supports sending of
+syslog messages.</li>
+ <li>Payload is the information that is to be conveyed. Payload by
+itself may have any format and is totally independent from to
+format specified in this document. The "Message CoDec" of the
+syslog application will bring it into the required format.</li>
+ <li>Payload Orginators ("PLOrig") are the orginal creators of payload.
+Typically, these are application programs.</li>
+ <li>A "Remote PLOrig" is a payload originator residing in a different
+application than the syslog application itself. That application
+may reside on a different machine and may talk to the syslog
+application via RPC.</li>
+ <li>A "PLOrig" is a payload originator residing within the syslog
+application itself. Typically, this PLOrig emits syslog
+application startup, shutdown, error and status log messages.</li>
+ <li>A "GWI" is a inbound gateway. For example, a SNMP-to-syslog
+gateway may receive SNMP messages and translate them into syslog.</li>
+ <li>The ellipsis after "GWI" indicates that there are potentially a
+variety of different other ways to originally generate payload.</li>
+ <li>A "PLGenerator" is a payload generator. It takes the information
+from the payload-generating source and integrates it into the
+syslog subsystem of the application. This is a highly theoretical
+concept. In practice, there may not actually be any such
+component. Instead, the payload generators (or other parts like
+the GWI) may talk directly to the syslog subsystem. Conceptually,
+the "PLGenerator" is the first component where the information is
+actually syslog content.</li>
+ <li>A "PLG Ext" is a payload generator extension. It is used to
+modify the syslog information. An example of a "PLG Ext" might be
+the addition of cryptographic signatures to the syslog
+information.</li>
+ <li>A "Message Router" is a component that accepts in- and outbound
+syslog information and routes it to the proper next destination
+inside the syslog application. The routing information itself is
+expected to be learnt by operator configuration.</li>
+ <li>A "Message CoDec" is the message encoder/decoder. The encoder
+takes syslog information and encodes them into the required format<br>for a syslog message. The decoder takes a syslog message and
+decodes it into syslog information. Codecs for multiple syslog
+formats may be present inside a single syslog application.</li>
+ <li>A transport (UDP, TLS, yet-to-be-defined ones) sends and receives
+syslog messages. Multiple transports may be used by a single<br>syslog application at the same time. A single transport instance
+may be used for both sending and receiving. Alternatively, a
+single instance might be used for sending and receiving
+exclusively. Multiple instances may be used for different
+listener ports and receivers.</li>
+ <li>A "RelayEng" is the relaying engine. It provides functionality
+necessary for receiving syslog information and sending it to
+another syslog application.</li>
+ <li>A "RelEng Ext" is an extension that processes syslog information
+as it enters or exits a RelayEng. An example of such a component
+might be a relay cryptographically signing received syslog
+messages. Such a function might be useful to guarantee authenticy
+starting from a given point inside a relay chain.</li>
+ <li>A "CollectorEng" is a collector engine. At this component, syslog
+information leaves the syslog system and is translated into some
+other form. After the CollectorEng, the information is no longer
+defined to be of native syslog type.</li>
+ <li>A "CollcEng Ext" is a collector engine extension. It modifies
+syslog information before it is passed on to the CollectorEng. An
+example for this might be the verification of cryptographically
+signed syslog message information. Please note that another
+implementation appraoch would be to do the verification outside of
+the syslog application or in a stage after "CollectorEng".</li>
+ <li>A "GWO" is an outbound gateway. An example of this might be the
+forwarding of syslog information via SNMP or SMTP. Please note
+that when a GWO directly connects to a GWI on a different syslog
+application, no native exchange of syslog information takes place.
+Instead, the native protocol of these gateways (e.g. SNMP) is
+used. The syslog information is embedded inside that protocol.
+Depending on protocol and gatway implementation, some of the
+native syslog information might be lost.</li>
+ <li>A "Store" is any way to persistently store the extracted syslog
+information, e.g. to the file system or to a data base.</li>
+ <li>"Disc" means the discarding of messages. Operators often find it
+useful to discard noise messages and so most syslog applications<br>contain a way to do that.</li>
+ <li>The ellipsis after "Disc" indicates that there are potentially avariety of different other ways to consume syslog information.</li>
+ <li>There may be multiple instances of each of the described
+components in a single syslog application.</li>
+ <li>A syslog application is made up of all or some of the above
+mentioned components.</li>
+</ul>
+</p>
+</body>
+</html>
diff --git a/doc/manual.html b/doc/manual.html index c5ae724f..8e15cc91 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -22,7 +22,7 @@ helps. Learn <a href="how2help.html">how to help the rsyslog project</a>.</p> <li><a href="rsyslogd.man.txt">rsyslogd man page</a>
<li><a href="rsyslog_conf.html">configuration file syntax (rsyslog.conf)</a>
<li>a commented <a href="sample.conf.html">sample rsyslog.conf</a>
-<li><a href="bugs.html">rsyslog bug list</a><li><a href="rsyslog_packages.html">
rsyslog packages</a></ul>
+<li><a href="bugs.html">rsyslog bug list</a><li><a href="rsyslog_packages.html">
rsyslog packages</a><li><a href="generic_design.html">backgrounder on generic
syslog application design</a></ul>
<p><b>We have some in-depth papers on</b></p>
<ul>
<li><a href="install.html">installing rsyslog</a></li>
|