diff options
| -rw-r--r-- | doc/imjournal.html | 64 |
1 files changed, 56 insertions, 8 deletions
diff --git a/doc/imjournal.html b/doc/imjournal.html index df9a436a..30f07ff5 100644 --- a/doc/imjournal.html +++ b/doc/imjournal.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head> -<meta http-equiv="Content-Language" content="en"><title>Text File Input Monitor</title></head> +<meta http-equiv="Content-Language" content="en"><title>Systemd Journal Input Module</title></head> <body> <a href="rsyslog_conf_modules.html">back</a> @@ -11,36 +11,84 @@ <p><b>Description</b>:</p> <p>Provides the ability to import structured log messages from systemd journal to syslog.</p> +<p>Note that this module reads the journal database, what is considered a +relativly performance-intense operation. As such, the performance of a +configuration utilizing this +module may be notably slower then when using +<a href="imuxsock.html">imuxsock</a>. The journal provides imuxsock with a +copy of all "classical" syslog messages, however, it does not provide +structured data. If the latter is needed, imjournal must be used. Otherwise, +imjournal may be simply replaced by imuxsock. +<p>We suggest to check out our short presentation on +<a href="http://youtu.be/GTS7EuSdFKE">rsyslog journal integration</a> to +learn more details of anticipated use cases. + <p><b>Warning:</b> Some versions of systemd journal have problems with database corruption, which leads to the journal to return the same data endlessly in a thight loop. This results in massive message duplication inside rsyslog probably resulting in a denial-of-service when the system ressouces get exhausted. This can be somewhat mitigated by using proper rate-limiters, but -even then there are spikes of old data which are endlessly repeated. -<b>As such, it is strongly recommended to use this plugin only if there +even then there are spikes of old data which are endlessly repeated. By default, +ratelimiting is activated and permits to process 20,000 messages within 10 +seconds, what should be well enough for most use cases. If insufficient, use +the parameters described below to adjust the permitted volume. +<b>It is strongly recommended to use this plugin only if there is hard need to do so.</b> <p><b>Configuration Directives</b>:</p> <p><b>Module Directives</b></p> <ul> -<li><span style="font-weight: bold;">PersistStateInterval -messages</span><br> +<li><b>PersistStateInterval</b> messages<br> This is a global setting. It specifies how often should the journal state be persisted. This option is useful for rsyslog to start reding from the last journal message it read. -<li><span style="font-weight: bold;">StateFile -/path/to/file</span><br> +<li><b>StateFile</b> /path/to/file<br> This is a global setting. It specifies where the state file for persisting journal state is located. + +<li><b>ratelimit.interval</b> seconds (default: 600)<br> +Specifies the interval in seconds onto which rate-limiting is to be applied. +If more than ratelimit.burst messages are read during that interval, further +messages up to the end of the interval are discarded. The number of messages +discarded is emitted at the end of the interval (if there were any discards). +<br>Setting this to value zero turns off ratelimiting. Note that it is +<b>not recommended to turn of ratelimiting</b>, except that you know for +sure journal database entries will never be corrupted. Without ratelimiting, +a corrupted systemd journal database may cause a kind of denial of service (we +are stressing this point as multiple users have reported us such problems +with the journal database - information current as of June 2013). + +<li><b>ratelimit.burst</b> messages (default: 20000)<br> +Specifies the maximum number of messages that can be emitted within the +ratelimit.interval interval. For futher information, see description there. + +</ul> + +<p><b>Legacy Configuration Directives</b>:</p> +<ul> +<li>$imjournalPersistStateInterval <Delimiter><br> +Equivalent to: ratelimit.PersistStateInterval</li> +<li>$imjournalStateFile <Delimiter><br> +Equivalent to: ratelimit.StateFile</li> +<li>$imjournalRatelimitInterval <Delimiter><br> +Equivalent to: ratelimit.interval</li> +<li>$imjournalRatelimitBurst <Delimiter><br> +Equivalent to: ratelimit.burst</li> </ul> + <b>Caveats/Known Bugs:</b> <p> +<ul> +<li>As stated above, a corrupted systemd journal database can cause major +problems, depending on what the corruption results in. This is beyond the +control of the rsyslog team. +</ul> </p> <p><b>Sample:</b></p> <p> The following example shows pulling structured imjournal messages and saving them into /var/log/ceelog </p> -<textarea rows="15" cols="60"> +<textarea rows="11" cols="60"> module(load="imjournal" PersistStateInterval="100" StateFile="/path/to/file") #load imjournal module module(load="mmjsonparse") #load mmjsonparse module for structured logs |