---
title: "Homarr — Proxmox Integration and Cert Trust"
aliases: [homarr-proxmox, homarr-cert-trust, homarr-termix, homarr-trusted-certs]
tags: [homarr, proxmox, homelab, dashboard, ssl, docker, termix, selfhosted]
sources:
  - "daily/2026-04-19.md"
created: 2026-04-19
updated: 2026-04-19
---

# Homarr — Proxmox Integration and Cert Trust

Homarr's Proxmox monitoring integration fails with `UNABLE_TO_VERIFY_LEAF_SIGNATURE` on self-signed Proxmox certificates. The fix is to place the Proxmox PVE **root CA** cert (not the leaf cert) into Homarr's `/appdata/trusted-certificates/` directory and restart. `NODE_TLS_REJECT_UNAUTHORIZED=0` is not reliably honored by Homarr v1's internal task runner process.

## Key Points

- **Use the PVE root CA**, not the leaf cert — `/etc/pve/pve-root-ca.pem` on the Proxmox host, not the node cert
- **`trusted-certificates/` file path takes precedence** over the DB table `trusted_certificate_hostname` — the DB table alone is insufficient; the `.pem` file must be present at startup
- **`NODE_TLS_REJECT_UNAUTHORIZED=0` is unreliable in Homarr v1** — the task runner process that calls integrations doesn't honor it consistently
- **Port 7575 conflict** often requires `fuser -k 7575/tcp` before `systemctl restart homarr` — the old process lingers after a failed start
- **Proxmox integration uses API token auth** (username / tokenId / tokenSecret), not SSH — `root@pam!homarr` style token

## Details

### Cert Trust: The Correct Approach

Homarr loads trusted certificates from `/appdata/trusted-certificates/` at process startup. Place the PVE root CA there:

```bash
# On Proxmox host — get the root CA
cat /etc/pve/pve-root-ca.pem

# In Homarr's LXC — write it to trusted-certificates
mkdir -p /appdata/trusted-certificates
# paste the PEM content into:
/appdata/trusted-certificates/proxmox.pem

# Restart (kill port conflict first if needed)
fuser -k 7575/tcp
systemctl restart homarr
```

The container volume must mount `/appdata` — verify with:
```bash
grep -r trusted-certificates /etc/systemd/system/homarr*
# or check the docker-compose if running in Docker
```

### Why Leaf Cert Doesn't Work

Proxmox's leaf cert (`/etc/pve/nodes/pve/pve-ssl.pem`) is signed by the PVE root CA, which is itself self-signed. Adding only the leaf cert tells Node.js the endpoint certificate is trusted but does nothing about the CA that signed it — the chain of trust still fails. Adding the root CA (`/etc/pve/pve-root-ca.pem`) causes Node.js to trust anything signed by that CA, which includes the leaf cert.

### Creating a Proxmox API Token for Homarr

In Proxmox web UI → Datacenter → Permissions → API Tokens:

```
User: root@pam
Token ID: homarr
Privilege Separation: unchecked (inherit root permissions)
```

In Homarr integration config:
- **Username:** `root@pam`
- **Token ID:** `homarr`
- **Token Secret:** (the UUID shown once at creation)

### Termix SSH Manager

Termix is a browser-based SSH manager that can run as a companion container. Hosts are managed via REST API at port 30001:

```bash
# Login to get JWT
TOKEN=$(curl -s -X POST http://localhost:30001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"..."}' | jq -r .token)

# Add a host
curl -X POST http://localhost:30001/host/db/host \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Proxmox",
    "host": "192.168.1.48",
    "port": 22,
    "username": "root",
    "authType": "password",
    "password": "..."
  }'

# Update an existing host (fix wrong password)
curl -X PUT http://localhost:30001/host/db/host/9 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "correct-password"}'
```

### Proxmox SSH — PasswordAuthentication

Proxmox ships with `PasswordAuthentication no` and `PermitRootLogin prohibit-password` in `/etc/ssh/sshd_config`. Termix SSH via password fails silently with "All configured authentication methods failed". Solutions:
1. Use key-based auth in Termix (`authType: key` + private key content)
2. Enable password auth on Proxmox: `sed -i 's/PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config && systemctl restart sshd` (less secure)

### Docker Socket Proxy for Homarr

To show running container stats in Homarr without exposing the full Docker socket:

```yaml
# In docker-compose on the LXC with Docker
services:
  socket-proxy:
    image: ghcr.io/tecnativa/docker-socket-proxy
    ports:
      - "2376:2375"  # port 2375 may be occupied by dockerd; use 2376
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      INFO: 1
```

In Homarr integration, point Docker widget at `http://<LXC_IP>:2376`.

## Related Concepts

- [[wiki/concepts/nodejs-ssl-system-trust-store]] — why Node.js ignores system trust store and requires explicit cert injection
- [[wiki/concepts/homepage-proxmox-widget-quirks]] — Homepage (replaced by Homarr/Dashy) had similar SSL and widget issues
- [[wiki/concepts/lxc-arp-cache-api-failures]] — ARP cache issues in LXC containers caused silent connection failures during this setup
- [[wiki/concepts/proxmox-mcp-server]] — Proxmox API token and access patterns

## Sources

- [[daily/2026-04-19.md]] — Homarr sessions at 22:05 and 22:23; Proxmox integration `UNABLE_TO_VERIFY_LEAF_SIGNATURE`; leaf cert vs root CA discovery; Termix REST API host management; docker-socket-proxy on port 2376; `fuser -k 7575/tcp` restart workaround
