---
title: "Upgrade AxoSyslog to a newer version"
url: "https://axoflow.com/docs/axosyslog-core/install/upgrade-axosyslog/"
description: "Upgrade an existing AxoSyslog installation from packages, container images, or the Helm chart, update the configuration version, and roll back if needed."
last_modified: "2026-10-02T12:51:48+02:00"
---

> For the complete documentation index, see [llms.txt](https://axoflow.com/docs/axosyslog-core/llms.txt).

# Upgrade AxoSyslog to a newer version

Upgrade an existing AxoSyslog installation from packages, container images, or the Helm chart, update the configuration version, and roll back if needed.

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](https://axoflow.com/docs/axosyslog-core/install/upgrade-syslog-ng/index.md) 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](https://axoflow.com/docs/axosyslog-core/install/upgrade-axosyslog/index.md#config-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.

   ```shell
   syslog-ng --version
   ```

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

   ```text
   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](https://axoflow.com/docs/axosyslog-core/whats-new/index.md), look for deprecated options and for **Breaking change** subsections (for example, in Version 4.16).
   - The [AxoSyslog release notes on GitHub](https://github.com/axoflow/axosyslog/releases) 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:

   ```shell
   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](https://axoflow.com/docs/axosyslog-core/install/podman-systemd/index.md) 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.

        ```shell
        sudo apt update
        ```
     2. Upgrade every installed AxoSyslog package.

        ```shell
        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.

        ```shell
        sudo dnf update
        ```
     2. Upgrade every installed AxoSyslog package.

        ```shell
        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.

   ```shell
   sudo systemctl restart syslog-ng
   ```
3. Check that the service runs.

   ```shell
   sudo systemctl status syslog-ng
   ```

   Make sure that the `Active:` line of the output shows `active (running)`.
4. Check the version of the binary.

   ```shell
   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:

   ```shell
   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](https://axoflow.com/docs/axosyslog-core/install/upgrade-axosyslog/index.md#config-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](https://github.com/axoflow/axosyslog-docker/pkgs/container/axosyslog).

### 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`.

   ```shell
   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:

   ```shell
   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.

   ```shell
   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:

   ```shell
   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](https://axoflow.com/docs/axosyslog-core/install/docker/index.md) and [Install AxoSyslog with Podman](https://axoflow.com/docs/axosyslog-core/install/podman/index.md).
5. Check the logs of the new container.

   ```shell
   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:

```systemd
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:

     ```systemd
     [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.

     ```shell
     sudo podman pull ghcr.io/axoflow/axosyslog:latest
     ```
2. Reload the systemd configuration, and restart the service.

   ```shell
   sudo systemctl daemon-reload
   sudo systemctl restart axosyslog
   ```
3. Check the log of the service.

   ```shell
   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](https://axoflow.com/docs/axosyslog-core/install/podman-systemd/index.md).

## 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](https://axoflow.com/docs/axosyslog-core/install/helm/helm-chart-parameters/index.md).

**CAUTION:**

If you don’t set the `collector.config.raw` or `aggregator.config.raw` parameters, the chart generates the configuration file. The generated `@version:` is the major and minor version of the `appVersion` of the chart. A chart upgrade therefore changes the configuration version, and turns on the new default behavior of that release. Read [What’s new](https://axoflow.com/docs/axosyslog-core/whats-new/index.md) before you upgrade the chart.

If you use `config.raw`, you control the `@version:` line of the configuration. The chart doesn’t change it.

1. Update the chart repository.

   ```shell
   helm repo update
   ```
2. List the available chart versions. The `APP VERSION` column shows the AxoSyslog version of each chart version.

   ```shell
   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.

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

   The output should be similar to:

   ```text
   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.

   ```shell
   kubectl get pods
   ```
5. Check the revision history of the release. You need the revision number to roll back.

   ```shell
   helm history <release-name>
   ```

For details on the chart, see [Install AxoSyslog with Helm](https://axoflow.com/docs/axosyslog-core/install/helm/index.md).

## 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:

```shell
@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](https://axoflow.com/docs/axosyslog-core/chapter-configuration-file/configuration-syntax/index.md).

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.

   ```shell
   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:

   ```shell
   @version: 4.28
   ```
5. Check the configuration again.

   ```shell
   sudo syslog-ng --syntax-only
   ```
6. Reload the configuration.

   ```shell
   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](https://axoflow.com/docs/axosyslog-core/install/upgrade-axosyslog/index.md#before).

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.

     ```shell
     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:

     ```shell
     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:

    ```shell
    sudo dnf downgrade 'axosyslog*'
    ```
  - To install a specific version:

    1. List the installed AxoSyslog packages.

       ```shell
       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:

       ```shell
       sudo dnf install axosyslog-<version> axosyslog-grpc-<version>
       ```
  - To undo the upgrade transaction, find its ID with `dnf history`, then run:

    ```shell
    sudo dnf history undo <transaction-id>
    ```

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

```shell
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](https://axoflow.com/docs/axosyslog-core/install/upgrade-axosyslog/index.md#before).

### Roll back the Helm chart

1. List the revisions of the release.

   ```shell
   helm history <release-name>
   ```
2. Roll back to the revision before the upgrade.

   ```shell
   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](https://axoflow.com/docs/axosyslog-core/support/index.md).

Last modified October 2, 2026: [Adds an upgrade axosyslog page (7fbe98d3)](https://github.com/axoflow/axosyslog-core-docs/commit/7fbe98d3405a8ccc30ac1cfda341edcd3b3ace77)