The Alertly.Net agent is a single small binary that reports server health every 30 seconds by default. It runs as an unprivileged systemd service and uses very little CPU and memory. systemd also keeps it in check: it runs at low priority with idle disk priority, is capped at a quarter of one CPU core and 256 MB of memory, and can't start more than 64 tasks.
Requirements
- Linux with systemd (Ubuntu, Debian, RHEL, Rocky, Alma, Fedora, Amazon Linux and most others).
curland root access (sudo) for the installation.- An
amd64,arm64orarmv7processor. - Outbound HTTPS to
https://alertly.net, and to GitHub for downloading the agent. No inbound ports are needed.
Install
Every server gets its own token. Copy the command from the server's page in Alertly.Net and run it on the server:
curl -fsSL https://alertly.net/agent/install.sh | sudo bash -s -- --token=alr_your_token_here
The installer:
- Downloads the right binary for your processor and checks its SHA-256 checksum.
- Creates an
alertlysystem user with no login shell. - Writes
/etc/alertly/agent.yml, readable only by root and the agent. - Installs and starts the
alertly-agentsystemd service with a hardened sandbox (ProtectSystem=strict,NoNewPrivileges). Its only writable folder is/var/lib/alertly, where it keeps unsent measurements. - Turns on a daily timer that installs new agent versions (see Updates).
Options
Add options after the token:
| Option | What it does |
|---|---|
--docker |
Lets the agent read container status and usage from the Docker socket. Access to the socket is equivalent to root, so it's only granted when you ask. |
--no-logs |
Doesn't give the agent read access to the authentication and kernel logs. Failed SSH logins, sudo use, new accounts, out-of-memory kills and system errors (disk errors, crashes) then aren't reported. |
--no-auto-update |
Leaves out the daily update timer. Update by running the install command again. |
--version=1.2.3 |
Installs a specific version instead of the latest. |
You can also pass the token as an environment variable. Put it after sudo, or sudo drops it:
curl -fsSL https://alertly.net/agent/install.sh | sudo ALERTLY_TOKEN=alr_your_token_here bash
Check that it's running
systemctl status alertly-agent
journalctl -u alertly-agent -n 50
The server page in Alertly.Net switches from Waiting for agent to Online within a minute.
To see exactly what the agent would send, without sending it:
sudo -u alertly alertly-agent --once
Updates
Once a day, at a random time, the alertly-agent-update timer asks Alertly.Net which agent version is current. When yours is older, it downloads the new binary from the address in /etc/alertly/agent.yml, checks its SHA-256 checksum, makes sure it runs, swaps it in and restarts the agent. Alertly.Net only tells it the version number, never where to download from.
systemctl list-timers alertly-agent-update.timer # when it runs next
journalctl -u alertly-agent-update -n 20 # what the last run did
sudo systemctl start alertly-agent-update # update right now
To update by hand instead, run the install command again with --no-auto-update. It replaces the binary and removes the timer. It rewrites /etc/alertly/agent.yml but keeps your database and web server lines, so pass the same options you installed with (like --docker). If you've lost the token, open the server's Settings and choose Generate new token under Agent token. The old token stops working immediately, so the agent stops reporting until you run the new command.
Your Alertly.Net administrator can hold automatic updates during a rollout (new installs still get the latest version), set how often agents may check in and send metrics, and turn off kinds of data for every server: process lists, listening ports, system logs, pending updates, firewall status, Docker, and databases and web servers. Data of a disabled kind that was already stored is cleared. The agent picks these up at its next check-in, with no reinstall.
When the connection drops
The agent keeps measuring while it can't reach Alertly.Net and sends everything once it's back: up to 2,000 measurements, at most 23 hours old (about 16 hours at the default 30-second interval). Unsent measurements are saved to /var/lib/alertly, so they also survive a restart of the agent or the server.
While a server is paused in Alertly.Net, the agent only checks in and doesn't collect or send measurements.
Uninstall
curl -fsSL https://alertly.net/agent/uninstall.sh | sudo bash
This stops the service and update timer, and removes the binary, configuration, saved measurements and system user. Then delete the server in Alertly.Net to remove its history.
Behind a proxy or firewall
The agent reports to https://alertly.net/api/v1. The installer and the update timer also download from GitHub (github.com and objects.githubusercontent.com). If outbound traffic is filtered, allow those hosts on port 443.
To send traffic through a proxy, add the standard HTTPS_PROXY variable to the service:
sudo systemctl edit alertly-agent
# add these two lines, then save:
# [Service]
# Environment=HTTPS_PROXY=http://proxy.internal:3128
sudo systemctl restart alertly-agent
To use the proxy for updates too, run sudo systemctl edit alertly-agent-update and add the same two lines.