mirror of
https://github.com/ced4568/ceds-observability-stack.git
synced 2026-08-12 22:34:03 +00:00
200 lines
2.7 KiB
Markdown
200 lines
2.7 KiB
Markdown
# UniFi Exporter Setup
|
|
|
|
## Purpose
|
|
|
|
UniFi metrics are collected using **Unpoller**.
|
|
|
|
Unpoller connects to the UniFi Network application and exposes UniFi network metrics to Prometheus on port `9130`.
|
|
|
|
---
|
|
|
|
## Exporter Used
|
|
|
|
Unpoller
|
|
|
|
---
|
|
|
|
## Metrics Port
|
|
|
|
9130
|
|
|
|
---
|
|
|
|
## Step 1 Create UniFi Monitoring User
|
|
|
|
In the UniFi Network application, create a local monitoring user.
|
|
|
|
Recommended settings:
|
|
|
|
Username: prometheus
|
|
Role: Read-only or limited admin
|
|
|
|
Do not commit the password to GitHub.
|
|
|
|
---
|
|
|
|
## Step 2 Run UniFi Exporter / Unpoller
|
|
|
|
Replace the password before running:
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name unifi-exporter \
|
|
--restart unless-stopped \
|
|
-p 9130:9130 \
|
|
-e UP_UNIFI_DEFAULT_URL="https://<unifi-controller-ip>" \
|
|
-e UP_UNIFI_DEFAULT_USER="prometheus" \
|
|
-e UP_UNIFI_DEFAULT_PASS="REPLACE_WITH_YOUR_PASSWORD" \
|
|
-e UP_UNIFI_DEFAULT_VERIFY_SSL="false" \
|
|
-e UP_PROMETHEUS_HTTP_LISTEN="0.0.0.0:9130" \
|
|
ghcr.io/unpoller/unpoller:latest
|
|
```
|
|
|
|
---
|
|
|
|
## Step 3 Verify Container Is Running
|
|
|
|
```bash
|
|
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"
|
|
```
|
|
|
|
Expected result:
|
|
|
|
```
|
|
unifi-exporter 0.0.0.0:9130->9130/tcp Up
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4 Test Metrics Endpoint
|
|
|
|
```bash
|
|
curl http://<exporter-host-ip>:9130/metrics
|
|
```
|
|
|
|
Expected result:
|
|
|
|
```
|
|
UniFi metrics output
|
|
```
|
|
|
|
---
|
|
|
|
## Step 5 Restart Prometheus
|
|
|
|
```bash
|
|
systemctl restart prometheus
|
|
```
|
|
|
|
---
|
|
|
|
## Step 6 Confirm in Prometheus
|
|
|
|
Open:
|
|
|
|
```
|
|
http://<prometheus-host-ip>:9090/targets
|
|
```
|
|
|
|
Expected:
|
|
|
|
```
|
|
unifi-exporter UP
|
|
```
|
|
|
|
---
|
|
|
|
## Prometheus Scrape Config
|
|
|
|
Add this to prometheus.yml if not present:
|
|
|
|
```yaml
|
|
- job_name: "unifi-exporter"
|
|
static_configs:
|
|
- targets:
|
|
- "<exporter-host-ip>:9130"
|
|
labels:
|
|
instance: "unifi-exporter"
|
|
service: "unifi"
|
|
role: "network"
|
|
vendor: "unifi"
|
|
site: "ceds-homelab"
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Refused
|
|
|
|
Cause:
|
|
Exporter not running or not bound to port 9130.
|
|
|
|
Fix:
|
|
|
|
```bash
|
|
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"
|
|
docker restart unifi-exporter
|
|
```
|
|
|
|
---
|
|
|
|
### Authentication Failed
|
|
|
|
Cause:
|
|
Incorrect UniFi credentials.
|
|
|
|
Fix:
|
|
Update credentials and restart container.
|
|
|
|
---
|
|
|
|
### Target Still Down in Prometheus
|
|
|
|
Test exporter:
|
|
|
|
```bash
|
|
curl http://<exporter-host-ip>:9130/metrics
|
|
```
|
|
|
|
Check Prometheus config:
|
|
|
|
```bash
|
|
promtool check config /etc/prometheus/prometheus.yml
|
|
```
|
|
|
|
Restart Prometheus:
|
|
|
|
```bash
|
|
systemctl restart prometheus
|
|
```
|
|
|
|
---
|
|
|
|
## Security Notes
|
|
|
|
Never commit:
|
|
|
|
- UniFi passwords
|
|
- API keys
|
|
- Cloudflare tokens
|
|
- Proxmox credentials
|
|
- Grafana credentials
|
|
|
|
Use placeholders:
|
|
|
|
```
|
|
REPLACE_WITH_YOUR_PASSWORD
|
|
```
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
When complete, Prometheus should show:
|
|
|
|
```
|
|
unifi-exporter UP
|
|
```
|
|
|
|
Grafana dashboards can now use UniFi metrics. |