Agent Configuration

The StatusRadar Agent is configured through a single shell environment file at /opt/statusradar/config.env. There is no YAML config — the agent reads its settings from environment variables, and systemd loads config.env into the service via EnvironmentFile=.

The automatic installer writes config.env for you. To change any setting later, edit this file and restart the agent.

Configuration File Location

/opt/statusradar/config.env

This is a plain KEY=value shell file (one variable per line, no quotes required, no spaces around =). Anything the agent or its plugins need is set here.

Basic Structure

A minimal config.env looks like this:

# /opt/statusradar/config.env
API_TOKEN=your-agent-token-here
API_URL=https://api.statusradar.dev
INTERVAL=300

# Comma-separated list of enabled plugins (optional)
PLUGINS=redis,nginx

# Plugin settings — only the ones your enabled plugins need
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
NGINX_STATUS_URL=http://127.0.0.1/nginx_status

Core Settings

These four variables control the agent itself. The installer always writes the first three.

API_TOKEN

Required. Your unique agent authentication token. Get it from the Add Server page in the dashboard.

API_TOKEN=abc123def456ghi789jkl012mno345pqr678

Security: Keep this token secret. Anyone with it can send metrics to your account. The installer locks config.env to chmod 600 — keep it that way.

The agent authenticates to the API with Authorization: Bearer <API_TOKEN>.

API_URL

Optional. Default: https://api.statusradar.dev. The StatusRadar API endpoint. Leave the default unless you run a self-hosted instance.

API_URL=https://api.statusradar.dev

INTERVAL

Optional. Default: 300 (5 minutes). How often, in seconds, the agent collects and sends metrics. The minimum accepted value is 60.

INTERVAL=300

Interval guidance:

Lower intervals increase collection overhead and the volume of stored data. Do not go below 60 seconds unless you genuinely need it.

PLUGINS

Optional. A comma-separated list of the service plugins to enable. If empty, the agent only reports core system metrics (CPU, memory, disk, network).

PLUGINS=redis,mysql,nginx,docker

Only plugins listed here are loaded. Each enabled plugin reads its own variables from config.env (see the reference table below). Plugin files must also exist in /opt/statusradar/plugins/ — the installer downloads the ones you name in PLUGINS.

How systemd Loads the Config

The agent runs as the statusradar-agent systemd service. Its unit file (/etc/systemd/system/statusradar-agent.service) loads config.env and passes the core settings to the agent on the command line:

[Service]
Type=simple
User=root
WorkingDirectory=/opt/statusradar
EnvironmentFile=/opt/statusradar/config.env
ExecStart=/usr/bin/python3 /opt/statusradar/statusradar-agent.py --token ${API_TOKEN} --api-url ${API_URL} --interval ${INTERVAL}
Restart=always
RestartSec=30
StandardOutput=append:/var/log/statusradar/agent.log
StandardError=append:/var/log/statusradar/agent.log

Two things to understand:

• EnvironmentFile=/opt/statusradar/config.env exports every variable in the file into the agent's environment. That is how plugin variables like REDIS_HOST or MYSQL_USER reach the plugins — they are read from the process environment, not from any config object.
• ExecStart only references ${API_TOKEN}, ${API_URL}, and ${INTERVAL} explicitly. All other variables are consumed by the plugins through the environment, so there is no need to add them to ExecStart.

Note: StandardOutput=append: requires systemd 240 or newer. On older systems (CentOS/RHEL 7) the installer instead writes StandardOutput=journal and StandardError=journal, and logs go to journalctl -u statusradar-agent.

Changing Settings

To change any setting — the interval, a plugin password, or to add a new plugin — edit config.env and restart the service:

# 1. Edit the file (as root)
sudo nano /opt/statusradar/config.env

# 2. Restart the agent so it picks up the changes
sudo systemctl restart statusradar-agent

# 3. Confirm it started cleanly
sudo systemctl status statusradar-agent
sudo journalctl -u statusradar-agent -n 50 --no-pager

The agent does not hot-reload config.env; a restart is always required.

Adding a Plugin to an Existing Install

