syslog-ng Premium Edition 7.0.30 - Administration Guide

Upgrading from syslog-ng PE to syslog-ng OSE is unsupported since it counts as downgrading.

If you wish to upgrade your existing syslog-ng OSE installation to syslog-ng PE, there are a number of considerations to keep in mind. This section highlights the main differences between syslog-ng OSE and syslog-ng PE that are useful to know before performing an upgrade. It also provides you with step-by-step instructions on how to do the upgrade.

Feature differences

syslog-ng OSE includes certain features that are highly experimental, require special external dependencies, or are important only to a very limited set of users. While syslog-ng PE is built from the same code base, it includes only a subset of syslog-ng OSE features. Those that are well tested and represent commercial value. These features are commercially supported as they are covered by automated end-to-end tests, which make sure that they not only compile but work correctly on many different platforms.

This means that your syslog-ng OSE installation may contain features that are not part of syslog-ng PE, or if they are, they may not have been tested.

Packaging

The packaging of syslog-ng OSE and syslog-ng PE also differ greatly.

With syslog-ng OSE, distribution packages do not bundle dependencies and only include features for which dependencies are available within the distribution. Packaging is modular to make sure that you install only a minimal set of extra dependencies. In addition, the naming and content of subpackages varies between distributions, and there are also unofficial syslog-ng OSE packages enabling more features than available in official distribution packages.

In the case of syslog-ng PE, all dependencies are included in a single package either in a distribution specific format (rpm or deb) or in a generic .run installer.

The cleanest way to upgrade from syslog-ng OSE to syslog-ng PE is to remove the syslog-ng OSE package from the system. This way you can avoid the packaging conflicts and feature differences.

In the example procedure provided here, we describe an upgrade of syslog-ng OSE version 3.12 from unofficial repositories running on Red Hat Enterprise Linux 7.4 to syslog-ng PE version 7.0.4. The process should work in a fairly similar way when using other OS or syslog-ng versions.

To upgrade from syslog-ng OSE to syslog-ng PE

1. Remove syslog-ng OSE.

   The following instructions assume that the user is in the /root directory.

   1. Unless you have not touched the syslog-ng configuration at all, make a backup of syslog-ng.conf first. Copy the contents of /etc/syslog-ng to a directory under /root (or where you can find it), so you have a backup you can work from later:

      cp -R /etc/syslog-ng sngose

   2. Remove the syslog-ng package and dependent subpackages:

      yum erase syslog-ng

   3. Remove the /etc/syslog-ng directory:

      rm -fr /etc/syslog-ng

      Caution: Check the output of yum carefully. If there are any applications listed other than syslog-ng and subpackages, remove syslog-ng using rpm -e –€”nodeps, so dependent packages are not removed.

2. Install syslog-ng PE.

   The following instructions assume that the syslog-ng PE rpm package is available in the current directory. You can install syslog-ng PE using the following command:

   [root@localhost ~]# rpm -Uvh syslog-ng-premium-edition-compact-7.0.5-1.rhel7.x86_64.rpm
   Preparing...                          ################################# [100%]
   Trying to stop syslog services on Linux, using systemd services.
   Updating / installing...
      1:syslog-ng-premium-edition-compact################################# [100%]
   Created symlink from /etc/systemd/system/multi-user.target.wants/syslog-ng.service to /usr/lib/systemd/system/syslog-ng.service.
   [root@localhost ~]#

3. Merge configurations.

   The configuration file of the freshly installed syslog-ng PE is available under /opt/syslog-ng/etc/syslog-ng.conf. Start by making a backup of it.

   The next steps largely depend on the particulars of your previous syslog-ng OSE configuration and what you want to achieve:

   1. Append your old OSE configuration to /opt/syslog-ng/etc/syslog-ng.conf.

   2. Edit out redundant configuration parts, for example, a version declaration.

   3. Edit out those configuration parts that refer to features unavailable in syslog-ng PE, such as the Riemann destination.

      If you try to start syslog-ng PE with an unknown feature enabled, it fails with a similar error message (in the example, it is the Riemann destination that is causing the error):

      /opt/syslog-ng/sbin/syslog-ng -s
      Error parsing destination, destination plugin riemann not found in /opt/syslog-ng/etc/syslog-ng.conf at line 41, column 2:
      
          riemann(
          ^^^^^^^

   4. Syntax check your configuration using the -s option of syslog-ng. Make sure that you use the full path to syslog-ng PE, or add it to the PATH:

      /opt/syslog-nb/sbin/syslog-ng -s

   5. If no errors are found, stop syslog-ng:

      systemctl stop syslog-ng

   6. Try to start syslog-ng from the command line in the foreground using the -F option, so you can see any errors:

      /opt/syslog-ng/sbin/syslog-ng -F

      Some common error messages and explanations:

      • syslog-ng OSE uses s_sys for references to local system sources, while syslog-ng PE uses s_local. Remember to rename such references, otherwise a similar error message will be displayed:

        [2017-10-03T14:04:18.968550] Error resolving reference; content='source', name='s_sys', location='/opt/syslog-ng/etc/syslog-ng.conf:86:2'

      • Some features of syslog-ng PE require a license file to be present. In the example shown here, a Java plugin failed to initialize due to a missing license:

        [2017-10-03T14:07:05.894534] syslog-ng running in client/relay mode, cannot initialize plugin; plugin name='java'
        [2017-10-03T14:07:05.894560] Error initializing message pipeline; plugin name='java', location='#buffer:2:3'

      Once you have made sure that your configuration works fine, you do not have to start syslog-ng in the foreground anymore.

   7. Stop syslog-ng using Ctrl-C.

   8. Start syslog-ng as a service using systemctl start syslog-ng.

The installer displays the following message if you try to upgrade from complete syslog-ng PE to client setup syslog-ng PE with .run package.

This version of syslog-ng Premium Edition doesn't support storing messages in SQL servers, while the installed one did.