Skip to content
Tyr

Linux systemd

The install script sets this up automatically; this guide is for manual / custom setups.

1. Install the binary

Download tyr-<arch>-linux.tar.gz from releases:

Terminal window
tar xzf tyr-x86_64-linux.tar.gz
sudo install tyrd /usr/local/bin/
sudo install tyr  /usr/local/bin/

2. Create config

Terminal window
sudo mkdir -p /etc/tyr /var/lib/tyr

/etc/tyr/tyrd.yaml:

# Behavior for processes that don't match a known agent_type
unregistered_agents: audit    # audit | quarantine | deny


# Heartbeat to server (seconds)
heartbeat_interval_s: 30


# Disk buffer size for offline events (MiB)
buffer_size_mb: 500


# Enable verbose logs
debug_mode: false


# Bootstrap enrollment token — one-time use to request a client certificate
enrollment_token: "tyr_et_..."


# Path to server CA certificate (downloaded from /api/v1/ca.pem)
ca_cert_path: /etc/tyr/ca.pem


# Where to persist agent identity, cert, and event buffer
data_dir: /var/lib/tyr

Download the server CA:

Terminal window
curl -sSL https://tyr.example.com:7701/api/v1/ca.pem | sudo tee /etc/tyr/ca.pem
sudo chmod 644 /etc/tyr/ca.pem

3. Systemd unit

/etc/systemd/system/tyr-agent.service:

[Unit]
Description=Tyr agent (tyrd)
Documentation=https://terranchi.github.io/tyr/
After=network-online.target
Wants=network-online.target


[Service]
Type=simple
ExecStart=/usr/local/bin/tyrd \
  --server https://tyr.example.com:7700 \
  --name   %H \
  --enforce \
  --tls-capture
Restart=on-failure
RestartSec=3s


# Required capabilities for eBPF
AmbientCapabilities=CAP_BPF CAP_SYS_ADMIN CAP_NET_ADMIN CAP_PERFMON CAP_SYS_PTRACE CAP_SYS_RESOURCE
NoNewPrivileges=false


# Hardening
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/var/lib/tyr /sys/fs/bpf


# Logs
StandardOutput=journal
StandardError=journal


[Install]
WantedBy=multi-user.target

%H expands to the hostname.

4. Start and enable

Terminal window
sudo systemctl daemon-reload
sudo systemctl enable --now tyr-agent
sudo systemctl status tyr-agent
sudo journalctl -u tyr-agent -f

Operating

Terminal window
# view status
systemctl status tyr-agent


# tail logs
journalctl -u tyr-agent -f


# reload after config change
systemctl restart tyr-agent


# stop (events stop, agent goes offline in the UI)
systemctl stop tyr-agent

Logs

Stderr logs go to the journal. Increase verbosity:

Terminal window
sudo systemctl edit tyr-agent
# drop in:
[Service]
Environment="RUST_LOG=debug"

Then systemctl restart tyr-agent.

Troubleshooting

  • failed to load BPF program — kernel too old or missing CONFIG_BPF_LSM. See Enforcement concepts.
  • enrollment rejected: token consumed — your enrollment token has been used up; create a new one.
  • Agent shows as offline but process is running — check network reachability to :7700 and that the server CA matches.

→ Next: Kubernetes · Troubleshooting