Agent Requirements

This document outlines the system requirements for running the StatusRadar monitoring agent.

Minimum System Requirements

Operating System

The installer auto-detects your package manager (apt, dnf, yum, zypper, pacman, or apk) and installs dependencies accordingly. Any modern Linux distribution that ships one of these is supported.

Supported (full automatic install + systemd service):

Partial support:

• Alpine Linux (apk): the agent itself runs fine, but service setup is manual — Alpine uses OpenRC, and automatic systemd service installation is not yet available. The installer also requires bash, so install it first:

  apk add bash

  After installing the agent, run it under your init system (OpenRC) or directly. See Installation for the manual command.

Not supported:

• Windows
• macOS
• BSD variants (FreeBSD, OpenBSD)
• End-of-life Linux distributions

Hardware Requirements

Minimal Configuration (Basic Monitoring Only)

• CPU: 1 core @ 1.0 GHz
• RAM: 256 MB available
• Disk: 100 MB free space
• Network: 10 Kbps sustained bandwidth

Recommended Configuration (Production Use)

• CPU: 1 core @ 2.0 GHz or faster
• RAM: 512 MB available
• Disk: 500 MB free space
• Network: 100 Kbps sustained bandwidth

High-Load Configuration (Many Plugins Enabled)

• CPU: 2 cores @ 2.0 GHz
• RAM: 1 GB available
• Disk: 1 GB free space
• Network: 1 Mbps sustained bandwidth

Software Dependencies

Required:

• Python 3.6 or later
• systemd (for automatic service management; optional on Alpine/OpenRC)

Python Packages (installed automatically by the installer):

• psutil — system metrics collection (CPU, memory, disk, network)
• requests — HTTP client for API communication

The installer prefers distro packages (e.g. python3-psutil, python3-requests; py3-* on Alpine, python-* on Arch), then falls back to pip, then to a virtual environment under /opt/statusradar/venv if the system Python is externally managed (PEP 668).

Optional (only when the matching plugin is enabled):

• redis — Redis plugin
• docker — Docker plugin

Other plugins (MySQL, PostgreSQL, MongoDB, Nginx, Apache, PHP-FPM, Memcached, RabbitMQ, Elasticsearch, Meilisearch, Varnish, HAProxy, VictoriaMetrics, mdadm) use the standard library or requests, or read system files directly, and need no extra Python packages.

Resource Usage

Base Agent (No Plugins)

Typical Resource Consumption:

• CPU: 0.1-0.5% (idle) to 5-10% (during collection)
• Memory: 30-50 MB RSS
• Disk I/O: < 1 MB/minute (logs and state)
• Network: 2-5 KB/minute

Metrics Collection Impact:

• Collection interval: 5 minutes (default, INTERVAL=300; minimum 60 seconds)
• Collection duration: 1-3 seconds
• Payload size: ~2 KB per report

Per-Plugin Resource Usage

Example Configurations

Web Server (Nginx + PHP-FPM + Redis + MySQL)

• Total Memory: ~120 MB
• CPU Usage: 10-15% during collection, < 1% idle
• Network: ~10 KB/minute
• Disk: < 2 MB/minute

Database Server (PostgreSQL + Redis)

• Total Memory: ~100 MB
• CPU Usage: 8-12% during collection
• Network: ~8 KB/minute

Container Host (Docker with 20 containers)

• Total Memory: ~150 MB
• CPU Usage: 15-20% during collection
• Network: ~15 KB/minute

Network Requirements

Outbound Connectivity

Required:

• HTTPS (port 443) to api.statusradar.dev
• Protocol: HTTPS with TLS 1.2 or later
• Firewall: Outbound HTTPS must be allowed

Bandwidth:

• Minimal: 10 Kbps sustained
• Recommended: 100 Kbps sustained
• Burst: Up to 1 Mbps during metric collection

DNS Requirements

Required DNS Resolution:

• api.statusradar.dev → resolves to API server
• statusradar.dev → resolves to web interface

DNS Servers:

