This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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