Skip to content
Docs

Install on Linux (automatic)

On this page
  1. Before you start
  2. Install
  3. Unattended installation
  4. Upgrade
  5. Manage the agent
  6. What is installed
  7. Security
  8. Settings

The installer is the recommended way to run an agent on a Linux server or VM. It downloads the agent, checks it, stores its token safely and runs it as a hardened systemd service, under an unprivileged user. Run it again at any time: it upgrades or repairs the installation, and never touches the token.

One machine, one agent. To run several agents on one host, use Docker — one container per agent.

Before you start#

  • A Linux distribution with systemd 235 or later (Debian 11+, Ubuntu 20.04+, RHEL/Rocky/Alma 8+…), on x86_64 or aarch64, with glibc (Alpine and other musl distributions: use Docker).
  • root access (or sudo), curl (or wget), and the ICU libraries (libicu, installed on most distributions).
  • The agent's token, copied when you created the agent in Onagre.

Install#

Download the installer, then run it:

Terminal
curl -fsSLo onagent-install.sh https://d.onag.re/install.sh
sudo bash onagent-install.sh

It asks for one thing: the token — paste it; nothing is displayed while you type.

TEXT
✓ Linux detected (Ubuntu 24.04 LTS, systemd 255)
✓ Architecture: x86_64
✓ Downloading Onagre Agent 2.9.0.0
✓ SHA-256 verified
✓ Binary checked (onagent --version: 2.9.0.0)
✓ System user onagent created
✓ Installing Onagre Agent
✓ Creating system service

Enter your Onagre Agent token:
>

✓ Token stored securely (/etc/onagent/onagent.env, root only)
✓ Service enabled
✓ Agent started
✓ Connected to Onagre

Onagre Agent is ready.

Connected to Onagre is only shown once the agent itself reports it is connected to the Hub (its /ready endpoint). Otherwise the installer says what is wrong — API unreachable, token refused, Hub unreachable — and where to look.

Prefer one line? The installer is built to be piped safely (nothing runs until it is fully downloaded, and the token is read from your terminal):

Terminal
curl -fsSL https://d.onag.re/install.sh | sudo bash

Unattended installation#

The token is never accepted on the command line, where it would stay in the shell history and the process list. Give it in a file or on standard input:

Terminal
sudo bash onagent-install.sh --token-file /path/to/token
Terminal
printf '%s' "$ONAGRE_TOKEN" | sudo bash onagent-install.sh --token-stdin

Add --yes to answer yes to every question (upgrades, migration). The installer exits with a non-zero status when the agent does not get connected.

Upgrade#

Run the installer again:

Terminal
sudo bash onagent-install.sh
TEXT
Onagre Agent already installed
Current version: 2.8.4.112
Latest version:  2.9.0.0

Upgrade 2.8.4.112 → 2.9.0.0? [Y/n]

The upgrade is transactional: the new version is downloaded, checked against its SHA-256 and run once (--version) before anything changes; the current binary is kept; the new one replaces it atomically, then the agent restarts. If the agent was connected before and is not connected again after the upgrade, the previous version is restored automatically. The token and /etc/onagent/onagent.env are never modified.

Command What it does
sudo bash onagent-install.sh Installs, upgrades to the latest version, or repairs (missing binary, service or token).
sudo bash onagent-install.sh --version 2.9.0.0 Installs this exact version (upgrade or downgrade).
sudo bash onagent-install.sh --rollback Goes back to the binary kept by the last upgrade (run it again to undo).
sudo bash onagent-install.sh --set-token Replaces the token — after Revoke and regenerate in Onagre — and restarts the agent. Also with --token-file or --token-stdin.
sudo bash onagent-install.sh --uninstall Removes the agent; keeps /etc/onagent (token). Add --purge to remove it and the onagent user too.
sudo bash onagent-install.sh --help Every option.

Manage the agent#

Terminal
systemctl status onagent
journalctl -u onagent
journalctl -u onagent -f
journalctl -u onagent --since today
journalctl -u onagent -p warning

The logs go to the systemd journal, with their level: -p warning shows warnings and errors only. If the token is refused, the agent stops (exit status 78) instead of restarting in a loop: fix the token with --set-token.

What is installed#

Item Location
Agent /usr/local/bin/onagent
Token and settings /etc/onagent/onagent.env (TOKEN=…, root only, mode 0600)
Service /etc/systemd/system/onagent.service
Previous version (rollback) and installer state /usr/local/lib/onagent/
Runtime cache /var/cache/onagent/
Logs systemd journal (journalctl -u onagent)

Security#

The agent runs as the system user onagent (no shell, no home directory), never as root. The service only grants it CAP_NET_RAW, needed by the Ping sensor and network discovery, and hardens it: read-only system, no privilege escalation, no access to devices or kernel settings.

File sensors can only read files the onagent user can read. For a file that only root can read, grant read access to that file alone:

Terminal
sudo setfacl -m u:onagent:r /path/to/file

To change the service — more open files, an extra environment variable… — use a drop-in, kept across upgrades:

Terminal
sudo systemctl edit onagent

Settings#

Settings are environment variables: add them to /etc/onagent/onagent.env, one NAME=value per line, then sudo systemctl restart onagent. Upgrades keep them. See Agent configuration.

The health endpoints listen on 127.0.0.1:27520 by default, from the machine itself only. HTTP_API_BIND=0.0.0.0 (or an address of the machine) and PORT change that: a non-loopback address exposes these endpoints to the network — protecting them (firewall) is up to you; the installer creates no firewall rule.

Prefer to do every step yourself? See Linux (manual).