CL Agent

If you run your own servers and want to send all logs from these servers to central logging you can use our central logging agent with binary name clagent. CL agent will periodically send all system logs upstream to your central logging instance.

On Linux it exports logs from systemd using the journalctl cli.

On OpenBSD it exports logs using syslogd.

Download CL Agent

• clagent-linux-amd64
• clagent-linux-arm
• clagent-openbsd-amd64

Or grab it with wget

Click Copy, paste into your shell, and run:

Config

Config is done by creating a file clagent.toml It can be in either /etc/clagent.toml or in the same path as the clagent binary. /etc/clagent.toml takes precedence.

Example clagent.toml:

URL = "https://my-centrallogging-instance.com/your-log-source-token"

You can test it out by just copying it to your server and running: ./clagent.

Install as a Service

Linux

You can install as a service on linux with:

sudo ./clagent-arm -install
sudo systemctl enable clagent
sudo systemctl start clagent

OpenBSD

Create /etc/clagent.toml:

URL = "https://my-centrallogging-instance.com"

Modify /etc/syslog.conf

Add line:

*.*                                                     |/your/path/to/clagent

*.* means send all logs, the | means pipe output to another program (clagent)

Restart syslogd for changes to take effect:

doas /etc/rc.d/syslogd restart

What happens when the server is unreachable

The agent remembers its place in the journal with a cursor, and that cursor only moves once your Central Logging instance has accepted the entries. If a send fails — the server is restarting, the network drops, a request times out — the cursor stays where it was and the same entries go out on the next pass. Nothing is skipped.

Passes happen every 30 seconds. A backlog is sent in batches of about a megabyte each, one after another, until the agent has caught up.

The cursor lives in /var/lib/clagent/clagent-cursor.txt. If the agent cannot write there it falls back to $XDG_STATE_HOME/clagent, then to your home directory, then to /tmp. The path it settled on is logged at startup:

journal cursor file is /var/lib/clagent/clagent-cursor.txt

Earlier releases kept the cursor in /tmp, which many distributions clear on reboot — a cleared cursor made the agent resume from the newest entry and skip whatever arrived while it was down. On first start the agent moves an existing /tmp/clagent-cursor.txt to the new location for you.

Two things worth knowing. A send that reaches the server but whose reply is lost will be retried, so an entry can arrive twice; the agent errs towards a duplicate over a hole. And the agent only tracks the journal — if the machine is off, or the agent is not running, systemd keeps writing to the local journal and the agent picks up from the cursor when it starts again.

If a send keeps failing, the reason is in the agent’s own log:

journalctl -u clagent -n 20

invalid user token means the URL in clagent.toml has the wrong log source token. Connection refused means the agent cannot reach the instance at all.

Updating the Agent

./clagent -update then restart service if running on Linux sudo service clagent restart

Install with Ansible script

---
- name: Install and configure clagent
  hosts: your_hosts_group    # <-- change this
  become: true

  vars:
    clagent_download_url: "https://downloads.eligian.com/clagent-linux-amd64.tar.gz"
    clagent_install_dir: "/opt/clagent"
    clagent_binary_path: "/opt/clagent/clagent"
    clagent_config_path: "/etc/clagent.toml"
    clagent_url: "https://my-centrallogging-instance.com/your-log-source-token"

  tasks:
    - name: Ensure clagent install directory exists
      file:
        path: "{{ clagent_install_dir }}"
        state: directory
        owner: root
        group: root
        mode: "0755"

    - name: Download clagent archive
      get_url:
        url: "{{ clagent_download_url }}"
        dest: "/tmp/clagent-linux-amd64.tar.gz"
        mode: "0644"

    - name: Extract clagent binary
      unarchive:
        src: "/tmp/clagent-linux-amd64.tar.gz"
        dest: "{{ clagent_install_dir }}"
        remote_src: true

    - name: Rename extracted binary to clagent
      command: mv {{ clagent_install_dir }}/clagent-linux-amd64 {{ clagent_binary_path }}
      args:
        creates: "{{ clagent_binary_path }}"

    - name: Ensure clagent binary is executable
      file:
        path: "{{ clagent_binary_path }}"
        owner: root
        group: root
        mode: "0755"
        state: file

    - name: Write clagent config
      copy:
        dest: "{{ clagent_config_path }}"
        content: |
          URL = "{{ clagent_url }}"          
        owner: root
        group: root
        mode: "0644"
      notify: Restart clagent

    - name: Create systemd service unit for clagent
      copy:
        dest: /etc/systemd/system/clagent.service
        owner: root
        group: root
        mode: "0644"
        content: |
          [Unit]
          Description=Central Logging Agent
          After=network.target

          [Service]
          Type=simple
          ExecStart={{ clagent_binary_path }}
          Restart=on-failure

          [Install]
          WantedBy=multi-user.target          
      notify:
        - Reload systemd
        - Restart clagent

    - name: Enable and start clagent service
      systemd:
        name: clagent.service
        enabled: true
        state: started
        daemon_reload: false

  handlers:
    - name: Reload systemd
      systemd:
        daemon_reload: true

    - name: Restart clagent
      systemd:
        name: clagent.service
        state: restarted