Send data from syslog to Axiom

This page explains how to send data from a syslog logging system to Axiom.

The Axiom Syslog Proxy acts as a syslog server to send data to Axiom.

The Axiom Syslog Proxy is an open-source project and welcomes your contributions. For more information, see the GitHub repository.

Syslog limitations and recommended alternatives

Syslog is an outdated protocol from the 1980s. Some of the limitations are the following:

• Lack of error reporting and feedback mechanisms when issues occur.
• Inability to gracefully terminate the connection. This can result in missing data.

For a more reliable and modern logging experience, consider using tools like Vector to receive syslog messages and forward them to Axiom. This approach bypasses many of syslog’s limitations.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to update the dataset you have created.

Other requirements:

• Message size limit: Axiom currently enforces a 64KB per-message size limit. This is in line with RFC5425 guidelines. Any message exceeding the limit causes the connection to close because Axiom doesn’t support ingesting truncated messages.
• TLS requirement: Axiom only supports syslog over TLS, specifically following RFC5425. Configure your syslog client accordingly.
• Port requirements: UDP log messages are sent on UDP port 514 to the Syslog server. TCP log messages are sent on TCP port 601 to the Syslog server.

Ensure your messages conform to the size limit and TLS requirements. If the connection is frequently re-established and messages are rejected, the issue can be the size of the messages or other formatting issues.

Install Axiom Syslog Proxy

To install the Axiom Syslog Proxy, choose one of the following options:

• Install using a pre-compiled binary file
• Install using Homebrew
• Install using Go command
• Install from the GitHub source
• Install using a Docker image

Install using pre-compiled binary file

To install the Axiom Syslog Proxy using a pre-compiled binary file, download one of the releases in GitHub.

Install using Homebrew

Run the following to install the Axiom Syslog Proxy using Homebrew:

brew tap axiomhq/tap
brew install axiom-syslog-proxy

Install using Go command

Run the following to install the Axiom Syslog Proxy using go get:

go get -u github.com/axiomhq/axiom-syslog-proxy/cmd/axiom-syslog-proxy

Install from GitHub source

Run the following to install the Axiom Syslog Proxy from the GitHub source:

git clone https://github.com/axiomhq/axiom-syslog-proxy.git
cd axiom-syslog-proxy
make install

Install using Docker image

To install the Axiom Syslog Proxy using a Docker image, use a Docker image from DockerHub

Configure Axiom Syslog Proxy

Set the following environment variables to connect to Axiom:

• AXIOM_TOKEN is the Axiom API token you have generated.
• AXIOM_DATASET is the name of the Axiom dataset where you want to send data.

Run Axiom Syslog Proxy

To run Axiom Syslog Proxy, run the following in your terminal.

./axiom-syslog-proxy

If you use Docker, run the following:

docker run -p601:601/tcp -p514:514/udp  \
  -e=AXIOM_TOKEN=API_TOKEN     \
  -e=AXIOM_DATASET=DATASET_NAME \
  axiomhq/axiom-syslog-proxy

• Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.
• Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

Test configuration

To test that the Axiom Syslog Proxy configuration:

1. Run the following in your terminal to send two messages:

   echo -n "tcp message" | nc -w1 localhost 601
   echo -n "udp message" | nc -u -w1 localhost 514
   

2. In Axiom, click the Stream tab.

3. Click your dataset.

4. Check whether Axiom displays the messages you have sent.