Install AxoSyslog

• 1: Install AxoSyslog with Podman and systemd
• 2: Install AxoSyslog on Debian/Ubuntu
• 3: Install AxoSyslog on RHEL/Fedora/AlmaLinux
• 4: Install AxoSyslog with Helm
• 4.1: Parameters of the AxoSyslog Helm chart
• 5: Install AxoSyslog with Podman
• 6: Install AxoSyslog with Docker
• 7: AxoSyslog on macOS
• 8: Upgrade AxoSyslog to a newer version
• 9: Upgrade syslog-ng to AxoSyslog
• 10: Forward Windows logs

1 - Install AxoSyslog with Podman and systemd

This page shows you how to run AxoSyslog as a systemd service using podman.

AxoSyslog provides cloud-ready images. These images differ from the upstream syslog-ng images, because:

• They’re based on Alpine Linux, instead of Debian testing for reliability and smaller size (thus smaller attack surface).
• They incorporate cloud-native features and settings, such as the Kubernetes source.
• They incorporate container-level optimizations for better performance and improved security. For example, they use an alternative malloc library.
• They support the ARM architecture.

The AxoSyslog images support the following architectures:

• amd64
• arm/v7
• arm64

Prerequisites

Podman version 4.6.1.

The steps in this procedure were tested on CentOS 9, but should work on other similar distributions as well.

Install AxoSyslog as a systemd service

1. Make sure that there is no axosyslog.service unit file on the system. Run the following commands:

   sudo rm /etc/systemd/system/axosyslog.service

   Expected output:

   rm: cannot remove '/etc/systemd/system/axosyslog.service': No such file or directory

   sudo systemctl cat axosyslog.service

   Expected output:

   No files found for axosyslog.service.

2. Create a systemd unit file called /etc/containers/systemd/axosyslog.container based on the following template:

   sudo curl -o /etc/containers/systemd/axosyslog.container https://axoflow.com/docs/axosyslog-core/install/podman-systemd/axosyslog.container

3. Edit the unit file as needed for your environment.

   We recommend using the default mount points:

   Purpose	On the host	In the container
   Disk-buffer and persist files	/var/lib/syslog-ng	/var/lib/syslog-ng
   syslog-ng configuration file	/opt/axosyslog/etc	/etc/syslog-ng
   Output log files	/opt/axosyslog/var/log	/var/log

4. (Optional) Create an override.conf file to set custom environment values. This can be useful if you don’t want to modify /etc/containers/systemd/axosyslog.container. Run:

   systemctl edit axosyslog

   Later you can edit this file by running the previous command again.

5. Create the /opt/axosyslog/etc/syslog-ng.conf configuration file based on the following template.

   sudo mkdir -p /opt/axosyslog/etc/ ; sudo curl -o /opt/axosyslog/etc/syslog-ng.conf https://axoflow.com/docs/axosyslog-core/install/podman-systemd/syslog-ng.conf

   With the following sample configuration file AxoSyslog collects the local system logs and logs received from the network into the /var/log/messages file.

   You can customize the configuration file according to your needs. For a few pointers, see Configuring AxoSyslog as a logserver and the rest of this guide.

6. Run the following commands to reload the systemd configuration and launch the axosyslog service. Though the systemctl commands are run as root, the container will run as the specified user if set appropriately in the unit file.

   sudo systemctl daemon-reload
   sudo systemctl stop axosyslog
   sudo systemctl start axosyslog

   If there aren’t any errors, these commands don’t have any output.

