Send data from syslog to Axiom

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

Syslog limitations and recommended alternatives

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

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

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to ingest data to 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 install github.com/axiomhq/axiom-syslog-proxy/cmd/axiom-syslog-proxy@latest

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.
• Optional: AXIOM_URL is the URL of the Axiom API. By default, it uses the US East 1 (AWS) edge deployment. Change the default value if your organization uses another edge deployment. For more information, see Edge deployments.

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

Test configuration

To test that the Axiom Syslog Proxy configuration:

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

   shell

   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.