• Use any public or private DNS server
• Google DNS (8.8.8.8, 8.8.4.4) recommended for reliability

Proxy Support

HTTP/HTTPS Proxies: The agent supports HTTP proxies via environment variables:

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"

Authenticated Proxies:

export HTTPS_PROXY="http://user:[email protected]:8080"

Disk Space Requirements

Installation

• Agent Code: 5-10 MB
• Python Dependencies: 50-100 MB
• Configuration: < 1 MB
• Total Installation: ~100 MB (/opt/statusradar)

Runtime

• Logs: 1-10 MB/day (/var/log/statusradar/agent.log, depending on verbosity)
• Cache: < 1 MB
• State Files: < 1 MB
• Total Runtime: 10-50 MB/week

Log Rotation

• On systemd >= 240, the agent writes directly to /var/log/statusradar/agent.log — rotate it with logrotate.
• On older systemd, output goes to the journal — configure retention via /etc/systemd/journald.conf.

Performance Impact

System Load

CPU Impact:

• Collection runs every 5 minutes (default)
• Each collection takes 1-5 seconds
• CPU spike during collection: 5-20%
• Idle CPU usage: < 0.5%

Memory Impact:

• Resident Set Size (RSS): 50-200 MB depending on plugins
• Virtual Memory (VSZ): 100-500 MB
• No memory leaks (tested for 30+ days continuous operation)

Disk I/O Impact:

• Read: < 100 KB/collection (reading service stats)
• Write: < 50 KB/collection (logs and cache)
• No sustained I/O load

Plugin-Specific Impact

Database Plugins (MySQL, PostgreSQL, MongoDB):

• Execute monitoring queries (e.g., SHOW STATUS, SELECT pg_stat_database)
• Queries use indexes and are read-only
• Negligible impact on database performance
• Recommended: Create dedicated read-only monitoring user

Web Server Plugins (Nginx, Apache):

• Poll status endpoints (e.g., /nginx_status, /server-status)
• Zero impact - status endpoints are optimized for monitoring
• No logging overhead (access_log disabled on status endpoints)

Container Plugin (Docker):

• Query Docker API for container stats
• Higher CPU/memory usage with many containers
• Impact scales linearly with container count
• Recommendation: Limit to 50 containers or adjust collection interval

Scalability

Single Server Limits

Supported Scale:

• Services Monitored: Up to 16 plugins simultaneously
• Docker Containers: Up to 100 containers
• Collection Interval: Minimum 60 seconds
• Uptime: Tested for months of continuous operation

Multi-Server Deployments

One Agent Per Server:

• Each server runs its own agent instance
• Agents report independently to API
• No cross-server communication required

Resource Planning:

Total Memory = Base (50 MB) + (Plugins × 15 MB avg)
Total CPU = Base (0.5%) + (Plugins × 2% avg)

Example:

• 100 servers × 100 MB average = 10 GB total across fleet
• Negligible compared to monitored services

Platform-Specific Notes

The installer auto-detects your package manager, so in most cases you do not need to install Python manually. The commands below are only needed if Python or bash is missing.

Debian / Ubuntu (apt)

sudo apt-get update
sudo apt-get install -y python3

systemd is included by default on Ubuntu 16.04+ and Debian 8+.

RHEL / Rocky / AlmaLinux / CentOS / Fedora (dnf / yum)

sudo dnf install -y python3

SELinux: the agent works with SELinux enforcing — no custom policies required. It runs as root with standard permissions.

Arch Linux (pacman)

sudo pacman -S --needed python

openSUSE (zypper)

sudo zypper install -y python3

Alpine Linux (apk)

The installer requires bash, and service setup is manual (no systemd):

apk add --no-cache bash python3 py3-psutil py3-requests

After running the installer, start the agent under OpenRC or directly. The agent process itself is fully compatible; only automatic service registration is unavailable.

Security Requirements

User Permissions

Agent Runs as Root:

• Required for system metrics (CPU, memory, disk, network)
• Required for accessing service sockets (Docker, systemd)
• Follow security best practices (see below)

