Many users are annoyed by the version number included in the syslog-ng configuration. However, it ensures backward compatibility in syslog-ng. It is especially useful when updating to syslog-ng 4 from version 3, but also when updating within the same major version.
Why?
The syslog-ng configuration format stayed roughly the same ever since it was created. However, new features are added in each new release, and sometimes even long-time defaults settings can change. When you update your operating system and syslog-ng along with it, you want syslog-ng to work from the moment you first start it. This is ensured by the version number included in the configuration. As long as the old number is included, syslog-ng tries to work the old way as much as possible.
How?
When a feature or default setting changes, syslog-ng developers make sure that the old behavior remains available when an old version number is included in the configuration. Once you are ready to update your configuration, all you have to do is a syntax check:
syslog-ng -s
This will print the changes on the terminal:
[root@localhost syslog-ng]# syslog-ng -s [2023-03-17T15:50:53.583894] WARNING: Configuration file format is too old, syslog-ng is running in compatibility mode. Please update it to use the syslog-ng 4.1 format at your time of convenience. To upgrade the configuration, please review the warnings about incompatible changes printed by syslog-ng, and once completed change the @version header at the top of the configuration file; config-version='3.37' [2023-03-17T15:50:53.591649] WARNING: $(format-json) starts using type information associated with name-value pairs in syslog-ng 4.0. This can possibly cause fields in the formatted JSON document to change types if no explicit type hint is specified. This change will cause the type in the output document match the original type that was parsed using json-parser(), add --no-cast argument to $(format-json) to keep the old behavior;
You might not notice it when syslog-ng starts automatically, but the very same warning messages are also printed when syslog-ng starts. These are the messages that annoy many people. However, these messages are there to make their transition from the old config to the new one easier. In some cases, the only warning is that the version number in the configuration is too old. Other times, there are explanations spanning many pages.
In this case, there were two warnings. The first one reminds you that syslog-ng is running in compatibility mode. You will see this as long as the version in the configuration and the version of syslog-ng are different. The second message reminds you that type support was added for version 4.0, and the output of $(format-json) is different by default. You also get instructions on how to restore the original behavior even after updating to version 4.
Updating to version 4
During the syslog-ng 3 series, there were regular minor changes. Using the version in the configuration was useful, but most of the time did not have dramatic effects. However, the change from version 3 to 4 has some huge changes if you use PatternDB, JSON parsing and many of the output possibilities. Embedded Python code does not even start without changing, and you might get unexpected output if you use the results of the JSON and PatternDB parsers.
Version 4 of syslog-ng is already in openSUSE, Fedora and FreeBSD from the major operating systems, and gradually made available in most Linux distributions. Leaving the embedded version number at version 3 ensures that syslog-ng keeps working with the original configuration and Python code after the upgrade. You can update your configuration and Python scripts at a time you prefer without any pressure, instead of trying to fix a non-working syslog-ng installation in a rush. You can learn more about the major changes and upgrade concerns of syslog-ng 4 at https://www.syslog-ng.com/community/b/blog/posts/upgrade-problems-from-syslog-ng-3-to-4
-
If you have questions or comments related to syslog-ng, do not hesitate to contact us. You can reach us by email or even chat with us. For a list of possibilities, check our GitHub page under the “Community” section at https://github.com/syslog-ng/syslog-ng. On Twitter, I am available as @PCzanik, on Mastodon as @Pczanik@fosstodon.org.