Upgrade AxoSyslog to a newer version

Use this page if you already run AxoSyslog and you want to move to a newer release. To replace the syslog-ng packages of your distribution with AxoSyslog, see Upgrade syslog-ng to AxoSyslog instead.

An upgrade has two independent parts:

1. Upgrade the AxoSyslog binaries: the packages, the container image, or the Helm chart.
2. Update the @version: line of your configuration file. This step is optional. Until you do it, AxoSyslog keeps the behavior of the declared version. For details, see Update the configuration version.

Before you upgrade AxoSyslog

1. Check which version you run now. Write it down, so that you can roll back to it if necessary.

   syslog-ng --version

   The first line of the output shows the version of the binary, for example:

   axosyslog 4 (4.10.1)
   Config version: 4.2
   Installer-Version: 4.10.1

2. Read the changes of every release between your current version and the target version. Don’t skip the intermediate releases.

   • In What’s new, look for deprecated options and for Breaking change subsections (for example, in Version 4.16).
   • The AxoSyslog release notes on GitHub list every change of every release, including bugfixes.

3. Back up your configuration and your state files:

   • /etc/syslog-ng/: the configuration files, including the files that you include from the main configuration file.
   • /var/lib/syslog-ng/: the persist file (syslog-ng.persist) and the disk-buffer files. If you store these files in a different location (for example, with the --persist-file command-line option, or the dir() option of a disk-buffer), back up that location too.

   For example:

   sudo tar -czf axosyslog-backup-$(date +%Y%m%d).tar.gz /etc/syslog-ng /var/lib/syslog-ng

   For containers, back up the host directories that you mount into the container. For example, with the default Podman with systemd setup, these are /opt/axosyslog/etc and /var/lib/syslog-ng.

Upgrade the AxoSyslog packages

The packages keep your existing configuration file (/etc/syslog-ng/syslog-ng.conf). Upgrade the module packages together with the base package: the installed axosyslog-* module packages must have the same version as the base package.

1. Upgrade the AxoSyslog packages.

   • Debian and Ubuntu:

     1. Update the package lists.

        sudo apt update

     2. Upgrade every installed AxoSyslog package.

        sudo apt install --only-upgrade axosyslog*

     To upgrade all the packages on the host, run sudo apt upgrade instead of the previous step.

   • RHEL, Fedora, and AlmaLinux:

     1. Update the package lists.

        sudo dnf update

     2. Upgrade every installed AxoSyslog package.

        sudo dnf upgrade 'axosyslog*'

        This command upgrades the base package and every installed module package. To upgrade all the packages on the host, run sudo dnf upgrade instead of the previous step.

2. Restart the service to start the new binary.

   sudo systemctl restart syslog-ng

3. Check that the service runs.

   sudo systemctl status syslog-ng

   Make sure that the Active: line of the output shows active (running).

4. Check the version of the binary.

   syslog-ng --version

   Make sure that the first line of the output shows the new version.

5. Check the log of AxoSyslog for warnings about your configuration file. For example:

   sudo journalctl -u syslog-ng -b | grep -i warning

   If your configuration declares an older version, you see warnings about compatibility mode and about incompatible changes. AxoSyslog works in this state. To resolve the warnings, see Update the configuration version.

Upgrade containers

The AxoSyslog container images are available at ghcr.io/axoflow/axosyslog. The latest tag moves to every new release automatically. For production, pin a specific version, such as ghcr.io/axoflow/axosyslog:4.28.0. Then you decide when to upgrade, and you can roll back to a known tag. For the available tags, see the list of image tags.

Upgrade a Docker or Podman container

If you use Podman, replace docker with podman in the commands of this section.

1. Pull the new image. Replace <new-version> with the version number, such as 4.28.0.

   docker pull ghcr.io/axoflow/axosyslog:<new-version>

2. Check your configuration file with the new image. The entrypoint of the image is /usr/sbin/syslog-ng -F, so you can add the --syntax-only option to the end of the command. Mount the directory that contains your configuration file, so that the check also finds the files that you include from it:

   docker run --rm --volume <path-to-your/config-directory>:/etc/syslog-ng ghcr.io/axoflow/axosyslog:<new-version> --syntax-only

   If the configuration is valid, the command doesn’t print errors. Check the output for warnings about incompatible changes.

3. Stop and remove the running container.

   docker stop <container-name>
   docker rm <container-name>

4. Start a new container from the new image. Use the same options, port mappings, and volume mounts that you used for the old container, and change only the image tag. For example:

   docker run -d --name <container-name> -p 514:514/udp -p 601:601/tcp --volume <path-to-your/config-directory>:/etc/syslog-ng --volume <path-to-your/persist-directory>:/var/lib/syslog-ng ghcr.io/axoflow/axosyslog:<new-version>

   Replace the -p options with the ports that your old container published. Mount the same /var/lib/syslog-ng directory as before. It stores the persist file and the disk-buffer files. For details, see Install AxoSyslog with Docker and Install AxoSyslog with Podman.

5. Check the logs of the new container.

   docker logs <container-name>

   The startup message shows the new version, for example: syslog-ng starting up; version='4.28.0'.

Upgrade a Podman systemd service

The AXOSYSLOG_IMAGE environment variable sets the image of the Podman systemd service. The default value in /etc/containers/systemd/axosyslog.container is:

Environment="AXOSYSLOG_IMAGE=ghcr.io/axoflow/axosyslog:latest"

