MRTG Remote Sensor

Modern PHP 8.1+ System Monitoring for MRTG

A type-safe, cross-platform web service that provides system metrics (CPU, memory, disk, battery, etc.) in MRTG-compatible format. Built as a simpler alternative to SNMP for monitoring remote servers via HTTP(S) endpoints.

Features

17 Sensor Types: CPU, Memory, Disk, Battery (6 types), Process count, Folder operations, Network ping
Cross-Platform: Windows, Linux, macOS, BusyBox (Synology NAS)
Modern PHP 8.1+: Enums, readonly properties, strict types, match expressions
Type-Safe: PHPStan level 8 analysis
Tested: PHPUnit integration and unit tests
PSR-4 Autoloading: Composer-based dependency management
100% Backward Compatible: Existing MRTG configs work unchanged

Requirements

PHP 8.1 or higher
Composer
Web server (Apache, Nginx, built-in PHP server)
Shell access for system commands (exec() enabled)

Installation

1. Install Dependencies

composer install

2. Configure Web Server

Option A: Point Document Root to `public/`

For Apache or Nginx, set the document root to the public/ directory:

DocumentRoot /path/to/mrtg_remote_sensor/public

Option B: PHP Built-in Server (Development)

php -S localhost:8080 -t public

Option C: Symlink (Quick Setup)

ln -s public/index.php index.php

3. Test Installation

# CPU usage
curl "http://localhost/index.php?key=cpu"

# Memory usage
curl "http://localhost/index.php?key=mem"

# Disk usage for root
curl "http://localhost/index.php?key=disk&param=/"

Usage

Available Sensors

Sensor Key	Description	Parameters	Example
`cpu`	CPU load (1-min average)	-	`?key=cpu`
`cpu%`	CPU percentage	-	`?key=cpu%`
`mem`	Memory usage (bytes)	-	`?key=mem`
`mem%`	Memory percentage	-	`?key=mem%`
`disk`	Disk usage (bytes)	`param=/path`	`?key=disk&param=/`
`disk%`	Disk percentage	`param=/path`	`?key=disk%&param=/home`
`battery`	Battery percentage (macOS)	-	`?key=battery`
`battery%`	Battery remaining (macOS)	-	`?key=battery%`
`battery-`	Battery used (macOS)	-	`?key=battery-`
`batt_volt`	Battery voltage (macOS)	-	`?key=batt_volt`
`batt_amp`	Battery amperage (macOS)	-	`?key=batt_amp`
`batt_cycles`	Battery cycles (macOS)	-	`?key=batt_cycles`
`proc`	Process count	`param=filter`	`?key=proc&param=apache`
`foldersize`	Folder size (MB)	`param=/path`	`?key=foldersize&param=/var/log`
`filecount`	File count	`param=/path`	`?key=filecount&param=/tmp`
`foldercount`	Subfolder count	`param=/path`	`?key=foldercount&param=/etc`
`pingtime`	Ping time (ms)	`param=host`	`?key=pingtime&param=8.8.8.8`

URL Parameters

key (required): Sensor type
param (optional): Sensor-specific parameter (path, hostname, filter)
options (optional): Additional options (comma-separated key=value)
config=1 (optional): Return full MRTG configuration block
debug=1 (optional): Enable debug output

Options Parameter

For file/folder operations, use options for filtering:

?key=filecount&param=/var&options=recursive=1,name=*.log

Available options:

recursive=1: Enable recursive operations
mtime=<value>: Filter by modification time (passed to find)
name=<pattern>: Filter by filename pattern

MRTG Integration

Basic Configuration

Add to your mrtg.cfg:

Target[server_cpu]: `curl -s "http://server/index.php?key=cpu"`
Title[server_cpu]: Server: CPU Usage
PageTop[server_cpu]: <h1>Server: CPU Usage</h1>
MaxBytes[server_cpu]: 500
Options[server_cpu]: gauge,growright,nobanner

Auto-Generate Configuration

Add config=1 to get a complete MRTG configuration block:

curl "http://server/index.php?key=cpu&config=1"

Output:

Target[server_cpu_abc123]: `curl -s "http://server/index.php?key=cpu"`
Title[server_cpu_abc123]: server: CPU Usage
PageTop[server_cpu_abc123]: <h1>server: CPU Usage</h1>
ShortLegend[server_cpu_abc123]:
Options[server_cpu_abc123]: gauge,growright,nobanner
MaxBytes[server_cpu_abc123]: 500
kMG[server_cpu_abc123]: k,M,G,T,P

Interactive Testing

Open public/overview.html in a browser to test all sensor types interactively.

Development

Run Tests

# All tests
composer test

# Unit tests only
vendor/bin/phpunit tests/Unit

# Integration tests only
vendor/bin/phpunit tests/Integration

Static Analysis

composer analyse

Runs PHPStan level 8 analysis on src/ directory.

Code Formatting

composer format

Applies PSR-12 coding standards using PHP-CS-Fixer.

Project Structure

