# 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.