7. Run the following command to verify that the service was properly started:

   journalctl -b -u axosyslog | tail -100

   The output should be similar to:

   Feb 12 09:04:40 <your-hostname> systemd[1]: Starting AxoSyslog Container...
   Feb 12 09:04:40 <your-hostname> podman[2783]: 2024-02-12 09:04:40.454665314 -0500 EST m=+0.167732500 system refresh
   Feb 12 09:04:40 <your-hostname> axosyslog[2783]: Trying to pull ghcr.io/axoflow/axosyslog:latest...
   Feb 12 09:04:40 <your-hostname> axosyslog[2783]: Pulling image //ghcr.io/axoflow/axosyslog:latest inside systemd: setting pull timeout to 5m0s
   Feb 12 09:04:41 <your-hostname> axosyslog[2783]: Getting image source signatures
   Feb 12 09:04:41 <your-hostname> axosyslog[2783]: Copying blob sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1
   Feb 12 09:04:41 <your-hostname> axosyslog[2783]: Copying blob sha256:619be1103602d98e1963557998c954c892b3872986c27365e9f651f5bc27cab8
   Feb 12 09:04:41 <your-hostname> axosyslog[2783]: Copying blob sha256:b061f41886afb563aff2a5f731f3286ba54ea6f657ed3e282f5339a12a64c5ef
   Feb 12 09:04:41 <your-hostname> axosyslog[2783]: Copying blob sha256:1b8d965a650c6a05227bd5c549930c9898071e8e7abb26886d4169a99762de0a
   Feb 12 09:04:41 <your-hostname> axosyslog[2783]: Copying blob sha256:b5b0ce6ebef193c4f909379188cfb59443e8a1809816fbb476074908b170b4d1
   Feb 12 09:04:50 <your-hostname> axosyslog[2783]: Copying config sha256:c379d94ef2c5ec348dfb3a93eed9a19aed667c396008db85edc354c8f4f8cb6a
   Feb 12 09:04:50 <your-hostname> axosyslog[2783]: Writing manifest to image destination
   Feb 12 09:04:50 <your-hostname> podman[2783]: 2024-02-12 09:04:50.422390687 -0500 EST m=+10.135457863 container create 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f (image=ghcr.io/axoflow/axosyslog:latest, name=AxoSyslog, org.opencontainers.image.documentation=https://axoflow.com/docs/axosyslog/docs/, org.opencontainers.image.url=https://axoflow.io/, org.opencontainers.image.source=https://github.com/axoflow/axosyslog, org.opencontainers.image.authors=Axoflow, org.opencontainers.image.title=AxoSyslog, org.opencontainers.image.vendor=Axoflow, PODMAN_SYSTEMD_UNIT=axosyslog.service, org.opencontainers.image.description=A cloud-native distribution of syslog-ng by Axoflow, maintainer=axoflow.io, org.opencontainers.image.licenses=GPL-3.0-only)
   Feb 12 09:04:50 <your-hostname> podman[2783]: 2024-02-12 09:04:50.402626446 -0500 EST m=+10.115693622 image pull c379d94ef2c5ec348dfb3a93eed9a19aed667c396008db85edc354c8f4f8cb6a ghcr.io/axoflow/axosyslog:latest
   Feb 12 09:04:50 <your-hostname> podman[2783]: 2024-02-12 09:04:50.489925509 -0500 EST m=+10.202992695 container init 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f (image=ghcr.io/axoflow/axosyslog:latest, name=AxoSyslog, org.opencontainers.image.authors=Axoflow, org.opencontainers.image.licenses=GPL-3.0-only, org.opencontainers.image.vendor=Axoflow, maintainer=axoflow.io, PODMAN_SYSTEMD_UNIT=axosyslog.service, org.opencontainers.image.url=https://axoflow.io/, org.opencontainers.image.documentation=https://axoflow.com/docs/axosyslog/docs/, org.opencontainers.image.title=AxoSyslog, org.opencontainers.image.description=A cloud-native distribution of syslog-ng by Axoflow, org.opencontainers.image.source=https://github.com/axoflow/axosyslog)
   Feb 12 09:04:50 <your-hostname> systemd[1]: Started AxoSyslog Container.
   Feb 12 09:04:50 <your-hostname> podman[2783]: 2024-02-12 09:04:50.500050669 -0500 EST m=+10.213117845 container start 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f (image=ghcr.io/axoflow/axosyslog:latest, name=AxoSyslog, PODMAN_SYSTEMD_UNIT=axosyslog.service, org.opencontainers.image.source=https://github.com/axoflow/axosyslog, org.opencontainers.image.authors=Axoflow, org.opencontainers.image.description=A cloud-native distribution of syslog-ng by Axoflow, org.opencontainers.image.documentation=https://axoflow.com/docs/axosyslog/docs/, org.opencontainers.image.licenses=GPL-3.0-only, org.opencontainers.image.vendor=Axoflow, org.opencontainers.image.title=AxoSyslog, maintainer=axoflow.io, org.opencontainers.image.url=https://axoflow.io/)
   Feb 12 09:04:50 <your-hostname> axosyslog[2783]: 477c9f011684f767aae138a0f88602ff30a8c95a46d616bb3b95318ec3a4b79f
   Feb 12 09:04:50 <your-hostname> AxoSyslog[2821]: [2024-02-12T14:04:50.806054] syslog-ng starting up; version='4.6.0'

8. Send a test message to the service (requires nc to be installed):

   echo '<5> localhost test: this is a test message' | nc localhost 514

   Check that the test message has arrived into the log file:

   cat /opt/axosyslog/var/log/messages

   The output should be similar to:

   Feb 19 15:49:12 localhost test: this is a test message

Customize the configuration

To customize the configuration, edit the /opt/axosyslog/etc/syslog-ng.conf file on the host, then reload the service.

Managing the AxoSyslog systemd service

• You can reload syslog-ng running in the container via systemctl. The following command reloads the syslog-ng.conf file, without stopping/starting syslog-ng itself.

  sudo systemctl reload axosyslog

• You can access syslog-ng-ctl from the host, for example by running:

  podman exec -ti AxoSyslog syslog-ng-ctl show-license-info

  If you use syslog-ng-ctl regularly, you can create the /opt/axosyslog/bin/syslog-ng-ctl file with the following content, make it executable, and add it to your path. That way running syslog-ng-ctl <command> will execute the command in the AxoSyslog container.

  #!/bin/bash  
  
  podman exec -ti AxoSyslog syslog-ng-ctl "$@"  

• The traditional method of starting a service at boot (systemctl enable) is not supported for container services. To automatically start the AxoSyslog service, make sure that the following line is included in the unit file. (It is included in the sample template.)

  [Install]
  WantedBy=default.target

2 - Install AxoSyslog on Debian/Ubuntu

You can install AxoSyslog 4.8 and newer on your Debian-based system from Axoflow’s APT repository. AxoSyslog is a drop in replacement for the syslog-ng Debian package, all the AxoSyslog binaries and configuration files are stored at the same place on your system.

The following x86-64 distributions are supported:

Which package to install?

AxoSyslog supports many features, but you rarely need all of them on a single host. Sources and destinations that depend on external libraries live in separate modules, so you install only the ones you actually use. For example, the gRPC-based destinations (like loki() and opentelemetry()) come from the gRPC module, while HTTP-based destinations (like elasticsearch-http() and sumologic-http()) come from the HTTP module.

The Prerequisites section of every source, destination, and parser names the module it needs.

If a module isn’t installed, AxoSyslog doesn’t start, and reports a syntax error that points at the name of the driver you configured. For details, see Error: unexpected LL_IDENTIFIER.

The following table lists the AxoSyslog modules, the configuration objects each provides, and the package to install.

The axosyslog metapackage installs axosyslog-core, axosyslog-scl, and recommends every optional module, so apt install axosyslog gives you a working setup with the common modules.

AxoSyslog supports the sun-streams(), darwin-oslog(), darwin-oslog-stream(), and openbsd() drivers only on Solaris, macOS, and OpenBSD respectively. The Debian/Ubuntu and RHEL packages don’t include them.

Usually, you install the base package axosyslog, and the packages of specific modules that you want to use. We also provide debuginfo packages for every module, but you only need these in certain troubleshooting scenarios.

Steps

To install AxoSyslog from the APT repository, complete the following steps.

1. Run the following commands to add the APT repository of your distribution (for example, Ubuntu 24.04) to the APT sources list:

   wget -qO - https://pkg.axoflow.io/axoflow-code-signing-pub.asc | gpg --dearmor > /usr/share/keyrings/axoflow-code-signing-pub.gpg

   echo "deb [signed-by=/usr/share/keyrings/axoflow-code-signing-pub.gpg] https://pkg.axoflow.io/apt stable ubuntu-noble" | tee --append /etc/apt/sources.list.d/axoflow.list

   apt update

   Note

   Nightly builds are also available:

   echo "deb [signed-by=/usr/share/keyrings/axoflow-code-signing-pub.gpg] https://pkg.axoflow.io/apt nightly ubuntu-noble" | tee --append /etc/apt/sources.list.d/axoflow.list

2. Install the AxoSyslog package.

   apt install axosyslog

Using AxoSyslog

After you’ve installed AxoSyslog, you can configure it just like syslog-ng, using the same configurations files (/etc/syslog-ng/syslog-ng.conf by default). For details, see the Quick-start guide.

Getting help

If you run into any issues while installing or configuring AxoSyslog, or you have any questions, you can find us on our Discord server.

3 - Install AxoSyslog on RHEL/Fedora/AlmaLinux

You can install AxoSyslog 4.8 and newer on your RPM-based system from Axoflow’s RPM repository. AxoSyslog is a drop in replacement for the syslog-ng RPM package, all the AxoSyslog binaries and configuration files are stored at the same place on your system.

The following distributions are supported:

• Red Hat Enterprise Linux (RHEL) 10 x86-64 / AlmaLinux 10 x86-64
• Red Hat Enterprise Linux (RHEL) 9 x86-64 / AlmaLinux 9 x86-64
• Red Hat Enterprise Linux (RHEL) 8 x86-64 / AlmaLinux 8 x86-64
• Fedora 44 x86-64

(The packages for AlmaLinux probably work for Rocky Linux as well, but we haven’t tested it.)

Which package to install?

AxoSyslog supports many features, but you rarely need all of them on a single host. Sources and destinations that depend on external libraries live in separate modules, so you install only the ones you actually use. For example, the gRPC-based destinations (like loki() and opentelemetry()) come from the gRPC module, while HTTP-based destinations (like elasticsearch-http() and sumologic-http()) come from the HTTP module.

The Prerequisites section of every source, destination, and parser names the module it needs.

If a module isn’t installed, AxoSyslog doesn’t start, and reports a syntax error that points at the name of the driver you configured. For details, see Error: unexpected LL_IDENTIFIER.

The following table lists the AxoSyslog modules, the configuration objects each provides, and the package to install.

Note that the RPM package names differ from the Debian package names: they don’t have the mod- part, and some of them use a different name (for example, the GeoIP2 module is axosyslog-geoip, and the Kafka module is axosyslog-kafka).

AxoSyslog supports the sun-streams(), darwin-oslog(), darwin-oslog-stream(), and openbsd() drivers only on Solaris, macOS, and OpenBSD respectively. The Debian/Ubuntu and RHEL packages don’t include them.

Usually, you install the base package axosyslog-<version-number>.<distro>.x86_64.rpm, and the packages of specific modules that you want to use. We also provide debuginfo packages for every module, but you only need these in certain troubleshooting scenarios.

Steps

To install AxoSyslog on RedHat Enterprise Linux 9 or AlmaLinux 9, complete the following steps. The instructions for AlmaLinux probably work for Rocky Linux 9 as well, but we haven’t tested it.

1. Run the following commands to enable the EPEL repositories for your distribution. This is needed to install some dependencies of AxoSyslog. (For RHEL 8 and compatible distributions, use these instructions.)

   • RHEL 9-10:

     sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
     sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

   • AlmaLinux 9-10:

     sudo dnf install epel-release
     sudo dnf config-manager --set-enabled crb

   • Fedora:

     sudo dnf install epel-release

2. Add the AxoSyslog repository of your distribution:

   • Distribution:
   • RHEL / AlmaLinux 9
   • RHEL / AlmaLinux 8
   • Fedora 41
   • Fedora 40
   • Fedora 39
   sudo tee /etc/yum.repos.d/axosyslog.repo <<< '[axosyslog]
   name=AxoSyslog
   baseurl=https://pkg.axoflow.io/rpm/stable/almalinux-9/$basearch
   enabled=1
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://pkg.axoflow.io/axoflow-code-signing-pub.asc' > /dev/null

   sudo tee /etc/yum.repos.d/axosyslog.repo <<< '[axosyslog]
   name=AxoSyslog
   baseurl=https://pkg.axoflow.io/rpm/stable/almalinux-8/$basearch
   enabled=1
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://pkg.axoflow.io/axoflow-code-signing-pub.asc' > /dev/null

   sudo tee /etc/yum.repos.d/axosyslog.repo <<< '[axosyslog]
   name=AxoSyslog
   baseurl=https://pkg.axoflow.io/rpm/stable/fedora-41/$basearch
   enabled=1
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://pkg.axoflow.io/axoflow-code-signing-pub.asc' > /dev/null

   sudo tee /etc/yum.repos.d/axosyslog.repo <<< '[axosyslog]
   name=AxoSyslog
   baseurl=https://pkg.axoflow.io/rpm/stable/fedora-40/$basearch
   enabled=1
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://pkg.axoflow.io/axoflow-code-signing-pub.asc' > /dev/null

   sudo tee /etc/yum.repos.d/axosyslog.repo <<< '[axosyslog]
   name=AxoSyslog
   baseurl=https://pkg.axoflow.io/rpm/stable/fedora-39/$basearch
   enabled=1
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://pkg.axoflow.io/axoflow-code-signing-pub.asc' > /dev/null

3. Update the packages list.

   sudo yum update -y

   Expected output:

   AxoSyslog                                                                                                           544  B/s | 488  B     00:00    
   AxoSyslog                                                                                                           5.2 kB/s | 3.2 kB     00:00    
   Importing GPG key 0x5F25E107:
   Userid     : "Axoflow Code Signing Key <support@axoflow.com>"
   Fingerprint: 365A 4340 FA76 89B4 78ED 617C 3605 FFAD 5F25 E107
   From       : https://pkg.axoflow.io/axoflow-code-signing-pub.asc
   AxoSyslog                                                                                                            68 kB/s |  56 kB     00:00    
   Extra Packages for Enterprise Linux 9 - x86_64                                                                      8.2 MB/s |  23 MB     00:02    
   Extra Packages for Enterprise Linux 9 openh264 (From Cisco) - x86_64                                                1.1 kB/s | 2.5 kB     00:02    
   Dependencies resolved.
   Nothing to do.
   Complete!

4. Install AxoSyslog.

   • To install AxoSyslog with every available module, run:

     sudo yum install axosyslog-*

   • To install only the base package, run:

     sudo yum install axosyslog

     Then install other packages for the modules you want to use as needed. For example, to use the gRPC-based destinations (like loki() or opentelemetry()), install the axosyslog-grpc-* package. For HTTP-based destinations like elasticsearch-http() or sumologic-http(), you need the axosyslog-http-* package.

5. Enable syslog-ng.

   sudo systemctl enable syslog-ng
   sudo systemctl start syslog-ng

6. (Optional) If you don’t want to run other log collectors on the host, you can delete the existing one (which is rsyslog by default):

   sudo yum remove rsyslog.x86_64

Using AxoSyslog

After you’ve installed AxoSyslog, you can configure it just like syslog-ng, using the same configurations files (/etc/syslog-ng/syslog-ng.conf by default). For details, see the Quick-start guide.

Getting help

If you run into any issues while installing or configuring AxoSyslog, or you have any questions, you can find us on our Discord server.

4 - Install AxoSyslog with Helm

AxoSyslog provides a Helm chart. You can use this chart to install cloud-ready syslog-ng images created and maintained by Axoflow.

Prerequisites for the Helm chart

To use this chart, you need:

• A Kubernetes cluster that runs Kubernetes 1.22 or newer.
• kubectl, configured to access your cluster.
• Helm 3.0 or newer. For details, see the official Helm documentation.

Collector and aggregator use cases

The chart has parameters for the following use cases:

• As a collector: The collector uses the kubernetes() source to collect the local logs. It sends the logs to the aggregator, to a syslog server, to an OpenSearch node, or to a different AxoSyslog node.
• As an aggregator: The aggregator receives RFC3164 and RFC5424 syslog messages from all senders, and axosyslog-otlp() messages from other AxoSyslog nodes. It stores the messages locally, or sends them to remote destinations.

By default, the collector sends the logs to the aggregator. You can configure and deploy the two components independently. To use other sources and destinations, use the config.raw parameter of the collector or the aggregator. For the list of parameters and their default values, see Parameters of the AxoSyslog Helm chart.

Install the Helm chart

To install the axosyslog chart, complete the following steps.

1. Add the chart repository.

   helm repo add axosyslog https://axoflow.github.io/axosyslog
   helm repo update

2. Install the chart. The default settings install the following into the default namespace:

   • A collector DaemonSet. It collects the pod logs on each node, and sends them to the aggregator.
   • An aggregator StatefulSet. It receives syslog and axosyslog-otlp() messages, and writes them to a file.

   To install only one component, disable the other component: set collector.enabled=false or aggregator.enabled=false. For the list of parameters and their default values, see Parameters of the AxoSyslog Helm chart. If you use disk-buffers, also read How to use disk-buffers in containers and Kubernetes.

   • Install with the default values:

     helm install --generate-name axosyslog/axosyslog

   • Install only the collector:

     helm install --generate-name axosyslog/axosyslog --set aggregator.enabled=false

   • Install only the aggregator:

     helm install --generate-name axosyslog/axosyslog --set collector.enabled=false

   The output should be similar to:

   NAME: axosyslog-1713953907
   LAST DEPLOYED: Wed Apr 24 12:18:28 2024
   NAMESPACE: default
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   NOTES:
   1. Watch the axosyslog-1713953907 containers start.
     $ kubectl get pods --namespace=default -l app.kubernetes.io/instance=axosyslog-1713953907,app.kubernetes.io/name=axosyslog -w

   The NAME field shows the name of the release. In the following commands, replace <release-name> with this name.

3. Check that the pods are running.

   kubectl get pods

   The output should list the pods that are running: a collector pod on every node and an aggregator pod for the default settings. For example, on a single-node cluster:

   NAME                                   READY   STATUS    RESTARTS   AGE
   axosyslog-1713953907-collector-ddftq   1/1     Running   0          57s
   axosyslog-1713953907-aggregator-0      1/1     Running   0          57s

4. Configure the settings of the pods for your use case.

   1. Create a file called my-values.yaml.

   2. Add the configuration needed for your use case. The settings in this file override the default configuration settings of the chart.

   3. Update your deployment using the my-values.yaml file by running:

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

      The output should be similar to:

      Release "axosyslog-1713953907" has been upgraded. Happy Helming!
      ...

      Tip To list the non-default values of a release, run helm get values <release-name>.

Send the collector logs to another destination

By default, the collector sends the logs in JSON format to the aggregator over TCP. To send the logs to a different destination, configure the destination in your values file, then run helm upgrade. For example, the following values file sends the logs in JSON format to the 192.0.2.10:514 address over TCP:

collector:
  config:
    destinations:
      syslog:
        enabled: true
        transport: tcp
        address: 192.0.2.10
        port: 514
        template: "$(format-json .*)"

For details and other parameters, see Collector parameters.

Send test messages to the aggregator

To make sure that the aggregator receives messages, send test messages from the aggregator pod.

1. Run loggen in the aggregator pod:

   kubectl exec <release-name>-aggregator-0 -- loggen -S 127.0.0.1 1514

   Expected output:

   count=9328, rate = 882.83 msg/sec
   count=9786, rate = 884.20 msg/sec
   count=9800, rate = 27.92 msg/sec
   average rate = 928.58 msg/sec, count=9800, time=10.5538, (average) msg size=256, bandwidth=232.14 kB/sec

2. Check the configured destinations for the generated messages. For example, with the default file destination:

   kubectl exec <release-name>-aggregator-0 -- tail -n 5 /var/log/syslog

   The generated messages look like this:

   2024-05-02T10:56:31.000000+00:00 localhost prg00000[1234]: seq: 0000000065, thread: 0000, runid: 1714647391, stamp: 2024-05-02T10:56:31 PADDPADDPADDPADD

How to use disk-buffers in containers and Kubernetes

When you are running AxoSyslog in a container or in Kubernetes, and you want to use disk-buffers, there are some additional things to configure.

• Make sure to mount the disk-buffer files and the persist file (by default, both are stored in /var/lib/syslog-ng) in a way they are not lost when the pod or container is restarted.
  • In Kubernetes, add a persistent volume to your pod and store the disk buffer files (/var/lib/syslog-ng) there.
  • In a container, mount the disk-buffer directory from the host, or store it on a local volume.
• Use a reliable disk-buffer only if your storage is fast enough. For example, a low-speed persistent volume in Kubernetes can cause a significant performance degradation for AxoSyslog.
• Use the latest available version of AxoSyslog, as many related improvements and performance improvements (for example, disk-buffer related metrics) are only supported in recent versions.

If you are using syslog-ng without disk-buffering configured, syslog-ng stores everything in memory, which results in great performance. If you enable disk-buffering, the performance decreases. Make sure to size your observability pipeline appropriately.

Upgrade the Helm chart

To upgrade the chart to a newer version, and to roll back an upgrade, see Upgrade the Helm chart.

Uninstall the Helm chart

To uninstall a release of the chart, run:

helm uninstall <release-name>

4.1 - Parameters of the AxoSyslog Helm chart

The following tables list the configurable parameters of the axosyslog Helm chart and their default values. For details on installing the chart, see Install AxoSyslog with Helm.

The chart has two components that you can enable or disable independently:

• The collector is a DaemonSet that runs on every node, collects the pod logs, and forwards them to a destination. By default, it forwards the logs to the aggregator.
• The aggregator is a StatefulSet that receives syslog and axosyslog-otlp() messages from the network (including the messages of the collector), and routes them to local or remote destinations.

Collector parameters

When you deploy AxoSyslog as a collector (which is a DaemonSet), it collects and forwards local logs to a destination. You can use the following parameters to configure the collector. The parameters for specific destinations are shown in subsequent sections.

The following example uses the collector.config.raw parameter to configure a custom destination:

collector:
  config:
    raw: |
      @version: 4.28.0
      @include "scl.conf"

      log {
        source {
          syslog(port(12345));
        };

        destination {
          logscale(
            token("<YOUR_INGEST_TOKEN>")
          );
        };

        flags(flow-control);
      };

  hostNetworking: true

Collector syslog destination

Send logs over the network, conforming to RFC3164 using the network() destination driver. By default, the collector uses this destination to send the logs to the aggregator in JSON format.

For example, to send the logs to a syslog server outside the cluster:

collector:
  config:
    destinations:
      syslog:
        enabled: true
        transport: tcp
        address: 192.0.2.10
        port: 514
        template: "$(format-json .*)"

Collector OpenSearch destination

Send logs to OpenSearch over HTTP or HTTPS.

For example:

collector:
  config:
    destinations:
      syslog:
        enabled: false
      opensearch:
        enabled: true
        url: http://my-release-opensearch.default.svc.cluster.local:9200
        index: "test-axoflow-index"
        tls:
          CAFile: "/path/to/CAFile.pem"
          Cert: "/path/to/Cert.pem"
          Key: "/path/to/Key.pem"
          peerVerify: true

Collector axosyslogOtlp destination

Send logs to another AxoSyslog node using the axosyslog-otlp() destination driver.

For example, to send the logs to the aggregator using axosyslog-otlp() instead of syslog:

collector:
  config:
    destinations:
      syslog:
        enabled: false
      axosyslogOtlp:
        enabled: true

Other collector parameters

Aggregator parameters

When you deploy AxoSyslog as an aggregator (which is a StatefulSet), it receives incoming data from the network and routes it to a local or remote destination. You can use the following parameters to configure the aggregator. The parameters for specific sources and destinations are shown in subsequent sections.

Aggregator syslog source

You can use the syslog source to receive RFC3164 or RFC5424 formatted syslog messages. The source uses the default-network-drivers() source driver. The following table shows the ports where the aggregator receives the messages:

The NodePorts are used only if service.type is NodePort or LoadBalancer. If needed, you can open additional ports using the service.extraPorts option.

Aggregator axosyslogOtlp source

Initializes an axosyslog-otlp() source to receive messages from another AxoSyslog node that sends telemetry data using the axosyslog-otlp() destination driver. The source receives the messages on port 4317 (container and service port).

Aggregator file destination

To write the received logs into files, configure the aggregator.logFileStorage and the aggregator.config.destinations.file options.

For example:

aggregator:
  enabled: true
  logFileStorage:
    enabled: true
    storageClass: standard
    size: 50Gi
  config:
    destinations:
      file:
        enabled: true
        path: "/var/log/$HOST/syslog"
        extraOptionsRaw: "create-dirs(yes)"

Aggregator OpenSearch destination

Send logs to OpenSearch over HTTP or HTTPS.

For example:

aggregator:
  enabled: true
  bufferStorage:
    enabled: true
    storageClass: standard
    size: 10Gi
  config:
    destinations:
      opensearch:
        enabled: true
        url: http://my-release-opensearch.default.svc.cluster.local:9200
        index: "test-axoflow-index"
        user: "<YOUR_USERNAME>"
        password: "<YOUR_PASSWORD>"
        #tls:
        #  CAFile: "/path/to/CAFile.pem"
        #  CADir: "/path/to/CADir/"
        #  Cert: "/path/to/Cert.pem"
        #  Key: "/path/to/Key.pem"
        #  peerVerify: false
        extraOptionsRaw: "time-reopen(10)"

Aggregator syslog destination

Send logs over the network, conforming to RFC3164 using the network() destination driver.

For example:

aggregator:
  enabled: true
  bufferStorage:
    enabled: true
    storageClass: standard
    size: 10Gi
  config:
    destinations:
      syslog:
        enabled: true
        transport: tcp
        address: 192.0.2.10
        port: 514
        # convert incoming data to JSON
        #template: "$(format-json .*)\n"
        # use standard syslog logfile
        #template: "$ISODATE $HOST $MSGHDR$MSG\n"
        extraOptionsRaw: "time-reopen(10)"

Aggregator axosyslogOtlp destination

Send data using the axosyslog-otlp() destination driver to another AxoSyslog node.

For example:

aggregator:
  enabled: true
  bufferStorage:
    enabled: true
    storageClass: standard
    size: 10Gi
  config:
    destinations:
      axosyslogOtlp:
        enabled: true
        url: "192.0.2.10:4317"
        extraOptionsRaw: "time-reopen(1) batch-timeout(1000) batch-lines(1000)"

Other aggregator parameters

Metrics parameters

You can deploy axosyslog-metrics-exporter as a sidecar container of the collector to expose the metrics of AxoSyslog in Prometheus format on port 9577. If you use the Prometheus Operator, you can also deploy a PodMonitor to scrape the metrics.

Generic chart parameters

The following parameters apply to both the collector and the aggregator. Where a component has its own parameter with the same name (for example, collector.resources or aggregator.resources), the component-level setting overrides the generic one.

5 - Install AxoSyslog with Podman

AxoSyslog provides cloud-ready images. These images differ from the upstream syslog-ng images, because:

• They’re based on Alpine Linux, instead of Debian testing for reliability and smaller size (thus smaller attack surface).
• They incorporate cloud-native features and settings, such as the Kubernetes source.
• They incorporate container-level optimizations for better performance and improved security. For example, they use an alternative malloc library.
• They support the ARM architecture.

The AxoSyslog images support the following architectures:

• amd64
• arm/v7
• arm64

Install the AxoSyslog images

You can find the list of tagged versions at https://github.com/axoflow/axosyslog-docker/pkgs/container/axosyslog.

To install the latest stable version, run:

podman pull ghcr.io/axoflow/axosyslog:latest

You can also use it as a base image in your Dockerfile:

FROM ghcr.io/axoflow/axosyslog:latest

If you want to test a development version, you can use the nightly builds:

podman pull ghcr.io/axoflow/axosyslog:nightly

Note: These named packages are automatically updated when a new package is released. To install a specific version, run podman pull ghcr.io/axoflow/axosyslog:<version-number>, for example:

podman pull ghcr.io/axoflow/axosyslog:4.28.0

Customize the configuration

The AxoSyslog container image stores the configuration file at /etc/syslog-ng/syslog-ng.conf. By default, AxoSyslog collects the local system logs and logs received from the network into the /var/log/messages and /var/log/messages-kv.log files using this configuration file from the syslog-ng repository.

To customize the configuration, create your own configuration file and override the file in the container image with it, for example:

podman run --rm --volume <path-to-your/syslog-ng.conf>:/etc/syslog-ng/syslog-ng.conf ghcr.io/axoflow/axosyslog:latest

How to use disk-buffers in containers and Kubernetes

When you are running AxoSyslog in a container or in Kubernetes, and you want to use disk-buffers, there are some additional things to configure.

• Make sure to mount the disk-buffer files and the persist file (by default, both are stored in /var/lib/syslog-ng) in a way they are not lost when the pod or container is restarted.
  • In Kubernetes, add a persistent volume to your pod and store the disk buffer files (/var/lib/syslog-ng) there.
  • In a container, mount the disk-buffer directory from the host, or store it on a local volume.
• Use a reliable disk-buffer only if your storage is fast enough. For example, a low-speed persistent volume in Kubernetes can cause a significant performance degradation for AxoSyslog.
• Use the latest available version of AxoSyslog, as many related improvements and performance improvements (for example, disk-buffer related metrics) are only supported in recent versions.

If you are using syslog-ng without disk-buffering configured, syslog-ng stores everything in memory, which results in great performance. If you enable disk-buffering, the performance decreases. Make sure to size your observability pipeline appropriately.

Expose port to receive incoming traffic

To receive incoming network in a container, you must expose the port from the container where you want to receive the traffic to the host that’s running the container. Typically, this is only needed if you are running AxoSyslog as a relay or a server/aggregator.

By default, the AxoSyslog container images expose the ports commonly used to receive syslog traffic:

• 514/udp, typically used for RFC3164 (BSD-syslog) formatted traffic.
• 601/tcp, typically used for RFC5424 (IETF-syslog) formatted traffic.
• 6514/tcp, typically used for RFC5424 (IETF-syslog) formatted traffic over TLS.

To expose a specific port, use the --expose option when starting the container. Make sure to include the IP address of the host to make the port externally accessible.

For example, if you are receiving OpenTelemetry messages using the opentelemetry() source, expose the 4317 port:

podman run --rm --expose 127.0.0.1:4317:4317/tcp --volume <path-to-your/syslog-ng.conf>:/etc/syslog-ng/syslog-ng.conf ghcr.io/axoflow/axosyslog:latest

Using AxoSyslog

After you’ve installed AxoSyslog, you can configure it just like syslog-ng, using the same configurations files (/etc/syslog-ng/syslog-ng.conf by default). For details, see the Quick-start guide.

Getting help

If you run into any issues while installing or configuring AxoSyslog, or you have any questions, you can find us on our Discord server.

6 - Install AxoSyslog with Docker

AxoSyslog provides cloud-ready images. These images differ from the upstream syslog-ng images, because:

• They’re based on Alpine Linux, instead of Debian testing for reliability and smaller size (thus smaller attack surface).
• They incorporate cloud-native features and settings, such as the Kubernetes source.
• They incorporate container-level optimizations for better performance and improved security. For example, they use an alternative malloc library.
• They support the ARM architecture.

The AxoSyslog images support the following architectures:

• amd64
• arm/v7
• arm64

Install the AxoSyslog images

You can find the list of tagged versions at https://github.com/axoflow/axosyslog-docker/pkgs/container/axosyslog.

To install the latest stable version, run:

docker pull ghcr.io/axoflow/axosyslog:latest

You can also use it as a base image in your Dockerfile:

FROM ghcr.io/axoflow/axosyslog:latest

If you want to test a development version, you can use the nightly builds:

docker pull ghcr.io/axoflow/axosyslog:nightly

Note: These named packages are automatically updated when a new package is released. To install a specific version, run docker pull ghcr.io/axoflow/axosyslog:<version-number>, for example:

docker pull ghcr.io/axoflow/axosyslog:4.28.0

Customize the configuration

The AxoSyslog container image stores the configuration file at /etc/syslog-ng/syslog-ng.conf. By default, AxoSyslog collects the local system logs and logs received from the network into the /var/log/messages and /var/log/messages-kv.log files using this configuration file from the syslog-ng repository.

To customize the configuration, create your own configuration file and override the file in the container image with it, for example:

docker run --rm --volume <path-to-your/syslog-ng.conf>:/etc/syslog-ng/syslog-ng.conf ghcr.io/axoflow/axosyslog:latest

How to use disk-buffers in containers and Kubernetes

When you are running AxoSyslog in a container or in Kubernetes, and you want to use disk-buffers, there are some additional things to configure.

• Make sure to mount the disk-buffer files and the persist file (by default, both are stored in /var/lib/syslog-ng) in a way they are not lost when the pod or container is restarted.
  • In Kubernetes, add a persistent volume to your pod and store the disk buffer files (/var/lib/syslog-ng) there.
  • In a container, mount the disk-buffer directory from the host, or store it on a local volume.
• Use a reliable disk-buffer only if your storage is fast enough. For example, a low-speed persistent volume in Kubernetes can cause a significant performance degradation for AxoSyslog.
• Use the latest available version of AxoSyslog, as many related improvements and performance improvements (for example, disk-buffer related metrics) are only supported in recent versions.

If you are using syslog-ng without disk-buffering configured, syslog-ng stores everything in memory, which results in great performance. If you enable disk-buffering, the performance decreases. Make sure to size your observability pipeline appropriately.

Expose port to receive incoming traffic

To receive incoming network in a container, you must expose the port from the container where you want to receive the traffic to the host that’s running the container. Typically, this is only needed if you are running AxoSyslog as a relay or a server/aggregator.

By default, the AxoSyslog container images expose the ports commonly used to receive syslog traffic:

• 514/udp, typically used for RFC3164 (BSD-syslog) formatted traffic.
• 601/tcp, typically used for RFC5424 (IETF-syslog) formatted traffic.
• 6514/tcp, typically used for RFC5424 (IETF-syslog) formatted traffic over TLS.

To expose a specific port, use the --expose option when starting the container. Make sure to include the IP address of the host to make the port externally accessible.

For example, if you are receiving OpenTelemetry messages using the opentelemetry() source, expose the 4317 port:

docker run --rm --expose 127.0.0.1:4317:4317/tcp --volume <path-to-your/syslog-ng.conf>:/etc/syslog-ng/syslog-ng.conf ghcr.io/axoflow/axosyslog:latest

Using AxoSyslog

After you’ve installed AxoSyslog, you can configure it just like syslog-ng, using the same configurations files (/etc/syslog-ng/syslog-ng.conf by default). For details, see the Quick-start guide.

Getting help

If you run into any issues while installing or configuring AxoSyslog, or you have any questions, you can find us on our Discord server.

7 - AxoSyslog on macOS

AxoSyslog has no official macOS package or Homebrew formula. For production use, run AxoSyslog on a Linux host or as a container. For details, see Install AxoSyslog and Install AxoSyslog with Docker.

To develop, test, or collect logs locally on a Mac, build AxoSyslog from source. The upstream CI builds and tests AxoSyslog on macOS 15 and the latest macOS GitHub runner.

Build from source

1. Install Homebrew, then clone the source code.

   git clone https://github.com/axoflow/axosyslog.git
   cd axosyslog

2. Install the build dependencies listed in the contrib/Brewfile.

   brew update
   brew bundle --file=contrib/Brewfile

3. Point the build to the Homebrew libraries and to the Homebrew version of bison.

   HOMEBREW_PREFIX="$(brew --prefix)"
   export PKG_CONFIG_PATH="${HOMEBREW_PREFIX}/opt/openssl@3/lib/pkgconfig:${HOMEBREW_PREFIX}/opt/net-snmp/lib/pkgconfig:${HOMEBREW_PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH}"
   export PATH="${HOMEBREW_PREFIX}/opt/bison/bin:${PATH}"
   export CFLAGS="-I${HOMEBREW_PREFIX}/include"
   export LDFLAGS="-L${HOMEBREW_PREFIX}/lib"

4. Configure, build, and install AxoSyslog. Replace <install-dir> with the directory to install to. You can use either autotools or CMake.

   • With autotools:

     ./autogen.sh
     ./configure --prefix=<install-dir> \
       --with-ivykis=system --with-python=3 --with-systemd-journal=no \
       --disable-smtp --disable-java --disable-java-modules \
       --disable-pacct --disable-stackdump --disable-jit
     make
     make install

   • With CMake:

     cmake --install-prefix <install-dir> -B build . \
       -DIVYKIS_SOURCE=system -DPYTHON_VERSION=3 -DENABLE_JOURNALD=OFF \
       -DENABLE_AFSMTP=OFF -DENABLE_GRPC=OFF -DENABLE_JAVA=OFF \
       -DENABLE_JAVA_MODULES=OFF -DENABLE_PACCT=OFF -DENABLE_LIBUNWIND=OFF
     cmake --build build --target install

Limitations

The macOS builds disable the following modules:

• the systemd-journal() source
• the smtp() destination
• Java and the Java-based modules
• the pacct() source
• stack dumps on crash (--disable-stackdump)

The CMake build also disables the gRPC-based modules, for example, opentelemetry(), loki(), and bigquery(). On macOS 14, an incompatibility between Apache Arrow and Apple clang (apache/arrow#49841) breaks the arrow-flight module. Disable it with --disable-arrow-flight (autotools) or -DENABLE_ARROW_FLIGHT=OFF (CMake).

Collect macOS system logs

macOS has its own logging system. To collect its logs, use the darwin-oslog() and darwin-oslog-stream() sources. For details, see Collect native macOS system logs.

Run as a service

The source tree includes a sample launchd property list at contrib/com.syslog-ng.syslog-ng.plist. Adjust the paths to match your <install-dir> before you use it.

8 - 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.

9 - Upgrade syslog-ng to AxoSyslog

If you’re already using syslog-ng, you can upgrade your existing syslog-ng deployments to AxoSyslog in a matter of minutes, by simply installing AxoSyslog on the host.

If you already run AxoSyslog and want to upgrade it to a newer version, see Upgrade AxoSyslog to a newer version.

We assume that you’ve installed syslog-ng from the repositories of your distribution. To upgrade to AxoSyslog, complete the following steps.

1. Check that the syslog-ng service is running:

   sudo systemctl status syslog-ng

   The output will look something like:

   syslog-ng.service - System Logger Daemon
    Loaded: loaded (/usr/lib/systemd/system/syslog-ng.service; enabled; preset>
    Active: active (running) since Thu 2025-02-27 17:04:28 CET; 11s ago
      Docs: man:syslog-ng(8)
   Main PID: 254 (syslog-ng)
     Tasks: 2 (limit: 9594)
    Memory: 19.6M (peak: 20.8M)
       CPU: 215ms
    CGroup: /system.slice/syslog-ng.service
            └─254 "[rosetta]" /usr/sbin/syslog-ng /usr/sbin/syslog-ng -F

2. Check the version of syslog-ng you have by running:

   syslog-ng --version

   The output will start with something like:

   syslog-ng 4 (4.8.1)
   Config version: 4.2
   Installer-Version: 4.8.1

3. Add the AxoSyslog repository for your distribution and install AxoSyslog. For details, see the installation sections:

   • Install AxoSyslog on Debian/Ubuntu
   • Install AxoSyslog on RHEL/Fedora/AlmaLinux

   The installation replaces the syslog-ng packages with AxoSyslog packages, but provides the same binaries (for example, /usr/sbin/syslog-ng). It will keep using the existing configuration files (/etc/syslog-ng/syslog-ng.conf), certificates, and so on.

4. Check that the syslog-ng service is still running:

   sudo systemctl status syslog-ng

   The output should be identical to the earlier result:

   syslog-ng.service - System Logger Daemon
    Loaded: loaded (/usr/lib/systemd/system/syslog-ng.service; enabled; preset>
    Active: active (running) since Thu 2025-02-27 17:07:41 CET; 42s ago
      Docs: man:syslog-ng(8)
   Main PID: 1936 (syslog-ng)
     Tasks: 2 (limit: 9594)
    Memory: 79.9M (peak: 83.1M)
       CPU: 462ms
    CGroup: /system.slice/syslog-ng.service
            └─1936 "[rosetta]" /usr/sbin/syslog-ng /usr/sbin/syslog-ng -F

5. Check the version of syslog-ng you have by running:

   syslog-ng --version

   You’ll see that now you’re running AxoSyslog:

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

In case you run into any issues, contact us.

10 - Forward Windows logs

Axoflow provides a custom OpenTelemetry Collector distribution that you can use to collect logs on Windows hosts and forward them to AxoSyslog using the OpenTelemetry Protocol (OTLP/gRPC).

The distribution provides installers for AMD64 and ARM64 based Windows for:

• Windows Server 2025
• Windows Server 2022
• Windows Server 2019
• Windows 11

Steps

To forward Windows logs to AxoSyslog, complete the following steps.

1. Configure an opentelemetry() source on the AxoSyslog that will receive the Windows logs.

2. Download the installation package for your platform (https://github.com/axoflow/axoflow-otel-collector-releases/releases/) from the Assets section of the Axoflow OpenTelemetry Collector releases page. We provide MSI installers and binary releases for amd64 and arm64 architectures.

3. Run the installer on your Windows host. The installer installs:

   • the collector agent (by default) to C:\Program Files\Axoflow\OpenTelemetry Collector\axoflow-otel-collector.exe, and
   • a default configuration file (C:\ProgramData\Axoflow\OpenTelemetry Collector\config.yaml) that must be edited before use.

4. Open the configuration file (C:\ProgramData\Axoflow\OpenTelemetry Collector\config.yaml).

5. Set the IP address and port of the AxoSyslog host where you want to send data from this Windows host. Use the IP address and port of an opentelemetry() source. For example:

   exporters:
     otlp/axosyslog:
       endpoint: 10.0.2.2:4317
       tls:
         insecure: true

   Set the TLS settings to match the configuration of the AxoSyslog opentelemetry() source.

6. Configure receivers to collect logs of the Windows host, and the pipelines to forward them. For example, to collect event logs from the Application, System, and Security channels:

   receivers:
     windowseventlog/application:
       channel: application
       raw: true
       suppress_rendering_info: true
     windowseventlog/system:
       channel: system
       raw: true
       suppress_rendering_info: true
     windowseventlog/security:
         channel: security
         raw: true
         suppress_rendering_info: true
   service:
     pipelines:
       logs/eventlog:
         receivers: [windowseventlog/application, windowseventlog/system, windowseventlog/security]
         processors: [resource/agent, resourcedetection/system]
          exporters: [otlp/axosyslog]

   For details, see the Windows installation Readme and the OpenTelemetry Collector documentation.

7. Save the file.

8. Restart the service.

   Restart-Service axoflow-otel-collector

   The agent starts sending data to the configured AxoSyslog.