File Permissions

The installer secures the config file automatically. To verify or restore:

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

The agent directory should be owned by root:

chown -R root:root /opt/statusradar
chmod 755 /opt/statusradar

Network Security

Firewall Rules:

# Debian/Ubuntu (ufw)
sudo ufw allow out 443/tcp

# RHEL/Rocky/Fedora (firewalld)
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Certificate Validation:

• Agent validates API server SSL certificate
• Uses system CA certificate store
• Update CA certificates regularly:

# Debian/Ubuntu
sudo apt-get install -y ca-certificates
sudo update-ca-certificates

# RHEL/Rocky/Fedora
sudo dnf install -y ca-certificates
sudo update-ca-trust

Compatibility

Python Versions

SystemD Versions

Minimum: systemd 219 (2015) Recommended: systemd 240+ — enables direct file logging to /var/log/statusradar/agent.log (older versions fall back to the journal).

Check Version:

systemctl --version

Kernel Requirements

Minimum: Linux kernel 3.10 (CentOS 7 era) Recommended: Linux kernel 4.15+ (Ubuntu 18.04 era)

Required Kernel Features:

• /proc filesystem
• /sys filesystem
• Netlink sockets (for network stats)

Virtualization Support

Supported Platforms

Fully Supported:

• ✅ KVM / QEMU
• ✅ VMware ESXi
• ✅ Hyper-V
• ✅ Xen
• ✅ Proxmox VE
• ✅ AWS EC2
• ✅ Google Compute Engine
• ✅ Azure Virtual Machines
• ✅ DigitalOcean Droplets
• ✅ Linode
• ✅ Vultr

Container Platforms:

• ✅ Docker (host installation, not in container)
• ✅ LXC / LXD
• ⚠️ Kubernetes (install as DaemonSet, not standard pod)

Not Recommended:

• ❌ Running agent inside Docker container (install on host)
• ❌ Running agent inside Kubernetes pod (use DaemonSet)
• ❌ Nested virtualization (agent on VM inside VM)

Cloud Provider Specifics

AWS EC2:

• Works on all instance types (t2, t3, m5, c5, etc.)
• Enhanced networking recommended for accurate network stats
• Works with both EBS and instance store

Google Cloud:

• Works on all machine types
• No special configuration required

Azure:

• Works on all VM sizes
• Supports both Linux VM and Virtual Machine Scale Sets

Resource Recommendations for Cloud:

• Smallest viable instance: t2.micro / f1-micro equivalent
• Recommended: t3.small / e2-small equivalent or larger

Upgrade Path

The agent is backward compatible within major versions. Re-run the installer in update mode:

curl -s https://statusradar.dev/install-agent.sh | sudo bash -s update

• Config file format is backward compatible
• No database migration required
• No service downtime during upgrade

See Upgrading for details.

Limitations

Known Limits

Metrics Collection:

• Maximum plugins per agent: 16 (all available plugins)
• Minimum collection interval: 60 seconds
• Maximum monitored Docker containers: 100 (soft limit)

Network:

• API request timeout: 30 seconds
• Maximum payload size: 10 MB (effectively unlimited for metrics)

Unsupported Scenarios

• ❌ Multiple agents on same server reporting as different servers
• ❌ Agent running in Docker container (install on host)
• ❌ Monitoring Windows services
• ❌ Monitoring macOS
• ❌ Air-gapped networks (requires internet connectivity)

Troubleshooting Requirements Issues

Check Python Version

python3 --version

Expected: Python 3.6.0 or later.

Check Available Memory

free -h

Ensure at least 256 MB free.

Check Disk Space

df -h /opt/statusradar

Ensure at least 100 MB free.

Check Network Connectivity

curl -I https://api.statusradar.dev

Expected: HTTP/2 200.

Check the Service

systemctl --version
systemctl status statusradar-agent

Next Steps

• Install the agent
• Configure plugins
• Troubleshooting
• Plugin documentation