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

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 on server hosts 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. Some of these, like specific sources and destinations require additional packages that you need only if you’re actually using the specific destination. Therefore, AxoSyslog has a number of modules that you can install as a separate package if you need the particular feature. 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.

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
   

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 x86-64 distributions are supported:

• Red Hat Enterprise Linux (RHEL) 9 / AlmaLinux 9
• Red Hat Enterprise Linux (RHEL) 8 / AlmaLinux 8
• Fedora 41
• Fedora 40
• Fedora 39

(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. Some of these, like specific sources and destinations require additional packages that you need only if you’re actually using the specific destination. Therefore, AxoSyslog has a number of modules that you can install as a separate package if you need the particular feature. 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.

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:

     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:

     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 Helm charts for syslog-ng. You can use these charts to install cloud-ready syslog-ng images created and maintained by Axoflow.

Prerequisites

You must have Helm 3.0 or newer installed to use these charts. Refer to the official Helm documentation for details.

Syslog collector and syslog server use cases

The chart provides parameters that make it easy to deploy AxoSyslog for the following use cases:

• As a collector, to collect local logs using the kubernetes() source, and forward them to another syslog server, to an opensearch() node, or to another AxoSyslog node.
• As a syslog server:
  • to receive RFC3164 and RFC5424 formatted syslog messages from any sender, or syslog-ng-otlp messages from another AxoSyslog node, and then
  • store them locally, or forward them to remote destinations.

These two use cases are independent from each other and can be configured separately. For other use cases, for example, to use other sources and destinations, you can use the config.raw parameter of the collector or the server. For the list of configurable parameters and their default values, see Parameters of the AxoSyslog Helm chart.

Install

To install the axosyslog chart, complete the following steps.

1. Clone the chart repository.

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

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

   • A collector that act as a syslog collector, and
   • a syslog server.

   If need only one of these pods, you can disable it with the collector.enabled or the syslog.enabled parameter, respectively. For the list of configurable parameters and their default values, see Parameters of the AxoSyslog Helm chart. If you want to use disk-buffers, see also 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 syslog.enabled=false
     

   • Install only the syslog server:

     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 container start.
     $ kubectl get pods --namespace=default -l app=axosyslog-1713953907 -w
   

3. Check that the pods are running.

   kubectl get pods
   

   The output should list the pods that are running: two for the default settings, or one if you have disabled the collector or the syslog pod.

   NAME                                   READY   STATUS    RESTARTS   AGE
   axosyslog-1713953907-collector-ddftq   1/1     Running   0          57s
   axosyslog-1713953907-syslog-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 will override the default configuration settings of the chart.

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

      helm upgrade <name-of-your-axosyslog-deployment> axosyslog/axosyslog -f my-values.yaml
      

      The output should be similar to:

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

      Tip: You can retrieve the non-default values of a deployment by running helm get values <name-of-your-axosyslog-deployment>

5. For the collector use case, configure the destination where the logs are forwarded. For example, the following values file sends the logs in JSON format to the localhost:514 address via TCP:

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

   For details and other parameters, see Collector parameters.

6. For the syslog server use case, you can send test messages from the pods, for example:

   • From the syslog server pod:

     kubectl exec axosyslog-1714389625-syslog-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
     

   The generated log messages (like 2024-05-02T10:56:31.000000+00:00 localhost prg00000[1234]: seq: 0000000065, thread: 0000, runid: 1714647391, stamp: 2024-05-02T10:56:31 PADDPADDPADDPADD) should show up in the configured destinations, for example, in the file destination:

   kubectl exec axosyslog-1714389625-syslog-0 -- less /var/log/syslog
   

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.

Uninstall

Tip: List all installed releases using helm list.

To uninstall a chart release, run:

helm delete <name-of-the-release-to-delete>

4.1 - Parameters of the AxoSyslog Helm chart

The following table lists the configurable parameters of the AxoSyslog collector chart and their default values. For details on installing the chart, see Install AxoSyslog with Helm.

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.10.0
      @include "scl.conf"

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

        destination {
          logscale(
            token("your-secret-humio-ingest-token")
          );
        };

        flags(flow-control);
      };

  hostNetworking: true

Syslog destination

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

For example:

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

OpenSearch destination

Send logs to OpenSearch over HTTP or HTTPS.

For example:

collector:
  config:
    destinations:
      opensearch:
        - address: 10.104.232.94
          index: "test-axoflow-index"
          tls:
            CAFile: "/path/to/CAFile.pem"
            CADir: "/path/to/CADir/"
            Cert: "/path/to/Cert.pem"
            Key: "/path/to/Key.pem"
            peerVerify: true
            template: "$(format-json .*)"

syslogNgOtlp destination

Send logs over to another AxoSyslog node using the syslog-ng-otlp() destination driver.

Other collector parameters

Syslog server parameters

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

Syslog source

You can use the syslog source to receive RFC3164 or RFC5424 formatted syslog messages on the following ports:

• 1514: RFC3164-formatted traffic over TCP and UDP (NodePort 30514)
• 1601: RFC5424-formatted traffic over TCP (NodePort 30601)
• 6514: RFC5424-formatted traffic over TLS (NodePort 30614)

If needed, you can open additional ports using the service.extraPorts option.

syslogNgOtlp source

Initializes a syslog-ng-otlp() to receive messages from another AxoSyslog node that sends telemetry data using the syslog-ng-otlp() destination driver.

File destination

To write the collected logs into files, configure the syslog.logFileStorage and the syslog.config.destinations.file options.

For example:

syslog:
  enabled: true
  logFileStorage:
    enabled: true
    storageClass: standard
    size: 500Gi
  bufferStorage:
    enabled: false
    storageClass: standard
    size: 10Gi
  config:
    sources:
      syslog:
        enabled: true
    destinations:
      file:
        enabled: true
        path: "/var/log/$HOST/syslog"
        extraOptionsRaw: "create-dirs(yes)"

OpenSearch destination

Send logs to OpenSearch over HTTP or HTTPS.

For example:

syslog:
  enabled: true
  bufferStorage:
    enabled: true
    storageClass: standard
    size: 10Gi
  config:
    sources:
      syslog:
        enabled: true
    destinations:
      opensearch:
        enabled: true
        url: http://my-release-opensearch.default.svc.cluster.local:9200
        index: "test-axoflow-index"
        user: "admin"
        password: "admin"
        #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)"

Syslog destination

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

For example:

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

syslogNgOtlp destination

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

For example:

syslog:
  enabled: true
  bufferStorage:
    enabled: true
    storageClass: standard
    size: 10Gi
  config:
    sources:
      syslog:
        enabled: true
    destinations:
      syslogNgOtlp:
        enabled: true
        url: "192.168.77.133:4317"
        extraOptionsRaw: "time-reopen(1) batch-timeout(1000) batch-lines(1000)"

Generic chart parameters

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

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