69 lines
1.9 KiB
Markdown
69 lines
1.9 KiB
Markdown
# Homelab Telemetry API (Proxmox)
|
|
|
|
This script creates a lightweight, zero-dependency REST API endpoint directly on your Proxmox host to expose real-time system metrics (CPU, RAM, Network I/O, ZFS, and VM counts).
|
|
|
|
### 1 - Configure your Variables
|
|
Before running, check your primary network interface and ZFS pool names.
|
|
Find your active interface:
|
|
```bash
|
|
ip -br a
|
|
```
|
|
Find your ZFS pool (if using ZFS):
|
|
```bash
|
|
zpool list
|
|
```
|
|
Edit `/opt/homelab-api.py` and update the configuration block at the top of the file to match your setup:
|
|
```python
|
|
PORT = 8080
|
|
IFACE = "vmbr0"
|
|
ENABLE_ZFS = True
|
|
ZPOOL = "rpool"
|
|
```
|
|
|
|
### 2 - Open the Firewall (If applicable)
|
|
If you are using the Proxmox Datacenter Firewall, you need to allow incoming TCP traffic on port `8080`.
|
|
*(Note: If your host firewall is disabled on your local LAN, you can skip this step).*
|
|
|
|
If using `ufw` on a standard Debian/Ubuntu host:
|
|
```bash
|
|
sudo ufw allow 8080/tcp
|
|
```
|
|
If using `iptables`:
|
|
```bash
|
|
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
|
|
```
|
|
|
|
### 3 - Enable and Start the Service
|
|
Ensure the script is executable and the systemd service is loaded:
|
|
```bash
|
|
sudo chmod +x /opt/homelab-api.py
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now homelab-api.service
|
|
```
|
|
|
|
### 4 - Test the Endpoint
|
|
Test the call point by using `curl` from a different machine on your network to ensure the firewall is open and the script is returning data correctly:
|
|
|
|
```bash
|
|
curl http://<your-proxmox-ip>:8080/api/homelab
|
|
```
|
|
|
|
**Expected Output:**
|
|
```json
|
|
{
|
|
"cpu": 14.5,
|
|
"ram": {"percent": 56.2, "used_gb": 18.0, "total_gb": 32.0},
|
|
"rx_mb": 0.45,
|
|
"tx_mb": 2.10,
|
|
"load_avg": [0.45, 0.51, 0.49],
|
|
"uptime_days": 14.2,
|
|
"root_disk_pct": 34.1,
|
|
"temp_c": 42.5,
|
|
"zfs_pct": 61.2,
|
|
"vms_running": 4,
|
|
"lxcs_running": 6
|
|
}
|
|
```
|
|
|
|
This endpoint can now be seamlessly consumed by your Astro/Stellar frontend dashboard, or added to **Uptime-Kuma** as a standard JSON HTTP monitor!
|