{"id":35054470,"url":"https://github.com/ruaan-deysel/unraid-management-agent","last_synced_at":"2026-05-16T03:27:39.448Z","repository":{"id":322201460,"uuid":"1068872709","full_name":"ruaan-deysel/unraid-management-agent","owner":"ruaan-deysel","description":"Go-based Unraid plugin providing REST API and WebSocket interfaces for real-time system monitoring, Docker/VM control, and comprehensive hardware metrics","archived":false,"fork":false,"pushed_at":"2026-01-13T04:00:54.000Z","size":95398,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T06:43:54.904Z","etag":null,"topics":["rest-api","unraid","websocket"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruaan-deysel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ruaan-deysel","buy_me_a_coffee":"MrD3y5eL"}},"created_at":"2025-10-03T03:30:30.000Z","updated_at":"2026-01-13T04:01:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ruaan-deysel/unraid-management-agent","commit_stats":null,"previous_names":["domalab/unraid-management-agent","ruaan-deysel/unraid-management-agent"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/ruaan-deysel/unraid-management-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruaan-deysel%2Funraid-management-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruaan-deysel%2Funraid-management-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruaan-deysel%2Funraid-management-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruaan-deysel%2Funraid-management-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruaan-deysel","download_url":"https://codeload.github.com/ruaan-deysel/unraid-management-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruaan-deysel%2Funraid-management-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rest-api","unraid","websocket"],"created_at":"2025-12-27T09:45:58.447Z","updated_at":"2026-04-11T05:18:28.672Z","avatar_url":"https://github.com/ruaan-deysel.png","language":"Go","funding_links":["https://github.com/sponsors/ruaan-deysel","https://buymeacoffee.com/MrD3y5eL"],"categories":[],"sub_categories":[],"readme":"[![GitHub Release](https://img.shields.io/github/v/release/ruaan-deysel/unraid-management-agent?label=latest%20release)](https://github.com/ruaan-deysel/unraid-management-agent/releases/latest)\n[![GitHub Last Commit](https://img.shields.io/github/last-commit/ruaan-deysel/unraid-management-agent)](https://github.com/ruaan-deysel/unraid-management-agent/commits/main)\n[![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/ruaan-deysel/unraid-management-agent)](https://github.com/ruaan-deysel/unraid-management-agent)\n[![GitHub issues](https://img.shields.io/github/issues/ruaan-deysel/unraid-management-agent)](https://github.com/ruaan-deysel/unraid-management-agent/issues)\n[![License](https://img.shields.io/github/license/ruaan-deysel/unraid-management-agent)](./LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ruaan-deysel/unraid-management-agent)\n\n# Unraid Management Agent\n\nA Go-based plugin for Unraid that exposes comprehensive system monitoring and control via REST API and WebSockets.\n\n## ⚠️ Important: Third-Party Plugin Notice\n\n**This is a community-developed third-party plugin and is NOT an official Unraid product.**\n\n### Relationship to Official Unraid API\n\n- **Official Unraid API**: Unraid OS 7.2+ includes an official **GraphQL-based API** as part of the core operating system. This is the official API provided and supported by Lime Technology (the creators of Unraid).\n\n- **This Plugin**: The Unraid Management Agent is a **separate, independent third-party plugin** that provides a **REST API and WebSocket interface** for system monitoring and control. It is developed and maintained by the community, not by Lime Technology.\n\n### Key Differences\n\n| Feature          | Official Unraid API        | This Plugin (Unraid Management Agent)         |\n| ---------------- | -------------------------- | --------------------------------------------- |\n| **Developer**    | Lime Technology (Official) | Community (Third-Party)                       |\n| **API Type**     | GraphQL                    | REST API + WebSocket                          |\n| **Availability** | Built into Unraid OS 7.2+  | Separate plugin installation required         |\n| **Support**      | Official Unraid support    | Community support                             |\n| **Purpose**      | Official system API        | Alternative/complementary monitoring solution |\n\n### When to Use This Plugin\n\nYou might choose this plugin if you:\n\n- ✅ **Prefer REST API**: You want a traditional REST API instead of GraphQL\n- ✅ **Need WebSocket Support**: You require real-time event streaming via WebSockets\n- ✅ **Want Specific Features**: This plugin offers specific monitoring and control features tailored to community needs\n- ✅ **Compatibility**: You need an API solution that works alongside or independently of the official API\n\n### Coexistence with Official API\n\nThis plugin **can coexist** with the official Unraid API. They operate independently and do not conflict with each other. You can use both simultaneously if your use case requires it.\n\n### Official Unraid API Documentation\n\nFor information about the official Unraid GraphQL API, please refer to:\n\n- [Unraid Official Documentation](https://docs.unraid.net/)\n- Unraid OS 7.2+ release notes and API documentation\n\n---\n\n## 📚 Documentation\n\n**[→ Complete Documentation](docs/README.md)** - Start here for guides, API reference, and integration examples\n\n### Quick Links\n\n- **Getting Started**\n\n  - [Installation Guide](docs/guides/installation.md) - Install the plugin\n  - [Quick Start](docs/guides/quick-start.md) - First API calls\n  - [Configuration](docs/guides/configuration.md) - Customize settings\n  - [System Requirements](docs/guides/system-requirements.md) - Requirements \u0026 dependencies\n\n- **API Reference**\n\n  - [REST API](docs/api/rest-api.md) - Complete HTTP API reference (57 endpoints)\n  - [WebSocket Events](docs/api/websocket-events.md) - Real-time events\n  - [Prometheus Metrics](docs/api/prometheus.md) - Metrics endpoint (41 metrics)\n\n- **Integrations**\n\n  - [MCP (AI Agents)](docs/integrations/mcp.md) - Model Context Protocol (54 tools)\n  - [MQTT](docs/integrations/mqtt.md) - MQTT publishing for IoT\n  - [Grafana Dashboards](docs/integrations/grafana.md) - Monitoring dashboards\n  - [Home Assistant](docs/integrations/home-assistant.md) - Smart home integration\n\n- **Development**\n\n  - [Contributing](docs/development/contributing.md) - Contribution guidelines\n  - [Code Quality](docs/development/code-quality.md) - Linting \u0026 pre-commit hooks\n  - [Testing](docs/development/testing.md) - Test suite documentation\n  - [Architecture](docs/development/architecture.md) - Technical architecture\n\n- **Troubleshooting**\n  - [Common Issues](docs/troubleshooting/common-issues.md) - Solutions to common problems\n  - [Diagnostics](docs/troubleshooting/diagnostics.md) - Diagnostic commands\n  - [Hardware Compatibility](docs/troubleshooting/hardware-compatibility.md) - Hardware-specific fixes\n\n---\n\n## Features\n\n### Real-time Monitoring\n\n- **System Information**: CPU usage, RAM, temperatures, uptime, hostname\n- **Array Status**: Array state, parity status, disk counts\n- **Disk Information**: Per-disk metrics, SMART data, temperatures, space usage\n- **Network Interfaces**: Interface status, bandwidth, IP addresses, MAC addresses\n- **Docker Containers**: Container list, status, resource usage (via Docker SDK)\n- **Virtual Machines**: VM list, state, resource allocation (via libvirt API)\n- **UPS Status**: Battery level, runtime, power state\n- **GPU Metrics**: GPU utilization, memory, temperature\n- **User Shares**: Share list, space usage, paths\n- **ZFS Pools/Datasets**: ZFS pool health, datasets, snapshots, ARC stats\n- **Notifications**: System alerts, warnings, and info messages\n\n### Control Operations\n\n- **Docker**: Start, stop, restart, pause, unpause containers\n- **Virtual Machines**: Start, stop, restart, pause, resume, hibernate, force-stop VMs\n- **Array**: Start, stop array operations\n- **Parity**: Start, stop, pause, resume parity checks\n- **Disk**: Spin up, spin down individual disks\n- **User Scripts**: Execute User Scripts plugin scripts\n\n### Communication Protocols\n\n- **REST API**: HTTP endpoints for synchronous queries\n- **WebSocket**: Real-time event streaming for live updates\n- **Prometheus**: Native `/metrics` endpoint for Grafana/monitoring integration (41 metrics)\n- **MQTT**: Event publishing to MQTT brokers for IoT integration and Home Assistant\n- **MCP (Model Context Protocol)**: AI agent integration for LLM-powered monitoring and control (54 tools)\n\n## Architecture\n\n### Event-Driven Design\n\nThe agent uses a pubsub event bus for decoupled, real-time data flow:\n\n```\nCollectors → Event Bus → API Server Cache → REST Endpoints\n                        ↓                  ↓\n                 WebSocket Hub      MCP Server → AI Agents\n                        ↓\n                 Connected Clients\n```\n\n### Native API Integration\n\nFor optimal performance, collectors use native Go libraries instead of shell commands:\n\n| Component  | Library                              | Description                          |\n| ---------- | ------------------------------------ | ------------------------------------ |\n| **Docker** | `github.com/moby/moby/client`        | Docker Engine SDK for container data |\n| **VMs**    | `github.com/digitalocean/go-libvirt` | Native libvirt bindings for VM data  |\n| **System** | Direct `/proc`, `/sys` access        | Kernel interfaces for metrics        |\n\n### Components\n\n#### Collectors\n\nData collectors run at configurable intervals (defaults shown):\n\n- **System Collector** (15s): CPU, RAM, temps, uptime\n- **Array Collector** (30s): Array state and parity info\n- **Disk Collector** (30s): Per-disk metrics\n- **Network Collector** (30s): Interface status and statistics\n- **Docker Collector** (30s): Container information\n- **VM Collector** (30s): Virtual machine data\n- **UPS Collector** (60s): UPS status\n- **GPU Collector** (60s): GPU metrics\n- **Share Collector** (60s): User share information\n- **Hardware Collector** (5m): Hardware info (rarely changes)\n- **Registration Collector** (5m): License info (rarely changes)\n\n#### API Server\n\n- Maintains in-memory cache of latest collector data\n- Serves REST endpoints for instant responses\n- Broadcasts events to WebSocket clients\n- Implements CORS, logging, and recovery middleware\n\n#### Orchestrator\n\nCoordinates the entire application lifecycle:\n\n- Initializes all collectors\n- Starts API server subscriptions before collectors\n- Manages graceful shutdown\n\n## System Requirements and Dependencies\n\n**Important:** The Unraid Management Agent has **NO external plugin dependencies**. It collects data directly from system sources.\n\nFor detailed information, see:\n\n- **[System Requirements \u0026 Dependencies](docs/guides/system-requirements.md)** - Complete requirements and data collection methods\n- **[Quick Start Guide](docs/guides/quick-start.md)** - Get started quickly\n- **[Diagnostic Commands](docs/troubleshooting/diagnostics.md)** - Troubleshooting guide\n\n### Quick Prerequisites\n\n- Unraid 6.9+ (tested on Unraid 7.x)\n- Port 8043 available (configurable)\n- No other plugins required\n\n### Via Community Applications (Recommended)\n\n**Coming Soon**: This plugin will be available in the Unraid Community Applications store.\n\nFor now, you can install manually using the plugin URL:\n\n1. Open your Unraid Web UI\n2. Navigate to **Plugins** → **Install Plugin**\n3. Enter the plugin URL:\n\n   ```\n   https://raw.githubusercontent.com/ruaan-deysel/unraid-management-agent/main/unraid-management-agent.plg\n   ```\n\n4. Click **Install**\n5. The plugin will automatically:\n   - Download and extract the package\n   - Create default configuration\n   - Start the service on port 8043\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/ruaan-deysel/unraid-management-agent.git\ncd unraid-management-agent\n\n# Install dependencies\nmake deps\n\n# Build for Unraid (Linux/amd64)\nmake release\n\n# Create plugin package\nmake package\n```\n\n## System Compatibility\n\n**Important Notice:** This plugin was developed and tested on a specific Unraid system configuration. While we strive for broad compatibility, **there is a possibility that the plugin may not function correctly on all hardware configurations** due to variations in:\n\n- **CPU Architectures**: Different CPU models, instruction sets, and architectures (Intel vs AMD, different generations)\n- **Disk Controllers and Storage Devices**: Various RAID controllers, HBA cards, SAS/SATA controllers, NVMe configurations\n- **GPU Models and Drivers**: Different GPU vendors (NVIDIA, AMD, Intel), driver versions, and passthrough configurations\n- **Network Interfaces**: Various network cards, bonding configurations, VLANs, and bridge setups\n- **UPS Models and Monitoring Tools**: Different UPS brands, monitoring software (apcupsd, nut), and communication protocols\n- **Docker and VM Configurations**: Different Docker API versions, libvirt socket configurations, and virtualization setups\n\n### What This Means for You\n\n- ✅ **If it works on your system**: Great! The plugin should continue to work reliably.\n- ⚠️ **If you encounter issues**: This is likely due to hardware/configuration differences. See the [Contributing](#contributing) section below for how you can help improve compatibility.\n- 🔧 **Debugging across different hardware**: As a single maintainer, it's challenging to test and debug across all possible hardware configurations. Community contributions are essential for broader compatibility.\n\n### Tested Configuration\n\nThis plugin has been developed and tested on the following configuration:\n\n- **Unraid Version**: 7.x\n- **Plugin Version**: 2025.11.0\n- **Architecture**: Linux/amd64\n- **Primary Testing**: REST API endpoints, WebSocket events, Docker/VM control operations\n\n**Note:** This configuration represents the primary development and testing environment. Your mileage may vary on different hardware setups.\n\n## Usage\n\n### Starting the Agent\n\n```bash\n# Standard mode\n./unraid-management-agent boot\n\n# Debug mode (stdout logging)\n./unraid-management-agent boot --debug\n\n# Custom port\n./unraid-management-agent boot --port 8043\n```\n\n### REST API Endpoints\n\nBase URL: `http://localhost:8043/api/v1`\n\n#### Monitoring Endpoints\n\n- `GET /health` - Health check\n- `GET /system` - System information\n- `GET /array` - Array status\n- `GET /disks` - List all disks\n- `GET /disks/{id}` - Get specific disk info\n- `GET /network` - Network interface list\n- `GET /shares` - List user shares\n- `GET /docker` - List Docker containers\n- `GET /docker/{id}` - Get container details\n- `GET /vm` - List virtual machines\n- `GET /vm/{id}` - Get VM details\n- `GET /ups` - UPS status\n- `GET /gpu` - GPU metrics\n- `GET /logs` - List log files or get log content\n- `GET /logs/{filename}` - Get specific log file by name\n\n#### Settings \u0026 Configuration Endpoints\n\n- `GET /settings/disk-thresholds` - Global disk temperature warning/critical thresholds\n- `GET /settings/mover` - Mover schedule, thresholds, and running status\n- `GET /settings/services` - Docker and VM Manager enabled/disabled status\n- `GET /settings/network-services` - Network services status (SMB, NFS, FTP, SSH, VPN, etc.)\n- `GET /array/parity-check/schedule` - Parity check schedule configuration\n- `GET /plugins` - List installed plugins with versions and update status\n- `GET /updates` - OS and plugin update availability\n- `GET /system/flash` - USB flash boot drive health statistics\n\n#### Control Endpoints\n\n- `POST /docker/{id}/start` - Start container\n- `POST /docker/{id}/stop` - Stop container\n- `POST /docker/{id}/restart` - Restart container\n- `POST /docker/{id}/pause` - Pause container\n- `POST /docker/{id}/unpause` - Unpause container\n- `POST /vm/{id}/start` - Start VM\n- `POST /vm/{id}/stop` - Stop VM\n- `POST /vm/{id}/restart` - Restart VM\n- `POST /vm/{id}/pause` - Pause VM\n- `POST /vm/{id}/resume` - Resume VM\n- `POST /vm/{id}/hibernate` - Hibernate VM\n- `POST /vm/{id}/force-stop` - Force stop VM\n\n### WebSocket Connection\n\nConnect to `ws://localhost:8043/api/v1/ws` to receive real-time events:\n\n```javascript\nconst ws = new WebSocket(\"ws://localhost:8043/api/v1/ws\");\n\nws.onmessage = (event) =\u003e {\n  const data = JSON.parse(event.data);\n  console.log(\"Event received:\", data);\n};\n```\n\n### Prometheus Metrics\n\nThe agent exposes **41 metrics** in Prometheus format at `/metrics`:\n\n```bash\n# Scrape metrics\ncurl http://localhost:8043/metrics\n```\n\nAvailable metrics include:\n\n- **Array**: state, capacity, usage, parity status\n- **CPU**: usage, temperature\n- **Memory**: total, used, usage percentage\n- **Disks**: size, free space, temperature, SMART status, standby state\n- **Docker**: container counts, states\n- **VMs**: VM counts, states\n- **GPU**: utilization, temperature, memory, power\n- **UPS**: battery charge, load, runtime, status\n- **Shares**: share counts, usage\n- **Services**: service states\n- **Parity**: parity validity, check progress\n- **System**: uptime, info labels\n\nFor Grafana integration, see [docs/integrations/grafana.md](docs/integrations/grafana.md).\n\n### MQTT Publishing\n\nPublish system events to MQTT brokers for IoT integration and Home Assistant:\n\n```bash\n# Enable MQTT publishing\n./unraid-management-agent boot \\\n  --mqtt-enabled \\\n  --mqtt-broker \"192.168.1.100\" \\\n  --mqtt-port 1883 \\\n  --mqtt-topic-prefix \"unraid/tower\"\n\n# With authentication\n./unraid-management-agent boot \\\n  --mqtt-enabled \\\n  --mqtt-broker \"mqtt.example.com\" \\\n  --mqtt-port 1883 \\\n  --mqtt-username \"unraid\" \\\n  --mqtt-password \"secret\" \\\n  --mqtt-use-tls \\\n  --mqtt-topic-prefix \"homelab/unraid\"\n\n# Home Assistant auto-discovery\n./unraid-management-agent boot \\\n  --mqtt-enabled \\\n  --mqtt-broker \"192.168.1.100\" \\\n  --mqtt-home-assistant\n```\n\n**Published Events:**\n\n- System metrics (CPU, RAM, temperatures)\n- Array status and capacity\n- Disk information and health\n- Container and VM states\n- Share usage\n- UPS status\n- GPU metrics\n- Network statistics\n- Notifications\n\n**Configuration via REST API:**\n\n```bash\n# Check MQTT status\ncurl http://localhost:8043/api/v1/mqtt/status\n\n# Test MQTT connection\ncurl -X POST http://localhost:8043/api/v1/mqtt/test\n\n# Publish custom message\ncurl -X POST http://localhost:8043/api/v1/mqtt/publish \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"topic\":\"custom/topic\",\"payload\":{\"message\":\"hello\"},\"retained\":false}'\n```\n\n### MCP (Model Context Protocol)\n\nThe agent includes an MCP endpoint for AI agent integration at `POST /mcp`:\n\n```bash\n# List available MCP tools\ncurl -X POST http://localhost:8043/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}'\n\n# Get system info via MCP\ncurl -X POST http://localhost:8043/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/call\",\"params\":{\"name\":\"get_system_info\",\"arguments\":{}},\"id\":1}'\n```\n\nFor full MCP documentation including all 54 tools, 5 resources, and 3 prompts, see [docs/integrations/mcp.md](docs/integrations/mcp.md).\n\n### Example API Usage\n\n```bash\n# Get system information\ncurl http://localhost:8043/api/v1/system\n\n# Get network interfaces\ncurl http://localhost:8043/api/v1/network\n\n# List all disks\ncurl http://localhost:8043/api/v1/disks\n\n# Start a Docker container\ncurl -X POST http://localhost:8043/api/v1/docker/nginx/start\n\n# Stop a VM\ncurl -X POST http://localhost:8043/api/v1/vm/Ubuntu/stop\n```\n\n## Development\n\n### Project Structure\n\n```\ndaemon/\n├── cmd/              # CLI commands\n├── common/           # Constants (intervals, paths)\n├── domain/           # Core types (Context, Config)\n├── dto/              # Data transfer objects\n├── lib/              # Utilities (shell execution)\n├── logger/           # Logging wrapper\n└── services/\n    ├── api/          # HTTP server, handlers, WebSocket\n    ├── collectors/   # Data collection subsystems\n    └── controllers/  # Control operations\n\nmeta/                 # Unraid plugin metadata\nscripts/              # Developer setup helpers\ntests/                # Unit and integration tests\n```\n\n### Building and Testing\n\n```bash\n# Install dependencies\nmake deps\n\n# Build for local development\nmake local\n\n# Run tests\nmake test\n\n# Generate coverage report\nmake test-coverage\n\n# Run specific test\ngo test -v ./daemon/services/api/handlers_test.go\n\n# Clean build artifacts\nmake clean\n```\n\n### Dev Container (VS Code / GitHub Codespaces)\n\n- Prereqs: Docker (or compatible), VS Code with Dev Containers extension — or just open in GitHub Codespaces.\n- Open the repo in VS Code and run `Dev Containers: Reopen in Container`.\n- Uses [Dev Container Features](https://containers.dev/features) for Go 1.26, Node.js 22, Python 3.12, and GitHub CLI.\n- Ansible + ansible-lint included for deployment automation (`ansible/` directory).\n- Go tools auto-installed: golangci-lint, gosec, govulncheck, swag, goimports.\n- VS Code extensions auto-installed: Go, Python, Ansible, Makefile Tools, Prettier, GitHub Copilot.\n- Lifecycle: `onCreateCommand` installs tools, `updateContentCommand` refreshes deps, `postCreateCommand` sets up pre-commit hooks.\n- Run `make test` to verify after attach.\n\n## Configuration\n\n### Settings Page\n\nConfigure the plugin through the Unraid web UI:\n\n1. Navigate to **Settings** → **Unraid Management Agent**\n2. Adjust settings as needed:\n\n   - **Port**: API server port (default: 8043)\n   - **Collection Intervals**: How often each data type is collected\n\n3. Click **Apply** to save changes (service restarts automatically)\n\n### Collection Intervals\n\nThe settings page provides dropdown menus to configure how often data is collected. Default values are optimized for low power consumption:\n\n| Category     | Collectors                                           | Default    |\n| ------------ | ---------------------------------------------------- | ---------- |\n| **Fast**     | System Metrics                                       | 15 seconds |\n| **Standard** | Array, Disk, Docker, VM, Network, ZFS, Notifications | 30 seconds |\n| **Moderate** | UPS, GPU, Shares, Unassigned Devices                 | 1 minute   |\n| **Slow**     | Hardware Info, License Info                          | 5 minutes  |\n\n**⚡ Power Note:** Lower intervals provide faster updates but increase CPU usage and power consumption. On Intel systems with many Docker containers, aggressive intervals (5-10s) can increase idle power by 15-20W.\n\n### Advanced: Manual Configuration\n\nFor automation or headless setups, you can edit the config file directly:\n\n```\n/boot/config/plugins/unraid-management-agent/config.cfg\n```\n\nChanges require a service restart:\n\n```bash\n/usr/local/emhttp/plugins/unraid-management-agent/scripts/stop\n/usr/local/emhttp/plugins/unraid-management-agent/scripts/start\n```\n\n### Logging\n\nThe agent uses log rotation with the following settings:\n\n- **Location**: `/var/log/unraid-management-agent.log`\n- **Max Size**: 5 MB per file\n- **Backups**: 1 backup file (older backups are automatically deleted)\n- **Age-based Retention**: 1 day (backup files older than 1 day are deleted)\n- **Log Levels**: DEBUG, INFO, WARNING, ERROR (configurable via `--log-level` CLI flag)\n- **Default Level**: INFO\n- **Auto Cleanup**: On startup, old rotated log files from previous versions are automatically removed\n\nIn debug mode (`--debug` or `--log-level debug`), logs are written to stdout for immediate visibility.\n\n## Troubleshooting\n\n### No Data Returned\n\nIf endpoints return empty or default data:\n\n1. Check that the agent is running: `ps aux | grep unraid-management-agent`\n2. Review logs: `tail -f /var/log/unraid-management-agent.log`\n3. Verify collection intervals haven't expired\n4. Ensure proper permissions for system file access\n\n### Collectors Not Running\n\n1. Enable debug mode: `./unraid-management-agent boot --debug`\n2. Check for panic recovery messages in logs\n3. Verify event bus subscriptions are initialized before collectors start\n\n### WebSocket Connection Issues\n\n1. Verify WebSocket hub is running: check logs for \"API server subscriptions started\"\n2. Test REST endpoints first to isolate API vs WebSocket issues\n3. Check browser console for connection errors\n\n## API Response Examples\n\n### System Information\n\n```json\n{\n  \"hostname\": \"Tower\",\n  \"version\": \"2025.10.03\",\n  \"cpu_usage\": 12.5,\n  \"ram_usage\": 45.2,\n  \"temperature\": 42.0,\n  \"uptime\": 86400,\n  \"timestamp\": \"2025-10-02T08:00:00Z\"\n}\n```\n\n### Network Interfaces\n\n```json\n[\n  {\n    \"name\": \"eth0\",\n    \"mac_address\": \"00:11:22:33:44:55\",\n    \"ip_address\": \"192.168.1.100\",\n    \"speed_mbps\": 1000,\n    \"state\": \"up\",\n    \"bytes_received\": 1234567890,\n    \"bytes_sent\": 987654321,\n    \"packets_received\": 5000000,\n    \"packets_sent\": 4500000,\n    \"errors_received\": 0,\n    \"errors_sent\": 0,\n    \"timestamp\": \"2025-10-02T08:00:00Z\"\n  }\n]\n```\n\n### Array Status\n\n```json\n{\n  \"state\": \"STARTED\",\n  \"num_disks\": 8,\n  \"num_data_disks\": 6,\n  \"num_parity_disks\": 2,\n  \"sync_percent\": 100.0,\n  \"parity_valid\": true,\n  \"timestamp\": \"2025-10-02T08:00:00Z\"\n}\n```\n\n## Contributing\n\nContributions are welcome and greatly appreciated! This project benefits from community involvement, especially for improving hardware compatibility across different Unraid configurations.\n\n### Code Quality Standards\n\nThis project enforces **zero tolerance** for code quality issues:\n\n- ✅ No linting warnings or errors\n- ✅ No security vulnerabilities (medium+ severity)\n- ✅ All tests must pass with race detection\n- ✅ Code must be properly formatted (gofmt/goimports)\n\nWe use **pre-commit hooks** to automatically enforce these standards.\n\n#### Quick Setup\n\n```bash\n# Automated setup (recommended)\n./scripts/setup-pre-commit.sh\n\n# Or manual setup\npip install pre-commit\nmake pre-commit-install\n```\n\nPre-commit will automatically run checks before each commit. See [docs/development/code-quality.md](docs/development/code-quality.md) for detailed documentation.\n\n#### Available Commands\n\n```bash\nmake pre-commit-run   # Run all pre-commit checks\nmake lint             # Run golangci-lint only\nmake security-check   # Run security scans\nmake test-coverage    # Run tests with coverage\n```\n\n### How to Contribute\n\n#### General Contributions\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/your-feature-name`)\n3. Commit your changes with descriptive messages\n4. Add tests for new functionality\n5. Ensure all checks pass: `make pre-commit-run \u0026\u0026 make test-coverage`\n6. Submit a pull request with a clear description of your changes\n\n**Important**: Pre-commit hooks will block commits that don't meet quality standards. Fix all issues before committing.\n\n#### Hardware Compatibility Contributions\n\n**Encountered compatibility issues on your system?** You can help improve the plugin for everyone!\n\nIf the plugin doesn't work correctly on your hardware configuration:\n\n1. **Fork the Repository**: Create your own fork to work on fixes\n2. **Identify the Issue**: Determine which component is failing (disk detection, GPU metrics, UPS monitoring, etc.)\n3. **Make Necessary Changes**: Modify the code to support your hardware configuration\n   - Update collectors in `daemon/services/collectors/` for data collection issues\n   - Update parsers in `daemon/lib/` for command output parsing issues\n   - Add fallback logic for different hardware variations\n4. **Test Thoroughly**: Ensure your changes work on your system and don't break existing functionality\n   - Run the full test suite: `make test`\n   - Test all affected API endpoints\n   - Verify WebSocket events are working correctly\n5. **Document Your Changes**: In your pull request, include:\n   - **Hardware Configuration**: CPU model, disk controllers, GPU model, UPS model, etc.\n   - **Issue Description**: What wasn't working and why\n   - **Solution Implemented**: How your changes fix the issue\n   - **Testing Performed**: What you tested and the results\n   - **Unraid Version**: Your Unraid version number\n\n**Example PR Description:**\n\n```\nHardware: AMD Ryzen 9 5950X, LSI 9300-8i HBA, NVIDIA RTX 3080\nIssue: GPU temperature not detected due to different nvidia-smi output format\nSolution: Added parsing for alternative nvidia-smi XML format\nTesting: Verified GPU metrics endpoint returns correct data, all tests pass\nUnraid Version: 7.2\n```\n\n### Why Community Contributions Matter\n\nAs a single maintainer, it's challenging to:\n\n- Test across all possible hardware configurations\n- Debug issues on systems I don't have access to\n- Support every variation of disk controllers, GPUs, UPS models, etc.\n\n**Your contributions help make this plugin work for everyone!** Even small fixes for specific hardware configurations are valuable and appreciated.\n\n### Areas Where Contributions Are Especially Helpful\n\n- 🔧 **Hardware-Specific Fixes**: Support for different disk controllers, GPU models, UPS brands\n- 📊 **Data Collection Improvements**: Better parsing of system commands for different hardware\n- 🧪 **Testing**: Testing on different Unraid versions and hardware configurations\n- 📝 **Documentation**: Improving docs, adding examples, documenting edge cases\n- 🐛 **Bug Fixes**: Fixing issues you encounter on your system\n- ✨ **New Features**: Adding support for additional hardware or metrics\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruaan-deysel%2Funraid-management-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruaan-deysel%2Funraid-management-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruaan-deysel%2Funraid-management-agent/lists"}