1. Make sure the plugin file exists in /opt/statusradar/plugins/ (e.g. mysql_plugin.py). Re-running the installer with the plugin listed in PLUGINS= downloads it for you, or download it manually from https://statusradar.dev/agent/plugins/<name>_plugin.py.
2. Add the plugin's name to the PLUGINS= line in config.env.
3. Add the plugin's variables (see the reference table) to config.env.
4. Restart the agent.

The installer persists Redis, Docker, VictoriaMetrics, and RabbitMQ variables automatically when you pass them at install time. For any other plugin, add its variables to config.env by hand and restart.

Plugin Environment Variable Reference

Every plugin is configured entirely through environment variables in config.env. The table below lists the exact variable name each plugin reads, with the default the agent falls back to when the variable is unset.

Redis

MySQL / MariaDB

PostgreSQL

MongoDB

Nginx

Apache

PHP-FPM

Memcached

RabbitMQ

Elasticsearch

Meilisearch

Varnish

The Varnish plugin reads stats by invoking the varnishstat CLI; both variables are optional.

HAProxy

Docker

VictoriaMetrics

mdadm

The mdadm plugin reads Linux Software RAID status from /proc/mdstat via the mdadm CLI. It has no environment variables — just add mdadm to PLUGINS= and ensure mdadm is installed.

Security

The token and any plugin passwords live in config.env, so protect it:

sudo chmod 600 /opt/statusradar/config.env
sudo chown root:root /opt/statusradar/config.env

The installer sets chmod 600 automatically. Additional best practices:

• Use read-only monitoring users. Create dedicated database accounts with the minimum privileges needed; never use root/admin credentials. For example, for MySQL:

  CREATE USER 'monitor'@'localhost' IDENTIFIED BY 'secret';
  GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'monitor'@'localhost';
  FLUSH PRIVILEGES;

  And for PostgreSQL:

  CREATE USER statusradar_monitor WITH PASSWORD 'secret';
  GRANT pg_monitor TO statusradar_monitor;

• Keep services on localhost. Point plugin variables at localhost/127.0.0.1 whenever the service runs on the same host. For remote services, restrict access with firewall rules and use TLS where the plugin supports it (*_PROTOCOL=https, RABBITMQ_USE_SSL=true).

• Enable only the plugins you use. Each plugin adds roughly 5-10 MB of memory and its own collection work; a shorter PLUGINS= list keeps the agent lean.

Example config.env Files

Web Server (Nginx + PHP-FPM + Redis)

# /opt/statusradar/config.env
API_TOKEN=your-agent-token-here
API_URL=https://api.statusradar.dev
INTERVAL=300

PLUGINS=nginx,php_fpm,redis

NGINX_STATUS_URL=http://127.0.0.1/nginx_status
PHP_FPM_STATUS_URL=http://127.0.0.1:9000/status?json

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

Database Server (PostgreSQL + Redis)

# /opt/statusradar/config.env
API_TOKEN=your-agent-token-here
API_URL=https://api.statusradar.dev
INTERVAL=300

PLUGINS=postgresql,redis

POSTGRESQL_HOST=localhost
POSTGRESQL_PORT=5432
POSTGRESQL_USER=statusradar_monitor
POSTGRESQL_PASSWORD=secret
POSTGRESQL_DATABASE=postgres

REDIS_HOST=localhost
REDIS_PORT=6379

Container Host (Docker + Nginx)

# /opt/statusradar/config.env
API_TOKEN=your-agent-token-here
API_URL=https://api.statusradar.dev
INTERVAL=300

PLUGINS=docker,nginx

DOCKER_SOCKET=/var/run/docker.sock

NGINX_STATUS_URL=http://127.0.0.1/nginx_status

After writing or editing any of these, restart the agent:

sudo systemctl restart statusradar-agent

Verifying Changes

After a restart, confirm the agent loaded the new configuration:

# Service should be active (running)
sudo systemctl status statusradar-agent

# Recent log lines (or journalctl on older systemd)
sudo tail -n 50 /var/log/statusradar/agent.log
sudo journalctl -u statusradar-agent -n 50 --no-pager

Then check the dashboard — the server's last-update time should advance, and any newly enabled plugin's metrics should appear within one collection interval.

Next Steps

• Install the agent
• Add monitoring plugins
• System requirements
• Troubleshooting
• Upgrading the agent