.
├── public/                 # Web root
│   ├── index.php          # Entry point
│   ├── overview.html      # Interactive testing UI
│   └── view.html          # Single sensor view
├── src/                   # PSR-4 source code
│   ├── Cache/            # File caching
│   ├── Command/          # Command execution
│   ├── Enum/             # Type-safe enums
│   ├── Http/             # Request/Response
│   ├── OS/               # OS abstraction layer
│   ├── Sensor/           # Sensor logic & results
│   └── Output/           # MRTG formatting
├── tests/                # PHPUnit tests
│   ├── Unit/            # Unit tests
│   └── Integration/     # Integration tests
├── var/                  # Runtime data
│   └── cache/           # Cache files
├── composer.json         # Dependencies
├── phpunit.xml          # Test configuration
├── phpstan.neon         # Static analysis config
└── .php-cs-fixer.php    # Code style config

Architecture

Modern PHP 8.1+ Features

Enums (PHP 8.1+): SensorType, OSType for type safety
Readonly Properties (PHP 8.1+): Immutable SensorResult value objects
#[\Override] Attribute (PHP 8.1+): Safe method overriding
Constructor Property Promotion (PHP 8.0+): Concise dependency injection
Match Expressions (PHP 8.0+): Clean sensor routing
Union Types (PHP 8.0+): Flexible type hints (int|float|string)
Strict Types: declare(strict_types=1) everywhere
Typed Properties (PHP 7.4+): Full type coverage

Core Components

Namespace: `MrtgSensor\`

Sensor (Sensor\Sensor): Main business logic, all 17 sensor implementations
OSTools (OS\OSTools): Abstract base for OS-specific implementations
- LinuxTools: Linux/Unix commands
- DarwinTools: macOS with battery support
- WindowsTools: Windows via wmic
- BusyBoxTools: Synology NAS
OSDetector (OS\OSDetector): Auto-detect operating system
FileCache (Cache\FileCache): Command output caching
CommandExecutor (Command\CommandExecutor): Shell command execution
SensorResult (Sensor\SensorResult): Immutable sensor data (15 properties)
MrtgFormatter (Output\MrtgFormatter): MRTG output generation
Request (Http\Request): Readonly request object
Response (Http\Response): Immutable response with factory methods

Platform Support

Linux

Commands: sys_getloadavg(), free, df, du, ps, uptime
Full support for all sensor types except battery

macOS (Darwin)

Commands: sysctl, vm_stat, df, du, system_profiler, ps
Full battery support via system_profiler SPPowerDataType

Windows

Commands: wmic (CPU, memory, disk, processes)
Folder operations require PHP COM extension

BusyBox (Synology NAS)

Detected via /usr/syno/synoman/
Limited command set with fallbacks

Security

Read-only operations: No write/modify commands executed
No root/sudo: All commands run with web server privileges
Input sanitization: Sensor::sanitize() removes shell metacharacters
Type safety: Strict types and enums prevent type juggling
Validated parameters: Enum validation for sensor types

Recommended: Restrict access via web server configuration (IP whitelist, basic auth).

Performance

File-based caching: Command output cached (30-3600 seconds)
Lazy loading: PSR-4 autoloading loads classes on demand
Efficient commands: OS-specific optimizations
Automatic cleanup: Expired cache files removed

Migration from Legacy PHP 5.x

The modernized version maintains 100% API compatibility with the legacy version:

Same URL parameters and sensor keys
Same MRTG 4-line output format
Existing MRTG configurations work unchanged
Simply run composer install and point web server to public/

Note: Requires PHP 8.1+ (uses enums, readonly properties, and match expressions).

See MODERNIZATION_SUMMARY.md for detailed migration information.

Troubleshooting

Commands Not Found

On macOS, free command doesn't exist (expected). The DarwinTools class uses vm_stat instead.

Permission Denied

Ensure PHP can execute shell commands:

php -r "echo exec('whoami');"

If blocked, check disable_functions in php.ini.

Cache Directory

Cache is stored in var/cache/. Ensure it's writable:

chmod 755 var/cache

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality

Run quality checks:

composer test
composer analyse
composer format

Submit a pull request

License

This project is open source. Check LICENSE file for details.

Credits

Original concept: Simple alternative to SNMP for MRTG
Modernization: PHP 8.1+ refactoring with strict types and testing
Powered by: MRTG (Multi Router Traffic Grapher)

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github/workflows		.github/workflows
PRPs		PRPs
docs		docs
public		public
site		site
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
VERSION.md		VERSION.md
composer.json		composer.json
mkdocs.yml		mkdocs.yml
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml
serve.sh		serve.sh
unsplash.sensor.jpg		unsplash.sensor.jpg

License

cinemapub/mrtg_remote_sensor

Folders and files

Latest commit

History

Repository files navigation

MRTG Remote Sensor

Features

Requirements

Installation

1. Install Dependencies

2. Configure Web Server

Option A: Point Document Root to public/

Option B: PHP Built-in Server (Development)

Option C: Symlink (Quick Setup)

3. Test Installation

Usage

Available Sensors

URL Parameters

Options Parameter

MRTG Integration

Basic Configuration

Auto-Generate Configuration

Interactive Testing

Development

Run Tests

Static Analysis

Code Formatting

Project Structure

Architecture

Modern PHP 8.1+ Features

Core Components

Namespace: MrtgSensor\

Platform Support

Linux

macOS (Darwin)

Windows

BusyBox (Synology NAS)

Security

Performance

Migration from Legacy PHP 5.x

Troubleshooting

Commands Not Found

Permission Denied

Cache Directory

Contributing

License

Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors 2

Uh oh!

Languages

Option A: Point Document Root to `public/`

Namespace: `MrtgSensor\`