Servers and the agent
Server monitoring uses a small read-only agent that runs on your machine, collects metrics every minute and posts them to the platform. It never opens a port and never accepts commands. This page covers installation on Linux and Windows, what is collected, the optional local settings file, thresholds, agent updates, uninstalling and the security promises.
Add a server
Servers → Add server: name, optional location / provider / type / group / tags, Report every (seconds) (30–600, default 60), the services to watch (one per line: nginx, mysql, php-fpm, docker…), the thresholds and the Agent settings (see below). Your plan decides how many servers you may add (the free plan includes one).
After saving you get a one-line install command that contains a one-time registration token. Run it on the server; the token is exchanged for the agent's own long-lived token and becomes useless. If you lose the command, Generate new token on the server page makes a new one.
Linux install (one line)
As root:
curl -fsSL https://your-monitor.example/api/agent/install.sh | sudo bash -s -- REGISTER_TOKEN
What the installer does:
- downloads
/usr/local/bin/aim-agent(a bash script; needs bash, coreutils and curl); - registers with the platform and writes
/etc/aim-agent/agent.conf(mode 600, root only) with the app URL, the agent token and the agent's update key; - creates and starts the systemd unit
aim-agent.service(aim-agent loop, restarts automatically, nice 10). Where systemd is missing it adds a cron line* * * * * /usr/local/bin/aim-agent runinstead; - sends the first sample; the server shows up as Online within a minute.
Add --insecure after the token for an installation that still runs on a self-signed certificate.
Agent commands:
aim-agent status # app URL, version, update key present, local settings file, spool size
aim-agent collect # print one JSON sample: exactly what is sent
aim-agent run # send one sample now
aim-agent update # look for a signed agent update now (only when the server allows it)
aim-agent verify-package update.json # check the signature of a downloaded update package
aim-agent conf-example # print a collectors.conf template
aim-agent version
systemctl status aim-agent
journalctl -u aim-agent
What the Linux agent collects
Each collector runs only when its tool or file exists on the host and reports null otherwise; nothing is guessed. The server page lists the collectors that found nothing readable under "Not installed / not readable on this host".
| Collector | Source | Data |
|---|---|---|
| host | /etc/os-release, /etc/cloudlinux-release, uname, /proc/uptime | hostname, OS (CloudLinux detected), kernel, architecture, uptime, process count |
| cpu | /proc/stat (1-second sample), /proc/cpuinfo | total usage %, usage % per core, cores, model |
| memory, swap | /proc/meminfo | total, used, available, cached; swap total/used |
| load | /proc/loadavg | 1 / 5 / 15 minute load |
| disks | df -P, df -Pi | per mount point: filesystem, total, used, %, inode % (tmpfs, overlay, snap, boot/efi skipped) |
| diskio | /proc/diskstats | read / write bytes per second (sd*, vd*, nvme*, xvd*, md*) |
| network | /proc/net/dev, /sys/class/net | per interface: bytes, bytes/s in and out, link state, speed, errors, drops (lo, docker, veth, bridges skipped) |
| processes | ps | top 15 by CPU with memory and RSS |
| services | systemctl is-active (or service … status) | the services you listed: active / inactive / failed |
| docker | docker ps -a, docker stats | containers with state, health, image, restart count; "daemon not running" when docker exists but is down |
| smart | smartctl | per disk: healthy, temperature, NVMe wear % |
| raid | /proc/mdstat | mdadm arrays and whether one is degraded |
| temperature | /sys/class/thermal, sensors | CPU temperature |
| cloudlinux | lveinfo --csv --period=5m | LVE usage, limits and faults of the top 50 accounts by CPU (5-minute averages) |
| phpfpm | sockets, processes, logs, pool status pages | pools, master processes, "max children reached" log lines; per status page: pool, process manager, accepted connections, listen queue, idle / active / total processes, max children reached, slow requests |
| webserver | systemctl, ss, status pages on localhost | which of httpd/apache2/nginx/lsws/openlitespeed/litespeed is active, established connections on 80/443; nginx stub_status (active, reading / writing / waiting, requests per second), Apache server-status?auto (busy / idle workers, requests per second), LiteSpeed .rtreport (plain / SSL / idle connections, requests in processing, requests per second) |
| weblogs | access log files | 2xx / 3xx / 4xx / 5xx counts of the lines written since the previous sample, 5xx and 4xx rate |
| mysql | mysql client: SHOW GLOBAL STATUS, SHOW REPLICA STATUS (or SHOW SLAVE STATUS) | version, connections, threads running, max connections, max used connections, questions, slow queries (and new ones since the previous sample), uptime, replication (IO / SQL thread, seconds behind source, source host, last error) |
| postgres | psql | version, connections, max connections, standby or primary, replay lag, the 30 largest databases with their size, replicas with state and lag |
| mongodb | mongosh (or mongo) | version, uptime, current / available connections, resident memory, operation counters, replica set name, member state and lag behind the primary |
| redis | redis-cli INFO | version, uptime, used / peak memory, maxmemory, fragmentation, clients, blocked clients, operations per second, hits, misses, hit ratio, evicted keys (and new ones since the previous sample), role, replicas, replica lag, master link status |
| memcached | stats over TCP | version, uptime, connections, memory used and limit, items, hits, misses, hit ratio, evictions, get / set commands |
| mailqueue | exim -bpc, exim -bp, postqueue -p, /var/spool/postfix/deferred | Exim queue and frozen count, Postfix queue and deferred count, Dovecot state |
| firewall | csf, fail2ban-client, ufw, firewall-cmd, imunify360-agent, ModSecurity config | active / inactive per tool, fail2ban jail count |
| updates | apt / dnf, /var/run/reboot-required | pending updates, reboot required |
| jetbackup | jetbackup5api | backup jobs (last and next run, status) and the 30 newest runs |
| kubernetes | kubectl | nodes Ready / not Ready, pods per phase, pods with restarts or a waiting reason (up to 200) |
The platform stores a metrics row per sample (CPU, load, memory, swap, disk, inodes, network in/out, disk I/O, processes, uptime, temperature, plus the full JSON), rolls the rows up per hour and keeps the raw rows for up to 30 days (less on plans with shorter history). The server page shows a card for every collector that sent data, including a CPU per core chart.
Databases and caches
The database collectors sign in with credentials that exist only on the server, in /etc/aim-agent/collectors.conf (see below). The platform never stores or sends database passwords.
- MySQL / MariaDB:
MYSQL_DEFAULTS_FILE(for example/root/.my.cnf) orMYSQL_USER/MYSQL_PASSWORD(passed through the environment, never on the command line), optionalMYSQL_HOST/MYSQL_PORT. Without them themysqlclient uses its normal defaults. - PostgreSQL: when the agent runs as root and no
PG_HOST/PG_USERis set, it runspsqlas thepostgresuser. Otherwise it usesPG_HOST,PG_PORT,PG_USER,PG_PASSWORDandPG_DB(defaultpostgres). - MongoDB:
MONGO_URI, for examplemongodb://monitor:secret@127.0.0.1:27017/admin. - Redis:
REDIS_HOST(default 127.0.0.1),REDIS_PORT(6379),REDIS_PASSWORD(handed toredis-clithroughREDISCLI_AUTH, never on the command line). - Memcached:
MEMCACHED_HOST(127.0.0.1),MEMCACHED_PORT(11211).
When a tool is installed but the agent cannot sign in, the server page says so and names the keys to set.
Web server status and access logs
Status pages are read only from localhost (127.0.0.1, localhost or [::1]). nginx defaults to http://127.0.0.1/nginx_status, Apache to http://127.0.0.1/server-status?auto; set NGINX_STATUS_URL / APACHE_STATUS_URL in collectors.conf for other addresses. A status page that was missing is tried again at most once an hour. LiteSpeed is read from /tmp/lshttpd/.rtreport (and .rtreport.*) or LSWS_RTREPORT.
Access logs (Edit server → Agent → Access logs): one path per line, wildcards allowed (/usr/local/apache/domlogs/*). Empty means the common paths /var/log/nginx/access.log, /var/log/apache2/access.log, /var/log/httpd/access_log, /usr/local/apache/logs/access_log and /usr/local/lsws/logs/access.log. The agent only counts the status codes in the lines added since its previous sample; no log line leaves the server. Details:
- the first sample of a file only records where the file ends; counting starts with the next one;
- log rotation and truncation are detected; at most 50 MB of new lines per file and 50 files are read per sample;
- files must be under
/var/log/,/usr/local/apache/,/usr/local/lsws/,/etc/apache2/logs/,/etc/httpd/logs/,/home/,/opt/or/srv/; other directories needLOG_PREFIXESin collectors.conf. Paths added in collectors.conf withACCESS_LOGSare added to the server's list.
PHP-FPM
Without any setting the agent finds PHP-FPM sockets, counts master processes and counts "max children reached" lines in the usual PHP-FPM logs. For live pool numbers add each pool's pm.status_path under Edit server → Agent → PHP-FPM status pages (up to 10), one per line:
http://127.0.0.1/fpm-status
/run/php/php8.2-fpm.sock:/status
127.0.0.1:9000:/status
A localhost URL is fetched over HTTP; a socket path or 127.0.0.1:port is asked directly over FastCGI and needs the cgi-fcgi tool on the server. FPM_STATUS in collectors.conf adds more entries.
Mail queue
The Exim and Postfix queue sizes are added together and compared with the Mail queue warning (messages) threshold. Mail queue growth (samples) alerts when the queue grew in each of the last N samples, which usually means outgoing mail is stuck or the server is sending spam. The alert message shows the last values and the frozen / deferred counts.
CloudLinux
On a CloudLinux server the agent reads lveinfo every sample (5-minute averages of the top 50 accounts by CPU). The platform stores one set of rows per 5-minute window and keeps them for 8 days.
The CloudLinux page (/app/cloudlinux, shown in the menu under Servers once your organisation has a CloudLinux server) has per server:
- top accounts by CPU, physical memory, entry processes, processes, IO, IOPS or faults, as the average in the range against the LVE limit (peaks in the tooltip);
- faults per account and faults by limit type (CPU, entry processes, physical memory, virtual memory, processes, IO, IOPS);
- 24-hour and 7-day history for the whole server or one account.
JetBackup 5
On a cPanel server with JetBackup 5 the agent calls jetbackup5api (listBackupJobs and listLogs, the 30 newest runs). Set JETBACKUP_CLI when the tool has another name or path. The server page shows the jobs with last and next run and the recent runs. A run that failed (critical) or partially completed (warning) raises one backup_failed alert per run; runs older than 24 hours found on the first look are ignored. A job whose last status is failed also alerts (once per run). To watch JetBackup without the agent, see the JetBackup integration in Integrations.
Kubernetes (kubectl)
When kubectl is installed the agent reads the cluster through the kubeconfig in KUBECONFIG, else ~/.kube/config, else /etc/kubernetes/admin.conf. It reports nodes that are not Ready and pods that restarted, wait with a reason or are not Running/Succeeded. Alerts: nodes not Ready (critical, with a "back to normal" when they recover), a pod in CrashLoopBackOff, ImagePullBackOff, ErrImagePull, OOMKilled and similar or in phase Failed / Unknown (warning), and a pod that restarted Kubernetes pod restarts (30 min) times or more in 30 minutes (warning). For a cluster without an agent host use the Kubernetes integration.
Local collector settings: collectors.conf
/etc/aim-agent/collectors.conf is optional. It holds database credentials and local addresses that should never leave the server. Rules:
- plain
KEY=valuelines; the file is parsed, never executed, and only the keys below are read (values may be quoted); - when the agent runs as root the file must be owned by root and not writable by group or others, otherwise it is ignored. Use mode 600.
Print a template and install it:
aim-agent conf-example > /etc/aim-agent/collectors.conf
chmod 600 /etc/aim-agent/collectors.conf
The template:
# /etc/aim-agent/collectors.conf - optional, owner root, mode 600 (chmod 600)
# Read by aim-agent as KEY=value lines (never executed). Leave a key out to use the default.
#MYSQL_DEFAULTS_FILE=/root/.my.cnf
#MYSQL_USER=monitor
#MYSQL_PASSWORD=secret
#PG_USER=monitor
#PG_PASSWORD=secret
#PG_HOST=127.0.0.1
#MONGO_URI=mongodb://monitor:secret@127.0.0.1:27017/admin
#REDIS_HOST=127.0.0.1
#REDIS_PORT=6379
#REDIS_PASSWORD=secret
#MEMCACHED_HOST=127.0.0.1
#MEMCACHED_PORT=11211
#NGINX_STATUS_URL=http://127.0.0.1/nginx_status
#APACHE_STATUS_URL=http://127.0.0.1/server-status?auto
#LSWS_RTREPORT=/tmp/lshttpd/.rtreport
#ACCESS_LOGS="/var/log/nginx/access.log"
#FPM_STATUS="http://127.0.0.1/fpm-status /run/php/php8.2-fpm.sock:/status"
#LOG_PREFIXES="/data/logs/"
#KUBECONFIG=/root/.kube/config
#JETBACKUP_CLI=jetbackup5api
#DISABLE="kubernetes"
| Key | Meaning |
|---|---|
MYSQL_DEFAULTS_FILE, MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD | MySQL / MariaDB sign-in |
PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, PG_DB | PostgreSQL sign-in (empty: psql as the postgres user) |
MONGO_URI | MongoDB connection string |
REDIS_HOST, REDIS_PORT, REDIS_PASSWORD | Redis |
MEMCACHED_HOST, MEMCACHED_PORT | Memcached |
NGINX_STATUS_URL, APACHE_STATUS_URL | status pages (localhost only; several separated by spaces) |
LSWS_RTREPORT | LiteSpeed report file |
ACCESS_LOGS | extra access logs, added to the server's list |
FPM_STATUS | extra PHP-FPM status pages |
LOG_PREFIXES | extra directories access logs may be read from |
KUBECONFIG | kubeconfig for kubectl |
JETBACKUP_CLI | name or path of jetbackup5api |
DISABLE | collectors to skip, separated by spaces, e.g. "kubernetes jetbackup" |
Collector names for DISABLE: host, cpu, memory, load, disks, diskio, network, processes, services, docker, smart, raid, temperature, cloudlinux, phpfpm, webserver, weblogs, mysql, postgres, mongodb, redis, memcached, mailqueue, firewall, updates, jetbackup, kubernetes.
aim-agent status shows whether the file was found.
Windows agent
PowerShell 5.1 or newer, run as Administrator:
New-Item -ItemType Directory -Force C:\AIM | Out-Null
cd C:\AIM
Invoke-WebRequest -Uri https://your-monitor.example/api/agent/agent.ps1 -OutFile aim-agent.ps1
.\aim-agent.ps1 -Register -AppUrl https://your-monitor.example -Token REGISTER_TOKEN
.\aim-agent.ps1 -Install
-Install creates the scheduled task AIM Agent that runs aim-agent.ps1 -Run every minute as SYSTEM. Configuration (with the update key) and the spool live in %ProgramData%\AIM-Agent. Other switches: -Collect (print one sample), -Status, -SelfUpdate (look for a signed update now), -VerifyPackage package.json, -Uninstall (removes the task and the folder).
The Windows agent collects: hostname, OS version, architecture, uptime, CPU usage, usage per logical processor, cores and model, memory and page file, a load figure derived from CPU usage, logical disks, network interfaces (bytes per second), the top 15 processes, the Windows services you listed (running → active, stopped → inactive), process count, and:
- IIS: the W3SVC service state, current connections, requests per second and the number of sites, when IIS is installed;
- SQL Server: the state of every
MSSQLSERVER,MSSQL$<instance>,SQLSERVERAGENTandSQLAgent$<instance>service. IIS and SQL Server services are tracked and alerted like the services you list; - pending Windows updates, only when Count pending Windows updates is ticked under Edit server → Agent. The Windows Update search is slow, so it runs at most every 6 hours; reboot required is always read.
It collects fewer things than the Linux agent (no Docker, SMART, RAID, temperature, databases, mail queues or firewall).
Agent updates (signed)
At registration every agent receives a per-server update key. Under Edit server → Agent, Update the agent automatically lets the agent replace itself when this installation ships a newer agent version:
- after a sample the agent compares its version with the newest one the platform reports (at most once an hour;
aim-agent updateor-SelfUpdatechecks at once); - it downloads the package from
/api/agent/package(the platform answers 403 while the setting is off); - it checks the package's HMAC-SHA256 signature with its update key, that the version is newer and that the new script parses (
bash -n, or the PowerShell parser); - only then it replaces itself; the Linux service restarts itself with the new script.
A package with a wrong signature is refused and the old agent keeps running. The server page shows "agent outdated: v… available" when the agent is older than the shipped version. Agents registered before 2.1 have no update key (aim-agent status says "no"): run the install command again to register and get one. Registering again changes the key.
Thresholds and alerts
Per server (defaults in brackets), under Edit server → Thresholds:
| Threshold | Default |
|---|---|
| CPU warning / critical % | 80 / 95 |
| Memory warning / critical % | 85 / 95 |
| Disk warning / critical % | 85 / 95 |
| Inode warning % | 85 |
| Swap warning % | 50 |
| Load average warning (0 = off; critical at twice the value) | 0 |
| CPU temperature warning °C (critical 10 °C higher) | 85 |
| Offline after (minutes) | 5 |
| Samples in a row | 3 |
The form also shows Network warning (Mbps); this version stores it but does not alert on it.
A value must be over the line for Samples in a row consecutive samples before a warning or critical alert is sent, and a warning that climbs into critical is sent again; when the value drops back you get a "back to normal" alert and the open alert is marked resolved. Other server alerts: offline (no sample for offline after minutes, at least 3 × the interval; an incident opens and the alert goes out) and online again, reboot (uptime reset), service / container / disk state changes for the watched items, RAID degraded and SMART failure (repeated at most every 12 hours).
Databases, web, mail and cluster alerts
Used when the agent finds the tool on the server. A value of 0 switches a check off.
| Threshold | Default | Alert |
|---|---|---|
| Replication lag warning (s) | 300 | MySQL replica, PostgreSQL standby or replica, MongoDB member or Redis replica this far behind (MySQL: critical at 4 ×). A stopped MySQL IO / SQL thread and a Redis replica whose master link is down are critical regardless |
| Database connections warning % | 85 | MySQL, PostgreSQL or MongoDB connections in use of the maximum, for Samples in a row samples |
| MySQL slow queries per sample | 0 (off) | that many new slow queries between two samples |
| Redis memory warning % | 90 | used memory of maxmemory, when one is set |
| HTTP 5xx rate warning % | 5 | 5xx share of the access-log lines since the previous sample; critical at twice the value |
| Minimum requests for the 5xx rate | 20 | samples with fewer lines are not judged |
| PHP-FPM listen queue warning | 10 | requests waiting in a pool's listen queue (needs a status page) |
| Mail queue warning (messages) | 500 | Exim + Postfix queue size |
| Mail queue growth (samples) | 5 | the queue grew in each of the last N samples |
| CloudLinux faults per account (30 min) | 20 | one account hit its LVE limits that many times in 30 minutes (lve_fault alert, at most hourly per account) |
| Kubernetes pod restarts (30 min) | 3 | restarts of one pod in 30 minutes (k8s alert) |
Also without a threshold: a database or cache the agent reached before and now cannot reach for two samples in a row (critical), and a PHP-FPM pool whose "max children reached" counter went up (warning, at most hourly per pool). These alerts send "back to normal" when the condition clears, except the one-off events (FPM max children, pod problems, backup runs).
Alerts go to the channels mapped to the server, or the organisation's default channels, plus the owner's e-mail; maintenance windows that include the server silence them. See Alerts.
Services watch list
The services you list on the server page are sent to the agent in every answer, together with the interval, the paused flag, the access-log paths, the PHP-FPM status pages and the update settings. That is all the agent reads from the platform. The server page shows every watched service, Docker container, Windows IIS / SQL Server service and disk with its state and when it last changed.
Pause and uninstall
Pause on the server page stops storing samples (the agent keeps calling, gets paused: true and sends nothing). To remove the agent from the machine:
aim-agent uninstall # Linux: stops and removes the unit, config, spool and binary
.\aim-agent.ps1 -Uninstall # Windows
Deleting the server in the panel removes its metrics, services, incidents and alerts; an agent that is still installed is then refused (401) and should be uninstalled.
Security promises
- Read-only. The agent collects and posts. It never executes anything sent by the platform; from the platform's answers it takes only the interval, the service names to check, the paused flag, the access-log paths and PHP-FPM status pages (reduced to a safe character set and used as file paths or localhost addresses, never run), and the update settings.
- Updates are signed. A new agent script is installed only when you ticked Update the agent automatically and its HMAC-SHA256 signature matches the key the agent received at registration.
- Outbound only. It makes HTTPS requests to your installation; no inbound port, no SSH, no remote shell.
- Secrets stay on the server. Linux:
/etc/aim-agent/agent.conf(token and update key) and the optionalcollectors.conf(database credentials), both root only. Windows:%ProgramData%\AIM-Agent\agent.jsonunder the SYSTEM task. On the platform the token is stored as a SHA-256 hash; the registration token is one-time. - Spool when offline. When the platform cannot be reached, samples are appended to
/var/lib/aim-agent/spool(Windows: thespoolfolder) and sent in batches once it answers again; the spool is bounded to about 7 days. - Transparent.
aim-agent collectshows the exact JSON that leaves the machine. Access logs leave only as counts. The script is plain bash / PowerShell that you can read. - Light. One sample per minute, runs at low priority (nice 10); the CPU collector sleeps for one second to measure, and slow tools run with time limits.
API
GET /api/v1/servers, GET /api/v1/servers/{id} (with thresholds and watch list), GET /api/v1/servers/{id}/metrics?hours=24 (raw samples bucketed; over 48 hours the hourly roll-up), GET /api/v1/servers/{id}/services. The metrics endpoints need the servers:read scope.
One click helps us improve these docs.

