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

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

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 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 region. Change the default value if your organization uses another region. For more information, see Regions.

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