1. Set the new image tag.

   • If you use a pinned version, change the tag in /etc/containers/systemd/axosyslog.container. Alternatively, run sudo systemctl edit axosyslog, and set the variable in the override file:

     [Service]
     Environment="AXOSYSLOG_IMAGE=ghcr.io/axoflow/axosyslog:<new-version>"

   • If you use the latest tag, pull the new image. Podman doesn’t pull a new latest image if one is already available locally.

     sudo podman pull ghcr.io/axoflow/axosyslog:latest

2. Reload the systemd configuration, and restart the service.

   sudo systemctl daemon-reload
   sudo systemctl restart axosyslog

3. Check the log of the service.

   journalctl -b -u axosyslog | tail -100

   The syslog-ng starting up message shows the new version. For details, see Install AxoSyslog with Podman and systemd.

Upgrade the Helm chart

The chart version and the AxoSyslog version are different. Every chart version has an appVersion, and the chart uses the image with that tag by default. If you set the image.tag parameter, the chart uses that image tag, independently of the chart version. For the list of parameters, see Parameters of the AxoSyslog Helm chart.

1. Update the chart repository.

   helm repo update

2. List the available chart versions. The APP VERSION column shows the AxoSyslog version of each chart version.

   helm search repo axosyslog/axosyslog --versions

3. Upgrade the release. Use your values file, so that you keep your settings. To install a specific chart version, add the --version <chart-version> option.

   helm upgrade <release-name> axosyslog/axosyslog -f my-values.yaml

   The output should be similar to:

   Release "<release-name>" has been upgraded. Happy Helming!
   ...

   The collector DaemonSet and the aggregator StatefulSet use the RollingUpdate update strategy, so Kubernetes replaces the pods one by one. For the collector, the collector.maxUnavailable parameter sets how many pods can be unavailable during the update (default: 1).

4. Check that the new pods run.

   kubectl get pods

5. Check the revision history of the release. You need the revision number to roll back.

   helm history <release-name>

For details on the chart, see Install AxoSyslog with Helm.

Update the configuration version

The @version: line of the configuration file declares which version of the configuration syntax and default behavior you use. For example:

@version: 4.28
@include "scl.conf"

The @version: line must be the first line of the main configuration file, before any @include statement. If the configuration contains more than one @version: line, AxoSyslog uses only the first one. For details, see The configuration syntax in detail.

AxoSyslog handles the declared version as follows:

• If you set @version: current, AxoSyslog uses the version of the installed binary. This is convenient, but every upgrade can change the behavior of your configuration, without a change in the configuration file.
• If the declared version is older than the version in the Config version: line of syslog-ng --version, AxoSyslog runs in compatibility mode. It keeps the old default behavior, and logs the Configuration file format is too old, syslog-ng is running in compatibility mode warning. It also logs a warning for each version-dependent default that your configuration uses.
• If the declared version is newer than the version of the binary, AxoSyslog logs a warning, and runs with the newest version that it supports.

To update the configuration version, complete the following steps.

1. Upgrade the binary first. Keep the old @version: line for now.

2. Check the configuration, and read the warnings.

   sudo syslog-ng --syntax-only

   You can also find the warnings in the log of AxoSyslog after a restart.

3. Resolve every warning about incompatible changes. For each warning, do one of these: set the option explicitly to keep the old behavior, or accept the new default behavior.

4. Change the @version: line to the new version, for example:

   @version: 4.28

5. Check the configuration again.

   sudo syslog-ng --syntax-only

6. Reload the configuration.

   sudo syslog-ng-ctl reload

   Alternatively, restart the service: sudo systemctl restart syslog-ng.

Roll back an AxoSyslog upgrade

If the new version doesn’t work as you expect, go back to the version that you wrote down in Before you upgrade AxoSyslog.

If you changed the @version: line of the configuration, restore the configuration from your backup. An older binary can’t use a newer configuration version. It uses its own newest version instead, so the behavior can change.

Roll back the packages

• Debian and Ubuntu:

  1. List the available versions of the package.

     apt-cache policy axosyslog

     You can also run apt list -a axosyslog.

  2. Install the previous version. Install the same version of every module package that you use. Replace <package-version> with a version from the output of the previous step. For example:

     sudo apt install --allow-downgrades axosyslog=<package-version> axosyslog-core=<package-version> axosyslog-mod-grpc=<package-version>

• RHEL, Fedora, and AlmaLinux:

  • To go back to the previous available version, run:

    sudo dnf downgrade 'axosyslog*'

  • To install a specific version:

    1. List the installed AxoSyslog packages.

       dnf list --installed 'axosyslog*'

    2. Install the previous version of every package from the list. Replace <version> with the version to roll back to, for example:

       sudo dnf install axosyslog-<version> axosyslog-grpc-<version>

  • To undo the upgrade transaction, find its ID with dnf history, then run:

    sudo dnf history undo <transaction-id>

After the downgrade, restart the service, and check the version:

sudo systemctl restart syslog-ng
syslog-ng --version

Roll back containers

Start the container again with the previous image tag. Use the same options and volume mounts as for the new container. For Podman with systemd, set the previous tag in the AXOSYSLOG_IMAGE variable, then run sudo systemctl daemon-reload and sudo systemctl restart axosyslog.

If you used the latest tag before the upgrade, latest now points to the new release. Use the version-number tag of the old version, for example, ghcr.io/axoflow/axosyslog:<old-version>. You wrote down this version in Before you upgrade AxoSyslog.

Roll back the Helm chart

1. List the revisions of the release.

   helm history <release-name>

2. Roll back to the revision before the upgrade.

   helm rollback <release-name> <revision>

Get help with an upgrade

If AxoSyslog doesn’t start after an upgrade or a rollback, keep the backup of /etc/syslog-ng/ and /var/lib/syslog-ng/, and contact us.