diff options
Diffstat (limited to '')
| -rw-r--r-- | source/compatibility/v7compatibility.rst | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/source/compatibility/v7compatibility.rst b/source/compatibility/v7compatibility.rst new file mode 100644 index 0000000..ba6a1de --- /dev/null +++ b/source/compatibility/v7compatibility.rst @@ -0,0 +1,173 @@ +Compatibility Notes for rsyslog v7 +================================== + +This document describes things to keep in mind when moving from v6 to v7. It +does not list enhancements nor does it talk about compatibility concerns +introduced by earlier versions (for this, see their respective compatibility +documents). Its focus is primarily on what you need to know if you used v6 +and want to use v7 without hassle. + +Version 7 builds on the new config language introduced in v6 and extends it. +Other than v6, it not just only extends the config language, but provides +considerable changes to core elements as well. The result is much more power and +ease of use as well (this time that is not contradictionary). + +BSD-Style blocks +---------------- +BSD style blocks are no longer supported (for good reason). See the +`rsyslog BSD blocks info page <http://www.rsyslog.com/g/BSD>`_ +for more information and how to upgrade your config. + +CEE-Properties +-------------- + +In rsyslog v6, CEE properties could not be used across disk-based queues. If this was +done, their content was reset. This was a missing feature in v6. In v7, this feature +has been implemented. Consequently, situations where the previous behaviour were +desired need now to be solved differently. We do not think that this will cause any +problems to anyone, especially as in v6 this was announced as a missing feature. + +omusrmsg: using just a username or "*" is deprecated +---------------------------------------------------- +In legacy config format, the asterisk denotes writing the message to all users. +This is usually used for emergency messages and configured like this: + +:: + + *.emerg * + +Unfortunately, the use of this single character conflicts with other uses, for +example with the multiplication operator. While rsyslog up to versions v7.4 preserves the meaning of +asterisk as an action, it is deprecated and will probably be removed in future versions. +Consequently, a warning message is emitted. To make this warning go away, the action must +be explicitly given, as follows: + +:: + + *.emerg :omusrmsg:* + +The same holds true for user names. For example + +:: + + *.emerg john + +at a minimum should be rewritten as + +:: + + *.emerg :omusrmsg:john + +Of course, for even more clarity the new RainerScript style of action can +also be used: + +:: + + *.emerg action(type="omusrmsg" users="john") + +In Rainer's blog, there is more +`background information on why omusrmsg needed to be changed <https://rainer.gerhards.net/2011/07/why-omusrmsg-is-evil-and-how-it-is.html>`_ +available. + +omruleset and discard (~) action are deprecated +----------------------------------------------- +Both continue to work, but have been replaced by better alternatives. + +The discard action (tilde character) has been replaced by the "stop" +RainerScript directive. It is considered more intuitive and offers slightly +better performance. + +The omruleset module has been replaced by the "call" RainerScript directive. +Call permits to execute a ruleset like a subroutine, and does so with much +higher performance than omruleset did. Note that omruleset could be run off +an async queue. This was more a side than a desired effect and is not supported +by the call statement. If that effect was needed, it can simply be simulated by +running the called rulesets actions asynchronously (what in any case is the right +way to handle this). + +Note that the deprecated modules emit warning messages when being used. +They tell that the construct is deprecated and which statement is to be used +as replacement. This does **not** affect operations: both modules are still +fully operational and will not be removed in the v7 timeframe. + +Retries of output plugins that do not do proper replies +------------------------------------------------------- +Some output plugins may not be able to detect if their target is capable of +accepting data again after an error (technically, they always return OK when +TryResume is called). Previously, the rsyslog core engine suspended such an action +after 1000 successive failures. This lead to potentially a large amount of +errors and error messages. Starting with 7.2.1, this has been reduced to 10 +successive failures. This still gives the plugin a chance to recover. In extreme +cases, a plugin may now enter suspend mode where it previously did not do so. +In practice, we do NOT expect that. + +omfile: file creation time +-------------------------- +Originally, omfile created files immediately during startup, no matter if +they were written to or not. In v7, this has changed. Files are only created +when they are needed for the first time. + +Also, in pre-v7 files were created *before* privileges were dropped. This meant +that files could be written to locations where the actual desired rsyslog +user was *not* permitted to. In v7, this has been fixed. This is fix also +the prime reason that files are now created on demand (which is later in the +process and after the privilege drop). + +Notes for the 7.3/7.4 branch +---------------------------- + +"last message repeated n times" Processing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This processing has been optimized and moved to the input side. This results +in usually far better performance and also de-couples different sources +from the same +processing. It is now also integrated in to the more generic rate-limiting +processing. + +User-Noticable Changes +...................... +The code works almost as before, with two exceptions: + +* The suppression amount can be different, as the new algorithm + precisely check's a single source, and while that source is being + read. The previous algorithm worked on a set of mixed messages + from multiple sources. +* The previous algorithm wrote a "last message repeated n times" message + at least every 60 seconds. For performance reasons, we do no longer do + this but write this message only when a new message arrives or rsyslog + is shut down. + +Note that the new algorithms needs support from input modules. If old +modules which do not have the necessary support are used, duplicate +messages will most probably not be detected. Upgrading the module code is +simple, and all rsyslog-provided plugins support the new method, so this +should not be a real problem (crafting a solution would result in rather +complex code - for a case that most probably would never happen). + +Performance Implications +........................ +In general, the new method enables far faster output processing. However, it +needs to be noted that the "last message repeated n" processing needs parsed +messages in order to detect duplicated. Consequently, if it is enabled the +parser step cannot be deferred to the main queue processing thread and +thus must be done during input processing. The changes workload distribution +and may have (good or bad) effect on the overall performance. If you have +a very high performance installation, it is suggested to check the performance +profile before deploying the new version. + +**Note:** for high-performance +environments it is highly recommended NOT to use "last message repeated n times" +processing but rather the other (more efficient) rate-limiting methods. These +also do NOT require the parsing step to be done during input processing. + +Stricter string-template Processing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Previously, no error message for invalid string template parameters +was generated. +Rather a malformed template was generated, and error information emitted +at runtime. However, this could be quite confusing. Note that the new code +changes user experience: formerly, rsyslog and the affected +actions properly started up, but the actions did not produce proper +data. Now, there are startup error messages and the actions are NOT +executed (due to missing template due to template error). |