Agent Requirements

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

Minimum System Requirements

Operating System

Supported Linux Distributions:

• Ubuntu 20.04 LTS or later
• Debian 10 (Buster) or later
• CentOS 8 or later
• RHEL (Red Hat Enterprise Linux) 8 or later
• Rocky Linux 8 or later
• AlmaLinux 8 or later
• Fedora 35 or later
• Amazon Linux 2 or later
• Arch Linux (current)
• Alpine Linux 3.14 or later

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.8 or later (3.9+ recommended)
• pip (Python package manager)
• systemd (for service management)

Python Packages (installed automatically):

• requests >= 2.28.0 - HTTP client library
• psutil >= 5.9.0 - System metrics collection
• PyYAML >= 6.0 - Configuration file parsing

Optional (for specific plugins):

• redis >= 4.5.0 - Redis plugin
• pymongo >= 4.3.0 - MongoDB plugin
• pymysql >= 1.0.0 - MySQL plugin
• psycopg2-binary >= 2.9.0 - PostgreSQL plugin
• docker >= 6.1.0 - Docker plugin
• elasticsearch >= 8.7.0 - Elasticsearch plugin

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)
• 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

Runtime

• Logs: 1-10 MB/day (depending on verbosity)
• Cache: < 1 MB
• State Files: < 1 MB
• Total Runtime: 10-50 MB/week

Log Rotation

Logs are automatically rotated by systemd journal:

• Default retention: 7 days
• Configurable 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 15 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

Ubuntu/Debian

Python Installation:

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

SystemD:

• Included by default on Ubuntu 16.04+ and Debian 8+

CentOS/RHEL/Rocky Linux

Python Installation:

sudo dnf install -y python3 python3-pip

SELinux Considerations:

• Agent works with SELinux enforcing
• No custom policies required
• Runs as root with standard permissions

Amazon Linux 2

Python Version:

• Amazon Linux 2 includes Python 3.7
• Recommended: Install Python 3.9 from amazon-linux-extras

sudo amazon-linux-extras install python3.8

Alpine Linux

Python Installation:

apk add --no-cache python3 py3-pip

SystemD Alternative:

• Alpine uses OpenRC by default
• Agent can run under OpenRC (manual service file creation required)
• Systemd recommended - install via: apk add systemd

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)

Alternative - Non-Root (Limited Functionality):

# Create statusradar user
useradd -r -s /bin/false statusradar

# Add to required groups
usermod -aG docker statusradar  # For Docker plugin
usermod -aG systemd-journal statusradar  # For log access

Limitations of Non-Root:

• Cannot collect all system metrics
• Cannot access some service sockets
• Reduced plugin functionality

File Permissions

Configuration File:

chown root:root /opt/statusradar/config/agent.yaml
chmod 600 /opt/statusradar/config/agent.yaml

Agent Directory:

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

Network Security

Firewall Rules:

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

# CentOS/RHEL (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:

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

# CentOS/RHEL
sudo yum install -y ca-certificates
sudo update-ca-trust

Compatibility

Python Versions

SystemD Versions

Minimum: systemd 219 (2015) Recommended: systemd 237+ (2018)

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

From Older Versions

The agent is backward compatible within major versions:

Upgrade Methods:

# Method 1: Re-run installer (recommended)
curl -sL https://statusradar.dev/install-agent.sh | sudo bash -s update

# Method 2: Manual git pull
cd /opt/statusradar
sudo git pull origin main
sudo systemctl restart statusradar-agent

Compatibility:

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

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)

Configuration:

• Maximum configuration file size: 1 MB (effectively unlimited)
• Maximum plugin-specific metrics: varies by plugin

Network:

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

Unsupported Scenarios

Not Supported:

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

Troubleshooting Requirements Issues

Check Python Version

python3 --version

Expected: Python 3.8.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 SystemD

systemctl --version
systemctl list-units --type=service | grep statusradar

Next Steps

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