Agent configuration
An agent needs only one setting: its token. Everything else — the sensors to run, their schedule, their variables and secrets — comes from Onagre. There is no configuration file to maintain on the agent's machine, and changing a sensor in Onagre never requires touching the agent.
What the agent receives#
At startup, the agent presents its token to the Onagre API, which tells it which Hub to connect to. It then keeps a permanent, encrypted connection with that Hub, which sends it each check to run:
- the sensor's settings, with its variables already replaced by their values;
- for database, Redis and RabbitMQ sensors, the connection string stored as a secret, decrypted by the Hub and sent over the encrypted connection.
The agent keeps secrets in memory only, for the time of the check: they are never written to disk or to its logs.
Where secrets live#
Database passwords and connection strings are not configured on the agent. Store them in Onagre, in the environment of the sensors that use them:
- Configuration → Environments → the environment (Production…) → Secrets → add the connection string.
- In the sensor, choose that secret in the Database connection, Redis connection or Broker connection section.
See Secrets and Secret security.
Settings#
Settings are environment variables — in /etc/onagent/onagent.env on Linux (then sudo systemctl restart onagent; upgrades keep the file), the service's environment on Windows, -e or --env-file for Docker. Most also exist as command-line options. Only TOKEN is required: every other setting has the default below, nothing needs to be written for it.
| Variable | Option | Default | Purpose |
|---|---|---|---|
TOKEN |
-t |
(required) | The agent's token, from New agent or Revoke and regenerate. |
API |
-a |
https://api.onagre.io |
The Onagre API. Change it only if Onagre support asks you to. |
LOG |
-l |
see Logs | Path of a log file (one per day, 4 kept). |
LOG_CONSOLE |
-lc |
on (Linux, Docker), off (Windows) | 0, false, off or no: stop writing the logs to standard output (journal, docker logs); 1, true, on or yes: write them. |
LOG_FORMAT |
text | json: standard output in compact JSON, one event per line with all its properties — for container platforms that index JSON. |
|
PORT |
-p |
27520 |
Port of the health endpoints. |
HTTP_API |
-nohttp |
on | 0, false, off or no: turn the health endpoints off. |
HTTP_API_BIND |
127.0.0.1 |
Address of the health endpoints: 127.0.0.1 (the machine only), 0.0.0.0 (every IPv4 interface), an address of the machine, or any (every IPv4 and IPv6 interface). A non-loopback address exposes them to the network. |
|
SM |
-sm |
— | Any value: stop sending the machine's CPU, memory and disk (Server sensor). |
HEARTBEAT_ENDPOINT |
-he |
— | A URL of your own that the agent calls (POST, JSON {"agent": "<code>", "timestamp": "…"}) at a regular interval, to watch the agent from another tool. |
HEARTBEAT_INTERVAL |
-hi |
30 |
Interval of those calls, in seconds. |
HL |
-hl |
10 |
Lifetime of the agent's HTTP handlers, in minutes. Leave the default. |
SENSOR_WORKERS |
-w |
32 |
Number of checks run at the same time (1 to 256). The agent never accepts more work than it can handle: beyond that, checks wait on the Onagre side instead of being lost. |
SENSOR_HTTP2 |
on | 0, false, off or no: HTTP sensors only use HTTP/1.1 (otherwise HTTP/2 is offered, with automatic fallback). |
--version prints the agent's version and exits, without network, token nor configuration.
If TOKEN is missing or the Onagre API refuses it, the agent stops with exit status 78 — the Linux service then does not restart it in a loop: fix the token, then restart. While the API cannot be reached, or answers with a temporary error, the agent waits and retries on its own.
Logs#
| System | By default |
|---|---|
| Linux | Standard output, collected by the systemd journal: journalctl -u onagent (-f to follow, --since today, -p warning for warnings and errors). No log file. |
| Docker | Container output: docker logs. No log file. |
| Windows | One file per day, 4 kept, in %LOCALAPPDATA%\Onagre\ — for the LocalSystem account, C:\Windows\System32\config\systemprofile\AppData\Local\Onagre\. |
LOG=<path> adds a log file (one per day, 4 kept) on any system.
The agent sends its logs nowhere by itself: the system collects them — the systemd journal, the container runtime, or the file on Windows. To centralise them, point your own collector (Grafana Alloy, Vector, Fluent Bit…) at the journal or at the container logs. LOKI_ENDPOINT, LOKI_ACCOUNT and LOKI_PASSWORD are no longer supported: they are ignored and the agent logs a warning at startup until you remove them.
At startup, the log shows the agent's code, version and Hub endpoint (Endpoint : …) — the address to allow if you filter outbound traffic.
Network#
The agent only opens outbound connections:
| Destination | Port | Why |
|---|---|---|
api.onagre.io |
443 (HTTPS) | Startup: authentication and Hub address. |
The Hub (Endpoint in the log) |
443 (gRPC over TLS) | Permanent connection: checks and results. |
api.ipify.org |
443 (HTTPS) | Optional: shows the agent's public IP address in Onagre. |
| Your resources | as configured | The checks themselves. |