# Configuration Reference

The exporter reads `config.yaml` from the current working directory by default.
Use `-config` to select a different file:

```sh
./pve-exporter -config /etc/pve-exporter/config.yaml
```

## Complete example

```yaml
host: 0.0.0.0
port: 9090
logLevel: 4

proxmox:
  token:
    tokenId: monitoring@pve!exporter
    secret: change-me

  hosts:
    - https://192.168.0.10:8006
    - https://pve02.example.com:8006/

  interval: 15

  metrics:
    clusterState: true
    nodeStatus: true
    qemu: true
    lxc: true
    disk: true
    zfs: true
    storage: true
    subscription: true
    sdn: true
```

## Server settings

| Setting | Type | Description |
| --- | --- | --- |
| `host` | IP address | Address on which the exporter HTTP server listens, for example `0.0.0.0` or `127.0.0.1`. DNS names are not accepted here. |
| `port` | integer | Exporter HTTP port. Prometheus metrics are served at `/metrics`. |
| `logLevel` | integer | Logrus level: `0=Panic`, `1=Fatal`, `2=Error`, `3=Warn`, `4=Info`, `5=Debug`, `6=Trace`. |

## Proxmox token

| Setting | Type | Description |
| --- | --- | --- |
| `proxmox.token.tokenId` | string | Full Proxmox API token ID, normally `user@realm!token-name`. |
| `proxmox.token.secret` | string | API token secret. Treat the configuration file as sensitive. |

Create a dedicated monitoring user and token, then assign the read-only
`PVEAuditor` role to both the user and the token. The role supplies the audit
permissions used by cluster, node, storage, disk, ZFS, guest, and subscription
API calls.

## API hosts and failover

`proxmox.hosts` is a non-empty list of Proxmox API base URLs. Both IP addresses
and DNS names are supported:

```yaml
proxmox:
  hosts:
    - https://192.168.0.10:8006
    - https://pve02.example.com:8006/
```

A trailing slash is optional and normalized automatically. Every host must use
`http` or `https` and must belong to the same PVE cluster. The exporter checks
endpoint liveness every five seconds and distributes API requests across the
currently reachable endpoints.

Do not combine unrelated clusters in one list. Their API responses share the
same short-lived client cache and Prometheus registry. Run a separate exporter
for each cluster.

## Collection interval

`proxmox.interval` is the positive number of seconds between collection cycles.
The first cycle runs during application startup. Prometheus scrapes only the
values already present in the registry, so its scrape interval does not control
the PVE API request rate.

## Collector switches

All switches are booleans. Omitted switches default to `false`.

| Setting | Collector | Main metric prefix |
| --- | --- | --- |
| `clusterState` | Cluster mode, node count, and quorum | `pve_cluster_` |
| `nodeStatus` | Node health and resource usage | `pve_node_` |
| `qemu` | QEMU virtual machines | `pve_vm_` |
| `lxc` | LXC containers | `pve_ct_` |
| `disk` | Physical disk health and metadata | `pve_node_disk_` |
| `zfs` | ZFS pool topology, state, and errors | `pve_node_zfs_` |
| `storage` | Enabled PVE storage status and capacity | `pve_storage_` |
| `subscription` | Node subscription information | `pve_node_subscription_` |
| `sdn` | Software-defined network state | `pve_sdn_` |

The exporter-level `pve_metrics_collection_latency_ms` summary is always
registered.

## Validation notes

- `host` must be a literal IP address.
- At least one Proxmox API host is required.
- API host URLs require an `http` or `https` scheme and an IP or DNS hostname.
- Token ID and secret cannot be empty.
- Keep `proxmox.interval` greater than zero and `logLevel` between `0` and `6`.