diff options
| author | Michael Biebl <biebl@debian.org> | 2008-03-29 12:14:38 +0100 |
|---|---|---|
| committer | Michael Biebl <biebl@debian.org> | 2008-03-29 12:14:38 +0100 |
| commit | 8a0b3535fa5eb747cf28cee9c3b281a2fe00c6b4 (patch) | |
| tree | 6afb3b638c3e9676c1854b6294acc67c26fdc90c /doc | |
| parent | 4d85b3abea17def3a88653d3678c4deb848355af (diff) | |
| download | rsyslog-8a0b3535fa5eb747cf28cee9c3b281a2fe00c6b4.tar.gz | |
Imported Upstream version 1.19.10upstream/1.19.10
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/Makefile.in | 3 | ||||
| -rw-r--r-- | doc/bugs.html | 4 | ||||
| -rw-r--r-- | doc/contributors.html | 2 | ||||
| -rw-r--r-- | doc/features.html | 2 | ||||
| -rw-r--r-- | doc/generic_design.html | 12 | ||||
| -rw-r--r-- | doc/history.html | 16 | ||||
| -rw-r--r-- | doc/how2help.html | 10 | ||||
| -rw-r--r-- | doc/install.html | 10 | ||||
| -rw-r--r-- | doc/ipv6.html | 6 | ||||
| -rw-r--r-- | doc/man_rsyslogd.html | 438 | ||||
| -rw-r--r-- | doc/manual.html | 2 | ||||
| -rw-r--r-- | doc/modules.html | 95 | ||||
| -rw-r--r-- | doc/rsconf1_allowedsender.html | 4 | ||||
| -rw-r--r-- | doc/rsconf1_controlcharacterescapeprefix.html | 4 | ||||
| -rw-r--r-- | doc/rsconf1_droptrailinglfonreception.html | 4 | ||||
| -rw-r--r-- | doc/rsconf1_escapecontrolcharactersonreceive.html | 4 | ||||
| -rw-r--r-- | doc/rsconf1_filecreatemode.html | 4 | ||||
| -rw-r--r-- | doc/rsconf1_mainmsgqueuesize.html | 6 | ||||
| -rw-r--r-- | doc/rsconf1_moddir.html | 27 | ||||
| -rw-r--r-- | doc/rsconf1_modload.html | 4 | ||||
| -rw-r--r-- | doc/rsyslog_conf.html | 45 | ||||
| -rw-r--r-- | doc/rsyslog_recording_pri.html | 4 | ||||
| -rw-r--r-- | doc/status.html | 10 | ||||
| -rw-r--r-- | doc/syslog-protocol.html | 12 | ||||
| -rw-r--r-- | doc/version_naming.html | 10 |
26 files changed, 662 insertions, 79 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index ed6dc2c..74e1be6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -7,6 +7,8 @@ html_files = \ install.html \ ipv6.html \ manual.html \ + man_rsyslogd.html \ + modules.html \ property_replacer.html \ rsyslog_conf.html \ rsyslog_mysql.html \ @@ -39,6 +41,7 @@ html_files = \ rsconf1_includeconfig.html \ rsconf1_mainmsgqueuesize.html \ rsconf1_modload.html \ + rsconf1_moddir.html \ rsconf1_repeatedmsgreduction.html \ rsconf1_resetconfigvariables.html \ rsconf1_umask.html diff --git a/doc/Makefile.in b/doc/Makefile.in index d18abc4..49b251c 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -163,6 +163,8 @@ html_files = \ install.html \ ipv6.html \ manual.html \ + man_rsyslogd.html \ + modules.html \ property_replacer.html \ rsyslog_conf.html \ rsyslog_mysql.html \ @@ -195,6 +197,7 @@ html_files = \ rsconf1_includeconfig.html \ rsconf1_mainmsgqueuesize.html \ rsconf1_modload.html \ + rsconf1_moddir.html \ rsconf1_repeatedmsgreduction.html \ rsconf1_resetconfigvariables.html \ rsconf1_umask.html diff --git a/doc/bugs.html b/doc/bugs.html index 41404e5..8f77560 100644 --- a/doc/bugs.html +++ b/doc/bugs.html @@ -29,12 +29,12 @@ single-threaded mode rsyslogd offers great performance (just think that stock sysklogd has always been using a single thread, only).</p> <h2>forwarding remotely received messages</h2> <p>Sysklogd does not forward remotely received messages to other network -destionation except when the -h option is given. This code is currently defunct. +destination except when the -h option is given. This code is currently defunct. No matter if -h is specified or not, messages are ALWAYS forwarded. It is currently under review if the sysklogd's functionality is actually needed. Please see my <a href="http://rgerhards.blogspot.com/2007/07/on-syslogd-h-option.html">blog -post on this topic</a> for futher detail.</p> +post on this topic</a> for further detail.</p> <h2>EQUALLY-NAMED TEMPLATES</h2> <p>If multiple templates with the SAME name are created, all but the first definition is IGNORED. So you can NOT (yet) replace a diff --git a/doc/contributors.html b/doc/contributors.html index ebbf1a5..713c329 100644 --- a/doc/contributors.html +++ b/doc/contributors.html @@ -10,7 +10,7 @@ Unfortunately, I have begun this page in July of 2007, long after the project started. I try to extract all past contributor information from CVS, readme's, code etc - but I may fail. If you contributed and do not find yourself listed below, please accept my sincere apologies and drop me a line.</p> -<p>Please also note that I will do the checks for past contibutors once the +<p>Please also note that I will do the checks for past contributors once the current very busy development phase is over, so it may take a few weeks to fully populate this file.</p> <p>Contributors are listed in alphabetical order. If I know an Alias only, that diff --git a/doc/features.html b/doc/features.html index f451c85..6f2e7e8 100644 --- a/doc/features.html +++ b/doc/features.html @@ -59,7 +59,7 @@ at some time moved back to the sourceforge tracker.</p> <ul> <li>create a plug-in-interface - we are very close to this. A neat interface is already used internally for output modules and the MySQL module already - works as a plug-in. However, no interface defintion is yet formally + works as a plug-in. However, no interface definition is yet formally published.<li>implement native email-functionality in selector (probably best done as a plug-in)<li>port it to more *nix variants (eg AIX and HP UX) - this needs volunteers with access to those machines and diff --git a/doc/generic_design.html b/doc/generic_design.html index 03a55fa..74dbd80 100644 --- a/doc/generic_design.html +++ b/doc/generic_design.html @@ -56,7 +56,7 @@ knowing the generic architecture.</p> Generic Syslog Application Architecture
</pre></font>
<ul>
- <li>A "syslog application" is an application whos purpose is the
+ <li>A "syslog application" is an application whose 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
@@ -69,7 +69,7 @@ syslog messages.</li> 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.
+ <li>Payload Originators ("PLOrig") are the original 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
@@ -114,7 +114,7 @@ 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
+messages. Such a function might be useful to guarantee authenticity
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
@@ -124,7 +124,7 @@ defined to be of native syslog type.</li> 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
+implementation approach 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
@@ -132,13 +132,13 @@ 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
+Depending on protocol and gateway 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>The ellipsis after "Disc" indicates that there are potentially a variety 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
diff --git a/doc/history.html b/doc/history.html index 48a6489..cd43229 100644 --- a/doc/history.html +++ b/doc/history.html @@ -11,11 +11,11 @@ MySQL databases and fully configurable output formats (including great timestamp Rsyslog was initiated by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a>. If you are interested to learn why Rainer initiated the project, you may want to read his blog posting on "<a href="http://rgerhards.blogspot.com/2007/08/why-does-world-need-another-syslogd.html">why -the world neeeds another syslogd</a>".<p>Rsyslog has +the world needs another syslogd</a>".<p>Rsyslog has been forked in <b>2004</b> from the <a href="http://www.infodrom.org/projects/sysklogd/">sysklogd standard package</a>. The goal of the rsyslog project is to provide a feature-richer and reliable -syslog deamon while retaining drop-in replacement capabilities to stock syslogd. By "reliable", we mean support for reliable transmission +syslog daemon while retaining drop-in replacement capabilities to stock syslogd. By "reliable", we mean support for reliable transmission modes like TCP or <a href="http://www.monitorware.com/Common/en/glossary/rfc3195.php">RFC 3195</a> (syslog-reliable). We do NOT imply that the sysklogd package is unreliable.</p> <p>The name "rsyslog" stems back to the @@ -26,7 +26,7 @@ Instead, it contained enhanced configurability and other enhancements changes. Also, questions asked on the loganalysis list and at other places indicated that RFC3195 is NOT a prime priority for users, but rather better control over the output format. So there we were, with -a rsyslod that covers a lot of enhancements, but not a single one +a rsyslogd that covers a lot of enhancements, but not a single one of these that made its name ;) Since version 0.9.2, receiving syslog messages via plain tcp is finally supported, a bit later sending via TCP, too. Starting with 1.11.0, RFC 3195 is finally support at the receiving side (a.k.a. "listener"). @@ -72,14 +72,14 @@ very busy time with many great additions.<p>In <b>July 2007</b>, Andrew Pantyukhin added BSD ports files for rsyslog and liblogging. We were strongly encouraged by this too. It looks like rsyslog is getting more and more momentum. Let's see what comes next...<p>Also in <b>July 2007</b> (and beginning of -August), Rainer remodled the output part of rsyslog. It got a clean object model +August), Rainer remodeled the output part of rsyslog. It got a clean object model and is now prepared for a plug-in architecture. During that time, some base ideas for the overall new object model appeared.<p>In <b>August 2007</b> -community involvment grew more and more. Also, more packages appeared. We were -quite happy about that. To facilitate user contributíons, we set up a +community involvement grew more and more. Also, more packages appeared. We were +quite happy about that. To facilitate user contributions, we set up a <a href="http://wiki.rsyslog.com/">wiki</a> on August 10th, 2007. Also in August 2007, rsyslog 1.18.2 appeared, which is deemed to be quite close to the final -2.0.0 release. With its appearance, the pace of changes was deliberatly reduced, +2.0.0 release. With its appearance, the pace of changes was deliberately reduced, in order to allow it to mature (see Rainers's <a href="http://rgerhards.blogspot.com/2007/07/pace-of-changes-in-rsyslog.html"> blog post</a> on this topic, written a bit early, but covering the essence).<p>Be sure to visit Rainer's <a href="http://rgerhards.blogspot.com/">syslog block</a> @@ -91,4 +91,4 @@ Don't be shy to post to either the blog or the <li><a href="http://www.rsyslog.com/Topic4.phtml">the rsyslog change log</a></li> </ul> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/how2help.html b/doc/how2help.html index 5c612e1..0caa5a3 100644 --- a/doc/how2help.html +++ b/doc/how2help.html @@ -7,8 +7,8 @@ <p><b>You like rsyslog and would like to lend us a helping hand?</b> This page
tells you how easy it is to help a little bit. You can contribute to the project
even with a single mouse click! If you could pick a single item from the
-whishlist, that would be awfully helpful!</p>
-<p>This is our whishlist:</p>
+wish list, that would be awfully helpful!</p>
+<p>This is our wish list:</p>
<ul>
<li>let others know how great rsyslog is<ul>
<li>rate us at <a href="http://freshmeat.net/rate/52985/">freshmeat.net</a>
@@ -21,7 +21,7 @@ whishlist, that would be awfully helpful!</p> <li>let us know about rsyslog - we are eager for feedback<ul>
<li>tell us what you like and what you not like - so that we can include
that into development</li>
- <li>tell us what you use rsyslog for - esepcially if you have high
+ <li>tell us what you use rsyslog for - especially if you have high
traffic volume or an otherwise "uncommon" deployment. We are looking for
case studies and experience how rsyslog performs in unusual scenarios.</li>
<li>allow us to post your thoughts and experiences as a "user story" on
@@ -31,7 +31,7 @@ whishlist, that would be awfully helpful!</p> <li>if you know how to create packages (rpm, deb, ...)<ul>
<li>we would very much appreciate your help with package creation. We know
that it is important to have good binary packages for a product to
- spread widely. Yet, we do not have the knowledge to do it all ourselfs.
+ spread widely. Yet, we do not have the knowledge to do it all ourselves.
<a href="mailto:rgerhards@adiscon.com">Drop Rainer a note </a>if you
could help us out.</li>
</ul>
@@ -56,4 +56,4 @@ whishlist, that would be awfully helpful!</p> might do!</p>
</body>
-</html>
\ No newline at end of file +</html> diff --git a/doc/install.html b/doc/install.html index fb9e893..bee136c 100644 --- a/doc/install.html +++ b/doc/install.html @@ -48,7 +48,7 @@ seconds. If an error message comes up, most probably a part of your build environment is not installed. Check with step 1 in those cases. </p> <h3>Step 4 - Install</h3> <p>Again, that is quite easy. All it takes is a "make install". That will copy -the rsyslogd and the man pages to the relavant directories.</p> +the rsyslogd and the man pages to the relevant directories.</p> <h3>Step 5 - Configure rsyslogd</h3> <p>In this step, you tell rsyslogd what to do with received messages. If you are upgrading from stock syslogd, /etc/syslog.conf is probably a good starting @@ -65,7 +65,7 @@ you need to disable the stock syslogd. To do this, you typically must change your rc.d startup scripts.</p> <p>For example, under <a href="http://www.debian.org/">Debian</a> this must be done as follows: The default runlevel is 2. We modify the init scripts for -runlevel 2 - in parctice, you need to do this for all run levels you will ever +runlevel 2 - in practice, you need to do this for all run levels you will ever use (which probably means all). Under /etc/rc2.d there is a S10sysklogd script (actually a symlink). Change the name to _S10sysklogd (this keeps the symlink in place, but will prevent further execution - effectively disabling it).</p> @@ -106,8 +106,8 @@ that), you need to make sure that klogd is restarted after rsyslogd is restarted So it might be a good idea to put a klogd reload-or-restart command right after the rsyslogd command in your daily script. This can save you lots of troubles.</p> <h3>Done</h3> -<p>This concludes the steps neccesary to install rsyslogd. Of course, it is -always a good idea to test everything thouroughly. At a minimalist level, you +<p>This concludes the steps necessary to install rsyslogd. Of course, it is +always a good idea to test everything thoroughly. At a minimalist level, you should do a reboot and after that check if everything has come up correctly. Pay attention not only to running processes, but also check if the log files (or the database) are correctly being populated.</p> @@ -153,4 +153,4 @@ comments or bug sighting reports are very welcome. Please http://www.gnu.org/copyleft/fdl.html</a>.</p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/ipv6.html b/doc/ipv6.html index f5a049c..67c8e1f 100644 --- a/doc/ipv6.html +++ b/doc/ipv6.html @@ -12,7 +12,7 @@ your way somewhat easier.</p> <p>First of all, you can restrict rsyslog to using IPv4 or IPv6 addresses only by specifying the -4 or -6 command line option (now guess which one does what...). If you do not provide any command line option, rsyslog uses IPv4 and -IPv6 adresses concurrently. In practice, that means the listener binds to both +IPv6 addresses concurrently. In practice, that means the listener binds to both addresses (provided they are configured). When sending syslog messages, rsyslog uses IPv4 addresses when the receiver can be reached via IPv4 and IPv6 addresses if it can be reached via IPv6. If it can be reached on either IPv4 and v6, @@ -20,10 +20,10 @@ rsyslog leaves the choice to the socket layer. The important point to know is that it uses whatever connectivity is available to reach the destination.</p> <p><b>There is one subtle difference between UDP and TCP.</b> With the new IPv4/v6 ignorant code, rsyslog has potentially different ways to reach -destinations. The socket layer returns all of these pathes in a sorted array. +destinations. The socket layer returns all of these paths in a sorted array. For TCP, rsyslog loops through this array until a successful TCP connect can be made. If that happens, the other addresses are ignored and messages are sent via -the succesfully-connected socket.</p> +the successfully-connected socket.</p> <p>For UDP, there is no such definite success indicator. Sure, the socket layer may detect some errors, but it may not notice other errors (due to the unreliable nature of UDP). By default, the UDP sender also tries one entry after diff --git a/doc/man_rsyslogd.html b/doc/man_rsyslogd.html new file mode 100644 index 0000000..d18fd88 --- /dev/null +++ b/doc/man_rsyslogd.html @@ -0,0 +1,438 @@ +<BODY><PRE> +RSYSLOGD(8) Linux System Administration RSYSLOGD(8) + + + +<B>NAME</B> + rsyslogd - reliable and extended syslogd + +<B>SYNOPSIS</B> + <B>rsyslogd </B>[ <B>-4 </B>] [ <B>-6 </B>] [ <B>-A </B>] [ <B>-a </B><I>socket </I>] [ <B>-d </B>] [ <B>-e </B>] + [ <B>-f </B><I>config file </I>] [ <B>-h </B>] [ <B>-i </B><I>pid file </I>] [ <B>-l </B><I>hostlist </I>] + [ <B>-m </B><I>interval </I>] [ <B>-n </B>] [ <B>-o </B>] [ <B>-p </B><I>socket </I>] + [ <B>-r </B><I>[port] </I>] [ <B>-s </B><I>domainlist </I>] [ <B>-t </B><I>port,max-nbr-of-sessions </I>] + [ <B>-v </B>] [ <B>-w </B>] [ <B>-x </B>] + + +<B>DESCRIPTION</B> + <B>Rsyslogd </B>is a system utility providing support for message logging. + Support of both internet and unix domain sockets enables this utility + to support both local and remote logging (via UDP and TCP). + + <B>Rsyslogd</B>(8) is derived from the sysklogd package which in turn is + derived from the stock BSD sources. + + <B>Rsyslogd </B>provides a kind of logging that many modern programs use. + Every logged message contains at least a time and a hostname field, + normally a program name field, too, but that depends on how trusty the + logging program is. The rsyslog package supports free definition of + output formats via templates. It also supports precise timestamps and + writing directly to MySQL databases. If the database option is used, + tools like phpLogCon can be used to view the log data. + + While the <B>rsyslogd </B>sources have been heavily modified a couple of notes + are in order. First of all there has been a systematic attempt to + insure that rsyslogd follows its default, standard BSD behavior. Of + course, some configuration file changes are necessary in order to sup- + port the template system. However, rsyslogd should be able to use a + standard syslog.conf and act like the original syslogd. However, an + original syslogd will not work correctly with a rsyslog-enhanced con- + figuration file. At best, it will generate funny looking file names. + The second important concept to note is that this version of rsyslogd + interacts transparently with the version of syslog found in the stan- + dard libraries. If a binary linked to the standard shared libraries + fails to function correctly we would like an example of the anomalous + behavior. + + The main configuration file <I>/etc/rsyslog.conf </I>or an alternative file, + given with the <B>-f </B>option, is read at startup. Any lines that begin + with the hash mark (‘‘#’’) and empty lines are ignored. If an error + occurs during parsing the error element is ignored. It is tried to + parse the rest of the line. + + For details and configuration examples, see the <B>rsyslog.conf (5) </B>man + page. + + + +<B>OPTIONS</B> + <B>-A </B>When sending UDP messages, there are potentially multiple paths + to the target destination. By default, <B>rsyslogd </B>only sends to + the first target it can successfully send to. If -A is given, + messages are sent to all targets. This may improve reliability, + but may also cause message duplication. This option should + enabled only if it is fully understood. + + <B>-4 </B>Causes <B>rsyslogd </B>to listen to IPv4 addresses only. If neither -4 + nor -6 is given, <B>rsyslogd </B>listens to all configured addresses of + the system. + + <B>-6 </B>Causes <B>rsyslogd </B>to listen to IPv6 addresses only. If neither -4 + nor -6 is given, <B>rsyslogd </B>listens to all configured addresses of + the system. + + <B>-a </B><I>socket</I> + Using this argument you can specify additional sockets from that + <B>rsyslogd </B>has to listen to. This is needed if you’re going to + let some daemon run within a chroot() environment. You can use + up to 19 additional sockets. If your environment needs even + more, you have to increase the symbol <B>MAXFUNIX </B>within the sys- + logd.c source file. An example for a chroot() daemon is + described by the people from OpenBSD at + http://www.psionic.com/papers/dns.html. + + <B>-d </B>Turns on debug mode. Using this the daemon will not proceed a + <B>fork</B>(2) to set itself in the background, but opposite to that + stay in the foreground and write much debug information on the + current tty. See the DEBUGGING section for more information. + + <B>-e </B>Set the default of $RepeatedMsgReduction config option to "off". + Hine: "e" like "every message". For further information, see + there. + + <B>-f </B><I>config file</I> + Specify an alternative configuration file instead of <I>/etc/rsys-</I> + <I>log.conf</I>, which is the default. + + <B>-h </B>By default rsyslogd will not forward messages it receives from + remote hosts. Specifying this switch on the command line will + cause the log daemon to forward any remote messages it receives + to forwarding hosts which have been defined. + + <B>-i </B><I>pid file</I> + Specify an alternative pid file instead of the default one. + This option must be used if multiple instances of rsyslogd + should run on a single machine. + + <B>-l </B><I>hostlist</I> + Specify a hostname that should be logged only with its simple + hostname and not the fqdn. Multiple hosts may be specified + using the colon (‘‘:’’) separator. + + <B>-m </B><I>interval</I> + The <B>rsyslogd </B>logs a mark timestamp regularly. The default + <I>interval </I>between two <I>-- MARK -- </I>lines is 20 minutes. This can + be changed with this option. Setting the <I>interval </I>to zero turns + it off entirely. + + <B>-n </B>Avoid auto-backgrounding. This is needed especially if the + <B>rsyslogd </B>is started and controlled by <B>init</B>(8). + + <B>-o </B>Omit reading the standard local log socket. This option is most + useful for running multiple instances of rsyslogd on a single + machine. When specified, no local log socket is opened at all. + + <B>-p </B><I>socket</I> + You can specify an alternative unix domain socket instead of + <I>/dev/log</I>. + + <B>-r </B><I>["port"]</I> + Activates the syslog/udp listener service. The listener will + listen to the specified port. If no port is specified, 0 is + used as port number, which in turn will lead to a lookup of the + system default syslog port. If there is no system default, 514 + is used. Please note that the port must immediately follow the + -r option. Thus "-r514" is valid while "-r 514" is invalid (note + the space). + + <B>-s </B><I>domainlist</I> + Specify a domainname that should be stripped off before logging. + Multiple domains may be specified using the colon (‘‘:’’) sepa- + rator. Please be advised that no sub-domains may be specified + but only entire domains. For example if <B>-s north.de </B>is speci- + fied and the host logging resolves to satu.infodrom.north.de no + domain would be cut, you will have to specify two domains like: + <B>-s north.de:infodrom.north.de</B>. + + <B>-t </B><I>port,max-nbr-of-sessions</I> + Activates the syslog/tcp listener service. The listener will + listen to the specified port. If max-nbr-of-sessions is speci- + fied, that becomes the maximum number of concurrent tcp ses- + sions. If not specified, the default is 200. Please note that + syslog/tcp is not standardized, but the implementation in rsys- + logd follows common practice and is compatible with e.g. Cisco + PIX, syslog-ng and MonitorWare (Windows). Please note that the + port must immediately follow the -t option. Thus "-t514" is + valid while "-t 514" is invalid (note the space). + + <B>-v </B>Print version and exit. + + <B>-w </B>Supress warnings issued when messages are received from non- + authorized machines (those, that are in no AllowedSender list). + + <B>-x </B>Disable DNS for remote messages. + + +<B>SIGNALS</B> + <B>Rsyslogd </B>reacts to a set of signals. You may easily send a signal to + <B>rsyslogd </B>using the following: + + kill -SIGNAL ‘cat /var/run/rsyslogd.pid‘ + + + <B>SIGHUP </B>This lets <B>rsyslogd </B>perform a re-initialization. All open files + are closed, the configuration file (default is <I>/etc/rsys-</I> + <I>log.conf</I>) will be reread and the <B>rsyslog</B>(3) facility is started + again. + + <B>SIGTERM</B> + <B>Rsyslogd </B>will die. + + <B>SIGINT</B>, <B>SIGQUIT</B> + If debugging is enabled these are ignored, otherwise <B>rsyslogd</B> + will die. + + <B>SIGUSR1</B> + Switch debugging on/off. This option can only be used if <B>rsys-</B> + <B>logd </B>is started with the <B>-d </B>debug option. + + <B>SIGCHLD</B> + Wait for childs if some were born, because of wall’ing messages. + + +<B>SUPPORT FOR REMOTE LOGGING</B> + <B>Rsyslogd </B>provides network support to the syslogd facility. Network + support means that messages can be forwarded from one node running + rsyslogd to another node running rsyslogd (or a compatible syslog + implementation) where they will be actually logged to a disk file. + + To enable this you have to specify either the <B>-r </B>or <B>-t </B>option on the + command line. The default behavior is that <B>rsyslogd </B>won’t listen to + the network. You can also combine these two options if you want rsys- + logd to listen to both TCP and UDP messages. + + The strategy is to have rsyslogd listen on a unix domain socket for + locally generated log messages. This behavior will allow rsyslogd to + inter-operate with the syslog found in the standard C library. At the + same time rsyslogd listens on the standard syslog port for messages + forwarded from other hosts. To have this work correctly the <B>ser-</B> + <B>vices</B>(5) files (typically found in <I>/etc</I>) must have the following entry: + + syslog 514/udp + + If this entry is missing <B>rsyslogd </B>will use the well known port of 514 + (so in most cases, it’s not really needed). + + To cause messages to be forwarded to another host replace the normal + file line in the <I>rsyslog.conf </I>file with the name of the host to which + the messages is to be sent prepended with an @ (for UDP delivery) or + the sequence @@ (for TCP delivery). The host name can also be followed + by a colon and a port number, in which case the message is sent to the + specified port on the remote host. + + For example, to forward <B>ALL </B>messages to a remote host use the + following <I>rsyslog.conf </I>entry: + + # Sample rsyslogd configuration file to + # messages to a remote host forward all. + *.* @hostname + More samples can be found in sample.conf. + + If the remote hostname cannot be resolved at startup, because + the name-server might not be accessible (it may be started after + rsyslogd) you don’t have to worry. <B>Rsyslogd </B>will retry to + resolve the name ten times and then complain. Another possibil- + ity to avoid this is to place the hostname in <I>/etc/hosts</I>. + + With normal <B>syslogd</B>s you would get syslog-loops if you send out + messages that were received from a remote host to the same host + (or more complicated to a third host that sends it back to the + first one, and so on). + + To avoid this no messages that were received from a remote host + are sent out to another (or the same) remote host. You can dis- + able this feature by the <B>-h </B>option. + + If the remote host is located in the same domain as the host, + <B>rsyslogd </B>is running on, only the simple hostname will be logged + instead of the whole fqdn. + + In a local network you may provide a central log server to have + all the important information kept on one machine. If the net- + work consists of different domains you don’t have to complain + about logging fully qualified names instead of simple hostnames. + You may want to use the strip-domain feature <B>-s </B>of this server. + You can tell <B>rsyslogd </B>to strip off several domains other than + the one the server is located in and only log simple hostnames. + + Using the <B>-l </B>option there’s also a possibility to define single + hosts as local machines. This, too, results in logging only + their simple hostnames and not the fqdns. + + +<B>OUTPUT TO DATABASES</B> + <B>Rsyslogd </B>has support for writing data to MySQL database tables. The + exact specifics are described in the <B>rsyslog.conf (5) </B>man page. Be sure + to read it if you plan to use database logging. + + While it is often handy to have the data in a database, you must be + aware of the implications. Most importantly, database logging takes far + longer than logging to a text file. A system that can handle a large + log volume when writing to text files can most likely not handle a sim- + ilar large volume when writing to a database table. + + +<B>OUTPUT TO NAMED PIPES (FIFOs)</B> + <B>Rsyslogd </B>has support for logging output to named pipes (fifos). A fifo + or named pipe can be used as a destination for log messages by prepend- + ing a pipy symbol (‘‘|’’) to the name of the file. This is handy for + debugging. Note that the fifo must be created with the mkfifo command + before <B>rsyslogd </B>is started. + + The following configuration file routes debug messages from the + kernel to a fifo: + + # Sample configuration to route kernel debugging + # messages ONLY to /usr/adm/debug which is a + # named pipe. + kern.=debug |/usr/adm/debug + + +<B>INSTALLATION CONCERNS</B> + There is probably one important consideration when installing rsyslogd. + It is dependent on proper formatting of messages by the syslog func- + tion. The functioning of the syslog function in the shared libraries + changed somewhere in the region of libc.so.4.[2-4].n. The specific + change was to null-terminate the message before transmitting it to the + <I>/dev/log </I>socket. Proper functioning of this version of rsyslogd is + dependent on null-termination of the message. + + This problem will typically manifest itself if old statically linked + binaries are being used on the system. Binaries using old versions of + the syslog function will cause empty lines to be logged followed by the + message with the first character in the message removed. Relinking + these binaries to newer versions of the shared libraries will correct + this problem. + + The <B>rsyslogd</B>(8) can be run from <B>init</B>(8) or started as part of the rc.* + sequence. If it is started from init the option <I>-n </I>must be set, other- + wise you’ll get tons of syslog daemons started. This is because + <B>init</B>(8) depends on the process ID. + + +<B>SECURITY THREATS</B> + There is the potential for the rsyslogd daemon to be used as a conduit + for a denial of service attack. A rogue program(mer) could very easily + flood the rsyslogd daemon with syslog messages resulting in the log + files consuming all the remaining space on the filesystem. Activating + logging over the inet domain sockets will of course expose a system to + risks outside of programs or individuals on the local machine. + + There are a number of methods of protecting a machine: + + 1. Implement kernel firewalling to limit which hosts or networks + have access to the 514/UDP socket. + + 2. Logging can be directed to an isolated or non-root filesystem + which, if filled, will not impair the machine. + + 3. The ext2 filesystem can be used which can be configured to limit + a certain percentage of a filesystem to usage by root only. + <B>NOTE </B>that this will require rsyslogd to be run as a non-root + process. <B>ALSO NOTE </B>that this will prevent usage of remote log- + ging since rsyslogd will be unable to bind to the 514/UDP + socket. + + 4. Disabling inet domain sockets will limit risk to the local + machine. + + 5. Use step 4 and if the problem persists and is not secondary to a + rogue program/daemon get a 3.5 ft (approx. 1 meter) length of + sucker rod* and have a chat with the user in question. + + Sucker rod def. — 3/4, 7/8 or 1in. hardened steel rod, male + threaded on each end. Primary use in the oil industry in West- + ern North Dakota and other locations to pump ’suck’ oil from oil + wells. Secondary uses are for the construction of cattle feed + lots and for dealing with the occasional recalcitrant or bel- + ligerent individual. + + <B>Message replay and spoofing</B> + If remote logging is enabled, messages can easily be spoofed and + replayed. As the messages are transmitted in clear-text, an attacker + might use the information obtained from the packets for malicious + things. Also, an attacker might reply recorded messages or spoof a + sender’s IP address, which could lead to a wrong perception of system + activity. Be sure to think about syslog network security before + enabling it. + + +<B>DEBUGGING</B> + When debugging is turned on using <B>-d </B>option then <B>rsyslogd </B>will be very + verbose by writing much of what it does on stdout. Whenever the con- + figuration file is reread and re-parsed you’ll see a tabular, corre- + sponding to the internal data structure. This tabular consists of four + fields: + + <I>number </I>This field contains a serial number starting by zero. This num- + ber represents the position in the internal data structure (i.e. + the array). If one number is left out then there might be an + error in the corresponding line in <I>/etc/rsyslog.conf</I>. + + <I>pattern</I> + This field is tricky and represents the internal structure + exactly. Every column stands for a facility (refer to <B>sys-</B> + <B>log</B>(3)). As you can see, there are still some facilities left + free for former use, only the left most are used. Every field + in a column represents the priorities (refer to <B>syslog</B>(3)). + + <I>action </I>This field describes the particular action that takes place + whenever a message is received that matches the pattern. Refer + to the <B>syslog.conf</B>(5) manpage for all possible actions. + + <I>arguments</I> + This field shows additional arguments to the actions in the last + field. For file-logging this is the filename for the logfile; + for user-logging this is a list of users; for remote logging + this is the hostname of the machine to log to; for console-log- + ging this is the used console; for tty-logging this is the spec- + ified tty; wall has no additional arguments. + + + <B>templates</B> + There will also be a second internal structure which lists all + defined templates and there contents. This also enables you to + see the internally-defined, hardcoded templates. + +<B>FILES</B> + <I>/etc/rsyslog.conf</I> + Configuration file for <B>rsyslogd</B>. See <B>rsyslog.conf</B>(5) for exact + information. + <I>/dev/log</I> + The Unix domain socket to from where local syslog messages are + read. + <I>/var/run/rsyslogd.pid</I> + The file containing the process id of <B>rsyslogd</B>. + +<B>BUGS</B> + Please review the file BUGS for up-to-date information on known bugs + and annoyances. + +<B>Further Information</B> + Please visit <B>http://www.rsyslog.com/doc </B>for additional information, + tutorials and a support forum. + +<B>SEE ALSO</B> + <B>rsyslog.conf</B>(5), <B>logger</B>(1), <B>syslog</B>(2), <B>syslog</B>(3), <B>services</B>(5), + <B>savelog</B>(8) + + +<B>COLLABORATORS</B> + <B>rsyslogd </B>is derived from sysklogd sources, which in turn was taken from + the BSD sources. Special thanks to Greg Wettstein (greg@wind.enjel- + lic.com) and Martin Schulze (joey@linux.de) for the fine sysklogd pack- + age. + + Rainer Gerhards + Adiscon GmbH + Grossrinderfeld, Germany + rgerhards@adiscon.com + + Michael Meckelein + Adiscon GmbH + mmeckelein@adiscon.com + + + +Version 1.16.1 (devel) 17 July 2007 RSYSLOGD(8) +</PRE></BODY> diff --git a/doc/manual.html b/doc/manual.html index 3496c85..4155390 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -19,7 +19,7 @@ a helping hand. </b>It doesn't require a lot of time - even a single mouse click helps. Learn <a href="how2help.html">how to help the rsyslog project</a>.</p>
<p><b>Follow the links below for the</b></p>
<ul>
-<li><a href="rsyslogd.man.txt">rsyslogd man page</a>
+<li><a href="man_rsyslogd.html">rsyslogd man page</a>
<li><a href="rsyslog_conf.html">configuration file syntax (rsyslog.conf)</a><li>
<a href="property_replacer.html">property replacer, an important core component</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><li><a href="generic_design.html">backgrounder on generic
syslog application design</a><li><a href="contributors.html">contributor "Hall
of Fame"</a><li><a href="modules.html">description of rsyslog modules</a></ul>
<p><b>We have some in-depth papers on</b></p>
diff --git a/doc/modules.html b/doc/modules.html new file mode 100644 index 0000000..9288750 --- /dev/null +++ b/doc/modules.html @@ -0,0 +1,95 @@ +<html><head> +<title>Writing syslog Data to MySQL</title> +<meta name="KEYWORDS" content="syslog, mysql, syslog to mysql, howto"> +</head> +<body> +<h1>About rsyslog Modules</h1> + <P><small><i>Written by + <a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer + Gerhards</a> (2007-07-28)</i></small></P> +<p><font color="#FF0000"><b>This document is incomplete. The module interface is +also quite incomplete and under development. Do not currently use it!</b></font> +You may want to visit <a href="http://rgerhards.blogspot.com/">Rainer's blog</a> +to learn what's going on.</p> +<h2>Overview</h2> +<p>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. </p> +<p>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.</p> +<h2>Module "generation"</h2> +<p>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".</p> +<p>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).</p> +<h2>Naming Conventions</h2> +<h3>Source</h3> +<p>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.</p> +<h2>Module Security</h2> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<h2>Action Selectors</h2> +<p>Modules (and rsyslog) need to know when they are called. For this, there must +a 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.</p> +<p>An in-depth discussion of module designation in action selectors can be found +in this forum thread:</p> +<p> +<a href="http://www.rsyslog.com/index.php?name=PNphpBB2&file=viewtopic&p=678#678"> +http://www.rsyslog.com/index.php?name=PNphpBB2&file=viewtopic&p=678#678</a></p> +<h2>Copyright</h2> +<p>Copyright (c) 2007 +<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> +and <a href="http://www.adiscon.com/en/">Adiscon</a>.</p> +<p>Permission is granted to copy, distribute and/or modify this document under +the terms of the GNU Free Documentation License, Version 1.2 or any later +version published by the Free Software Foundation; with no Invariant Sections, +no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be +viewed at <a href="http://www.gnu.org/copyleft/fdl.html"> +http://www.gnu.org/copyleft/fdl.html</a>.</p> +</body> +</html> diff --git a/doc/rsconf1_allowedsender.html b/doc/rsconf1_allowedsender.html index 619b71e..4a980b8 100644 --- a/doc/rsconf1_allowedsender.html +++ b/doc/rsconf1_allowedsender.html @@ -13,7 +13,7 @@ <p>"$AllowedSender" is the directive - it must be written exactly as shown and the $ must start at the first column of the line. "<protocol>" is either "UDP" or "TCP". It must immediately be followed by the comma, else you will receive an error message. "ip[/bits]" is a machine or network ip address as in "192.0.2.0/24" or "127.0.0.1". If the "/bits" part is omitted, a single host is assumed (32 bits or mask 255.255.255.255). "/0" is not allowed, because that would match any sending system. If you intend to do that, just remove all $AllowedSender directives. If more than 32 bits are requested with IPv4, they are adjusted to 32. For IPv6, the limit is 128 for obvious reasons. Hostnames, with and without wildcards, may also be provided. If so, the result of revers DNS resolution is used for filtering. Multiple allowed senders can be specified in a comma-delimited list. Also, multiple $AllowedSender lines can be given. They are all combined into one UDP and one TCP list. Performance-wise, it is good to specify those allowed senders with high traffic volume before those with lower volume. As soon as a match is found, no further evaluation is necessary and so you can save CPU cycles.</p> <p>Rsyslogd handles allowed sender detection very early in the code, nearly as the first action after receiving a message. This keeps the access to potential vulnerable code in rsyslog at a minimum. However, it is still a good idea to impose allowed sender limitations via firewalling.</p> <p><b>WARNING:</b> by UDP design, rsyslogd can not identify a spoofed sender address in UDP syslog packets. As such, a malicious person could spoof the address of an allowed sender, send such packets to rsyslogd and rsyslogd would accept them as being from the faked sender. To prevent this, use syslog via TCP exclusively. If you need to use UDP-based syslog, make sure that you do proper egress and ingress filtering at the firewall and router level.</p> -<p>Rsyslog also detects some kind of malicious reverse DNS entries. In any case, using DNS names adds an extra layer of vulnerability. We recommend to stick with hard-coded IP addresses whereever possible.</p> +<p>Rsyslog also detects some kind of malicious reverse DNS entries. In any case, using DNS names adds an extra layer of vulnerability. We recommend to stick with hard-coded IP addresses wherever possible.</p> <p><b>Sample:</b></p> <p><code><b>$AllowedSender UDP, 127.0.0.1, 192.0.2.0/24, [::1]/128, *.example.net, somehost.example.com</b></code></p> @@ -25,4 +25,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsconf1_controlcharacterescapeprefix.html b/doc/rsconf1_controlcharacterescapeprefix.html index 23bf5c6..6dab1e2 100644 --- a/doc/rsconf1_controlcharacterescapeprefix.html +++ b/doc/rsconf1_controlcharacterescapeprefix.html @@ -8,7 +8,7 @@ <p><b>Default:</b> \</p> <p><b>Description:</b></p> <p>This option specifies the prefix character to be used for control character escaping (see option $EscapeControlCharactersOnReceive). By default, it is '\', which is backwards-compatible with sysklogd. Change it to '#' in order to be compliant to the value that is somewhat suggested by Internet-Draft syslog-protocol.</p> -<p><b>IMPORTANT</b>: do not use the ' character. This is reserved and will most probably be used in the future as a character delimiter. For the same reason, the syntax of this directive will probably change in furture releases.</p> +<p><b>IMPORTANT</b>: do not use the ' character. This is reserved and will most probably be used in the future as a character delimiter. For the same reason, the syntax of this directive will probably change in future releases.</p> <p><b>Sample:</b></p> <p><code><b>$EscapeControlCharactersOnReceive # # as of syslog-protocol</b></code></p> @@ -20,4 +20,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsconf1_droptrailinglfonreception.html b/doc/rsconf1_droptrailinglfonreception.html index e0054cc..1e3aa8a 100644 --- a/doc/rsconf1_droptrailinglfonreception.html +++ b/doc/rsconf1_droptrailinglfonreception.html @@ -7,7 +7,7 @@ <p><b>Type:</b> global configuration directive</p> <p><b>Default:</b> on</p> <p><b>Description:</b></p> -<p>Syslog messages frequently have the line feed character (LF) as the last character of the message. In allmost all cases, this LF should not really become part of the message. However, recent IETF syslog standardization recommends against modifying syslog messages (e.g. to keep digital signatures valid). This option allows to specify if trailing LFs should be dropped or not. The default is to drop them, which is consistent with what sysklogd does.</p> +<p>Syslog messages frequently have the line feed character (LF) as the last character of the message. In almost all cases, this LF should not really become part of the message. However, recent IETF syslog standardization recommends against modifying syslog messages (e.g. to keep digital signatures valid). This option allows to specify if trailing LFs should be dropped or not. The default is to drop them, which is consistent with what sysklogd does.</p> <p><b>Sample:</b></p> <p><code><b>$DropTrailingLFOnRecption on</b></code></p> @@ -19,4 +19,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsconf1_escapecontrolcharactersonreceive.html b/doc/rsconf1_escapecontrolcharactersonreceive.html index f273b85..a885511 100644 --- a/doc/rsconf1_escapecontrolcharactersonreceive.html +++ b/doc/rsconf1_escapecontrolcharactersonreceive.html @@ -7,7 +7,7 @@ <p><b>Type:</b> global configuration directive</p> <p><b>Default:</b> on</p> <p><b>Description:</b></p> -<p>This directive instructs rsyslogd to replace control characters during reception of the message. The intent is to provide a way to stop non-printable messages from entering the syslog system as whole. If this option is truned on, all control-characters are converted to a 3-digit octal number and be prefixed with the $ControlCharacterEscapePrefix character (being '\' by default). For example, if the BEL character (ctrl-g) is included in the message, it would be converted to "\007". To be compatible to sysklogd, this option must be turned on.</p> +<p>This directive instructs rsyslogd to replace control characters during reception of the message. The intent is to provide a way to stop non-printable messages from entering the syslog system as whole. If this option is turned on, all control-characters are converted to a 3-digit octal number and be prefixed with the $ControlCharacterEscapePrefix character (being '\' by default). For example, if the BEL character (ctrl-g) is included in the message, it would be converted to "\007". To be compatible to sysklogd, this option must be turned on.</p> <p><b>Warning:</b></p> <ul> <li>turning on this option most probably destroys non-western character sets @@ -26,4 +26,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsconf1_filecreatemode.html b/doc/rsconf1_filecreatemode.html index b6498cd..7c6f171 100644 --- a/doc/rsconf1_filecreatemode.html +++ b/doc/rsconf1_filecreatemode.html @@ -14,7 +14,7 @@ <p><code><b>$FileCreateMode 0600</b></code></p> <p>This sample lets rsyslog create files with read and write access only for the users it runs under.</p> <p>The following sample is deemed to be a complete rsyslog.conf: -<p><code><b>$umask 0000 # make sure nothing interfers with the following +<p><code><b>$umask 0000 # make sure nothing interferes with the following definitions<br> *.* /var/log/file-with-0644-default<br> $FileCreateMode 0600<br> @@ -32,4 +32,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsconf1_mainmsgqueuesize.html b/doc/rsconf1_mainmsgqueuesize.html index b9501e0..acf88e9 100644 --- a/doc/rsconf1_mainmsgqueuesize.html +++ b/doc/rsconf1_mainmsgqueuesize.html @@ -7,9 +7,9 @@ <p><b>Type:</b> global configuration directive</p> <p><b>Default:</b> 10000</p> <p><b>Description:</b></p> -<p>This allows to specify the maximum size of the message queue. This directive is only available when rsyslogd has been compiled with multithreading support. In this mode, receiver and output modules are de-coupled via an in-memory queue. This queue buffers messages when the output modules are not capable to process them as fast as they are received. Once the queue size is exhausted, messages will be dropped. The slower the output (e.g. MySQL), the larger the queue should be. Buffer space for the actual queue entries is allocated on an as-needed basis. Please keep in mind that a very large queue may exhaust available system memory and swap space. Keep this in mind when configuring the max size. The actual size of a message depends largely on its content and the orginator. As a rule of thumb, typically messages should not take up more then roughtly 1k (this is the memory structure, not what you see in a network dump!). For typical linux messages, 512 bytes should be a good bet. Please also note that there is a minimal amout of memory taken for each queue entry, no matter if it is used or not. This is one pointer value, so on 32bit systems, it should typically be 4 bytes and on 64bit systems it should typically be 8 bytes. For example, the default queue size of 10,000 entries needs roughly 40k fixed overhead on a 32 bit system.</p> +<p>This allows to specify the maximum size of the message queue. This directive is only available when rsyslogd has been compiled with multithreading support. In this mode, receiver and output modules are de-coupled via an in-memory queue. This queue buffers messages when the output modules are not capable to process them as fast as they are received. Once the queue size is exhausted, messages will be dropped. The slower the output (e.g. MySQL), the larger the queue should be. Buffer space for the actual queue entries is allocated on an as-needed basis. Please keep in mind that a very large queue may exhaust available system memory and swap space. Keep this in mind when configuring the max size. The actual size of a message depends largely on its content and the originator. As a rule of thumb, typically messages should not take up more then roughly 1k (this is the memory structure, not what you see in a network dump!). For typical linux messages, 512 bytes should be a good bet. Please also note that there is a minimal amount of memory taken for each queue entry, no matter if it is used or not. This is one pointer value, so on 32bit systems, it should typically be 4 bytes and on 64bit systems it should typically be 8 bytes. For example, the default queue size of 10,000 entries needs roughly 40k fixed overhead on a 32 bit system.</p> <p><b>Sample:</b></p> -<p><code><b>$MainMsgQueueSize 100000 # 100,000 may be a value to handle bursty traffic</b></code></p> +<p><code><b>$MainMsgQueueSize 100000 # 100,000 may be a value to handle burst traffic</b></code></p> <p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p> @@ -19,4 +19,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsconf1_moddir.html b/doc/rsconf1_moddir.html new file mode 100644 index 0000000..ced07dc --- /dev/null +++ b/doc/rsconf1_moddir.html @@ -0,0 +1,27 @@ +<html> +<head> +<title>rsyslog.conf file</title> +</head> +<body> +<h2>$ModDir</h2> +<p><b>Type:</b> global configuration directive</p> +<p><b>Default:</b> system default for user libraries, e.g. +/usr/local/lib/rsyslog/</p> +<p><b>Description:</b></p> +<p>Provides the default directory in which loadable modules reside. This may be +used to specify an alternate location that is not based on the system default. +If the system default is used, there is no need to specify this directive. Please +note that it is vitally important to end the path name with a slash, else module +loads will fail.</p> +<p><b>Sample:</b></p> +<p><code><b>$ModDir /usr/rsyslog/libs/ # note the trailing slash!</b></code></p> + +<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual +index</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 © 2007 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>
\ No newline at end of file diff --git a/doc/rsconf1_modload.html b/doc/rsconf1_modload.html index 397e675..c9b4294 100644 --- a/doc/rsconf1_modload.html +++ b/doc/rsconf1_modload.html @@ -12,7 +12,7 @@ The plug-in must obey the rsyslog module API. Currently, only MySQL is available as a plugin, but others may create their own. A plug-in must be loaded BEFORE any configuration file lines that reference it.</p> <p>Modules must be present in the system default destination for rsyslog -modules. You can also set the direcotry via the <a href="rsconf1_moddir.html"> +modules. You can also set the directory via the <a href="rsconf1_moddir.html"> $ModDir</a> directive.</p> <p>If a full path name is specified, the module is loaded from that path. The default module directory is ignored in that case.</p> @@ -28,4 +28,4 @@ Copyright © 2007 by <a href="http://www.gerhards.net/rainer">Rainer Gerhard <a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL version 2 or higher.</font></p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/rsyslog_conf.html b/doc/rsyslog_conf.html index ec99a60..266a6dc 100644 --- a/doc/rsyslog_conf.html +++ b/doc/rsyslog_conf.html @@ -117,7 +117,7 @@ the wrong one, you are still vulnerable to sql injection.</b><br> <br> Please note that the database writer *checks* that the sql option is present in the template. If it is not present, the write database action is disabled. This -is to guard you against accidential forgetting it and then becoming vulnerable +is to guard you against accidental forgetting it and then becoming vulnerable to SQL injection. The sql option can also be useful with files - especially if you want to import them into a database on another machine for performance reasons. However, do NOT use it if you do not have a real need for it - among @@ -157,7 +157,7 @@ this is the "file" part of selector lines (and this is why we are not output channel syntax will stay after the next review). There is a<br> difference, though: selector channels both have filter conditions (currently facility and severity) as well as the output destination. Output channels define -the output defintion, only. As of this build, they can only be used to write to +the output definition, only. As of this build, they can only be used to write to files - not pipes, ttys or whatever else. If we stick with output channels, this will change over time.</p> <p>In concept, an output channel includes everything needed to know about an @@ -189,7 +189,7 @@ line includes the channel name plus an $ sign in front of it. A sample might be: *.* $mychannel<br> <br> In its current form, output channels primarily provide the ability to size-limit -an output file. To do so, specify a maximum size. When this size is reachead, +an output file. To do so, specify a maximum size. When this size is reached, rsyslogd will execute the action-on-max-size command and then reopen the file and retry. The command should be something like a log rotation script or a similar thing.</p> @@ -234,13 +234,13 @@ in BSD syslogd is not supported by rsyslogd. By default, no hostname or program is set.</p> <h3>Selectors</h3> <p><b>Selectors are the traditional way of filtering syslog messages.</b> They -have been kept in rsyslog with their orginal syntax, because it is well-known, +have been kept in rsyslog with their original syntax, because it is well-known, highly effective and also needed for compatibility with stock syslogd configuration files. If you just need to filter based on priority and facility, you should do this with selector lines. They are <b>not</b> second-class -citicens in rsyslog and offer the best performance for this job.</p> +citizens in rsyslog and offer the best performance for this job.</p> <p>The selector field itself again consists of two parts, a facility and a -priority, separated by a period (``.''). Both parts are case insenstive and can +priority, separated by a period (``.''). Both parts are case insensitive and can also be specified as decimal numbers, but don't do that, you have been warned. Both facilities and priorities are described in rsyslog(3). The names mentioned below correspond to the similar LOG_-values in /usr/include/rsyslog.h.<br><br>The facility is one of the following keywords: auth, authpriv, cron, daemon, @@ -302,7 +302,7 @@ brief, the syntax is as follows:</p> <td>isequal</td> <td>Compares the "value" string provided and the property contents. These two values must be exactly equal to match. The difference to - contains is that contains searchs for the value anywhere inside the + contains is that contains searches for the value anywhere inside the property value, whereas all characters must be identical for isequal. As such, isequal is most useful for fields like syslogtag or FROMHOST, where you probably know the exact contents.</td> @@ -386,7 +386,7 @@ filters. An example would be</p> <p><code><b>*.=crit rger<br> & root<br> & /var/log/critmsgs</b></code></p> -<p>These three lines send critical messages to the usrs rger and root and also +<p>These three lines send critical messages to the user rger and root and also store them in /var/log/critmsgs. <b>Using multiple actions per selector is</b> convenient and also <b>offers a performance benefit</b>. As the filter needs to be evaluated only once, there is less computation required to process the @@ -477,10 +477,10 @@ separated by commas. The following options are right now defined:</p> make an awful lot of sense. There is hardly a difference between level 1 and 9 for typical syslog messages. You can expect a compression gain between 0% and 30% for typical messages. Very chatty messages may - compress up to 50%, but this is seldomly seen with typicaly traffic. + compress up to 50%, but this is seldom seen with typically traffic. Please note that rsyslogd checks the compression gain. Messages with 60 bytes or less will never be compressed. This is because compression gain - is pretty unlikely and we prefer to save CPU cycles. Messags over that + is pretty unlikely and we prefer to save CPU cycles. Messages over that size are always compressed. However, it is checked if there is a gain in compression and only if there is, the compressed message is transmitted. Otherwise, the uncompressed messages is transmitted. This saves the @@ -510,7 +510,7 @@ separated by commas. The following options are right now defined:</p> primary reason for that is that it seems technically impossible to provide compatibility between some of those changes. So you should take this note very serious. It is not something we do not *like* to do (and - may change our mind if enough pepole beg...), it is something we most + may change our mind if enough people beg...), it is something we most probably *can not* do for technical reasons (aka: you can beg as much as you like, it won't change anything...).</p> <p>The most important implication is that compressed syslog messages via @@ -546,9 +546,26 @@ might be too late.</p> <p>Emergency messages often go to all users currently online to notify them that something strange is happening with the system. To specify this wall(1)-feature use an asterisk ("*'').</p> +<h3>Call Plugin</h3> +<p>This is a generic way to call an output plugin. The plugin must support this +functionality. Actual parameters depend on the module, so see the module's doc +on what to supply. The general syntax is as follows:</p> +<p>:modname:params;template</p> +<p>Currently, the ommysql database output module supports this syntax (in +addtion to the ">" syntax it traditionally supported). For ommysql, the module +name is "ommysql" and the params are the traditional ones. The ;template part is +not module specific, it is generic rsyslog functionality available to all +modules.</p> +<p>As an example, the ommysql module may be called as follows:</p> +<p>:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate</p> +<p>For details, please see the "Database Table" section of this documentation.</p> +<p>Note: as of this writing, the ":modname:" part is hardcoded into the module. +So the name to use is not necessarily the name the module's plugin file is +called.</p> <h3>Database Table</h3> <p>This allows logging of the message to a database table. Currently, only MySQL -databases are supported. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible schema is required +databases are supported. However, other database drivers will most probably be +developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible schema is required for this to work. You can create that schema with the createDB.SQL file that came with the rsyslog package. You can also<br> use any other schema of your liking - you just need to define a proper template @@ -574,7 +591,7 @@ discarded. No further processing of it occurs. Discard has primarily been added to filter out messages before carrying on any further processing. For obvious reasons, the results of "discard" are depending on where in the configuration file it is being used. Please note that once a message has been discarded there -is no way to retrive it in later configuration file lines.</p> +is no way to retrieve it in later configuration file lines.</p> <p>Discard can be highly effective if you want to filter out some annoying messages that otherwise would fill your log files. To do that, place the discard actions early in your log files. This often plays well with property-based @@ -632,7 +649,7 @@ self-explanatory. If not, please see www.monitorware.com/rsyslog/ for advise.</p <p>Please note that the samples are split across multiple lines. A template MUST NOT actually be split across multiple lines.<br> <br> -A template that resambles traditional syslogd file output:<br> +A template that resembles traditional syslogd file output:<br> $template TraditionalFormat,"%timegenerated% %HOSTNAME%<br> %syslogtag%%msg:::drop-last-lf%\n"<br> <br> diff --git a/doc/rsyslog_recording_pri.html b/doc/rsyslog_recording_pri.html index c84d47f..48852ca 100644 --- a/doc/rsyslog_recording_pri.html +++ b/doc/rsyslog_recording_pri.html @@ -18,7 +18,7 @@ written to a log file.</i></p> facility indicates where the message originated from (e.g. kernel, mail subsystem) while the severity provides a glimpse of how important the message might be (e.g. error or informational). Be careful with these values: they are -in no way consistent accross applications (especially severity). However, they +in no way consistent across applications (especially severity). However, they still form the basis of most filtering in syslog.conf. For example, the directive (aka "selector line)</p> <p align="center"> @@ -131,4 +131,4 @@ no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be viewed at <a href="http://www.gnu.org/copyleft/fdl.html"> http://www.gnu.org/copyleft/fdl.html</a>.</p> </body> -</html>
\ No newline at end of file +</html> diff --git a/doc/status.html b/doc/status.html index fe56385..0f68ba1 100644 --- a/doc/status.html +++ b/doc/status.html @@ -4,11 +4,11 @@ </head> <body> <h2>rsyslog status page</h2> -<p>This page reflects the status as of 2007-10-12.</p> +<p>This page reflects the status as of 2007-10-19.</p> <h2>Current Releases</h2> -<p><b>development:</b> 1.19.9 - -<a href="http://www.rsyslog.com/Article135.phtml">change log</a> - -<a href="http://www.rsyslog.com/Downloads-index-req-getit-lid-61.phtml">download</a></p> +<p><b>development:</b> 1.19.10 - +<a href="http://www.rsyslog.com/Article137.phtml">change log</a> - +<a href="http://www.rsyslog.com/Downloads-index-req-getit-lid-62.phtml">download</a></p> <p><b>stable:</b> 1.0.5 - <a href="http://www.rsyslog.com/Article85.phtml">change log</a> - <a href="http://www.rsyslog.com/Downloads-index-req-getit-lid-39.phtml">download</a></p> <p> (<a href="version_naming.html">How are versions named?</a>)</p> @@ -19,7 +19,7 @@ security advisory</a>).</p> <p>Thankfully, a number of folks have begin to build packages and help port rsyslog to other platforms. As such, <a href="http://wiki.rsyslog.com/index.php/Platforms">the platform list is now -maintened inside the rsyslog wiki</a>. Platform maintainers perhaps have posted +maintained inside the rsyslog wiki</a>. Platform maintainers perhaps have posted extra information there. If you do platform-specific work, feel free to add information to the wiki.</p> <h2>Additional information</h2> diff --git a/doc/syslog-protocol.html b/doc/syslog-protocol.html index 5305d81..72de5c2 100644 --- a/doc/syslog-protocol.html +++ b/doc/syslog-protocol.html @@ -14,7 +14,7 @@ highly volatile. It may change from release to release. So while it provides some advantages in the real world, users are cautioned against using it right now. If you do, be prepared that you will probably need to update all of your rsyslogds with each new release. If you try it anyhow, please provide feedback -as that would be most benefitial for us.</p> +as that would be most beneficial for us.</p> <h2>Currently supported message format</h2> <p>Due to recent discussion on syslog-protocol, we do not follow any specific revision of the draft but rather the candidate ideas. The format supported @@ -59,12 +59,12 @@ SP MSG</code></b></p> as is and stuffed it into the MSG part. Please note that I think this will be a route that other implementors would take, too.</li> <li>A minimal parser is easy to implement. It took me roughly 2 hours to add - it to rsyslogd. This includes the time for restructering the code to be able + it to rsyslogd. This includes the time for restructuring the code to be able to parse both legacy syslog as well as syslog-protocol. The parser has some restrictions, though<ul> <li>STRUCTURED-DATA field is extracted, but not validated. Structured data "[test ]]" is not caught as an error. Nor are any other errors caught. For - my needs with this syslogd, that level of structued data processing is + my needs with this syslogd, that level of structured data processing is probably sufficient. I do not want to parse/validate it in all cases. This is also a performance issue. I think other implementors could have the same view. As such, we should not make validation a requirement.</li> @@ -89,7 +89,7 @@ SP MSG</code></b></p> we could do against this. This questions the usefulness of the TRUNCATE bit. Eventually, I could look at the UDP headers and see that it is a fragment. I have looked at a network sniffer log of the conversation. This looks like - two totally-independant messages were sent by the sender stack.</li> + two totally-independent messages were sent by the sender stack.</li> <li>The maximum message size is currently being configured via a preprocessor #define. It can easily be set to 2K or 4K, but more than 4K is not possible because of UDP stack limitations. Eventually, this can be @@ -116,7 +116,7 @@ SP MSG</code></b></p> midnight in the old year. I think this is acceptable. However, I can not assign a high-precision timestamp, at least it is somewhat off if I take the timestamp from message reception on the local socket. An alternative might - be to ígnore the timestamp present and instead use that one when the message + be to ignore the timestamp present and instead use that one when the message is pulled from the local socket (I am talking about IPC, not the network - just a reminder...). This is doable, but eventually not advisable. It looks like this needs to be resolved via a configuration option.</li> @@ -174,7 +174,7 @@ SP MSG</code></b></p> <p>These are my personal conclusions and suggestions. Obviously, they must be discussed ;)</p> <ul> - <li>NUL should be disallowd in MSG</li> + <li>NUL should be disallowed in MSG</li> <li>As it is not possible to definitely know the character encoding of the application-provided message, MSG should <b>not</b> be specified to use UTF-8 exclusively. Instead, it is suggested that any encoding may be used but diff --git a/doc/version_naming.html b/doc/version_naming.html index 31fe056..a685f5f 100644 --- a/doc/version_naming.html +++ b/doc/version_naming.html @@ -5,7 +5,7 @@ <body> <h1>Version Naming</h1> <p>This document briefly outlines the strategy for naming versions. It applies -to versions 1.0.0 and above. Versions below that are all instable and have a +to versions 1.0.0 and above. Versions below that are all unstable and have a different naming schema.</p> <p><b>Please note that version naming is currently being changed. There is a <a href="http://rgerhards.blogspot.com/2007/08/on-rsyslog-versions.html">blog @@ -14,20 +14,20 @@ post about future rsyslog versions</a>.</b></p> been added. This is expected to happen quite infrequently.</p> <p>The minor version number is incremented whenever there is "sufficient need" (at the discretion of the developers). There is a notable difference between -stable and instable branches. The <b>stable branch</b> always has a minor +stable and unstable branches. The <b>stable branch</b> always has a minor version number in the range from 0 to 9. It is expected that the stable branch will receive bug and security fixes only. So the range of minor version numbers should be quite sufficient.</p> -<p>For the <b>instable branch</b>, minor version numbers always start at 10 and +<p>For the <b>unstable branch</b>, minor version numbers always start at 10 and are incremented as needed (again, at the discretion of the developers). Here, new minor versions include both fixes as well as new features (hopefully most of the time). They are expected to be released quite often.</p> <p>The patch level (third number) is incremented whenever a really minor thing must be added to an existing version. This is expected to happen quite infrequently.</p> -<p>In general, the instable branch carries all new development. Once it +<p>In general, the unstable branch carries all new development. Once it concludes with a sufficiently-enhanced, quite stable version, a new major stable version is assigned.</p> </body> -</html>
\ No newline at end of file +</html> |