Skip to content

Proxmox VE and Ceph

At the end of this page Ferrule will be reading your Proxmox cluster: nodes, quorum, storage, the busiest virtual machines, and Ceph if you run it.

One source covers the whole cluster. Any node's address will do.

In Proxmox

In the web interface, go to Datacenter → Permissions:

  1. Users → Add: user telemetry, realm Proxmox VE authentication server (pve). It needs no password.
  2. API Tokens → Add: user telemetry@pve, token ID ro, with Privilege Separation ticked. Copy the secret now: it's shown once.
  3. Permissions → Add → User Permission: path /, user telemetry@pve, role PVEAuditor, Propagate ticked.
  4. Permissions → Add → API Token Permission: path /, token telemetry@pve!ro, role PVEAuditor, Propagate ticked.

Do both step 3 and step 4

With privilege separation on, the token sees only what both it and its user may see. With only one of them, Proxmox shows Ferrule nothing at all, and the panel tells you so.

In Ferrule

  1. Click Settings ⚙ and find Add a source.
  2. Kind: Proxmox VE. Fill in Name (anything you'll recognise), Address and API token ID.
  3. Ferrule writes two lines, such as SOURCE_1=... and SOURCE_1_SECRET=.... Click Copy.
  4. Add both lines to your settings, and replace the placeholder in the _SECRET line with the token secret:
  1. Open the ferrule stack and find Environment variables.
  2. Add or change the lines. In Advanced mode you can paste several at once.
  3. Click Pull and redeploy.
  1. Open .env in the folder where you cloned ferrule-deploy.
  2. Add or change the lines.
  3. Run docker compose up -d in that folder.

Ferrule never asks for the token secret

It only goes into your settings. The Settings page shows whether it's set, never what it is.

  • Address: https://<node>:8006
  • API token ID: telemetry@pve!ro

How to know it worked

  • Settings → Sources lists it, with the state polling. Right after an update it says waiting for first poll for up to a minute.

  • It appears on the Virtualization tab.

  • With Ceph, its health appears on the cluster's panel.

What it alerts on

A node that left the cluster, lost quorum, storage unavailable or nearly full (90% is a warning, 95% is bad), and every health check Ceph raises. A check you mute in Ceph stays quiet in Ferrule too.