Proxmox & PBS Control

What you need

• Windows 10 or 11, or macOS 12 or newer, with Stream Deck software 7.1 or newer. It should work on a Mac, but it has not been tested on one yet.
• At least one of these, reachable from that computer:
  • Proxmox VE 7 or later, a single node or a cluster (port 8006)
  • Proxmox Backup Server 2 or later (port 8007)
  • Proxmox Datacenter Manager 1.0 or later (port 8443), which covers every remote it manages
• An API token on each server. The plugin never asks for a password.

Any Stream Deck works: the original, Mini, XL, Stream Deck +, Neo, and Stream Deck Mobile on a phone or tablet.

1. Install the plugin

Demo profiles

A ready-made page of Proxmox & PBS Control keys for each Stream Deck: nodes and guests on connection A, the backup server on connection C, and on the XL a Datacenter Manager key on connection B. Each Node, Guest and Datastore key asks you to pick which one, so add your connections first. Download the one for your deck and double-click it to import it into Stream Deck.

• Stream Deck: 15 keys: two nodes, eleven guests, the backup server and a datastore
• Stream Deck Mini: 6 keys: a node, three guests, the backup server and a datastore
• Stream Deck XL: 32 keys: two nodes, twenty-six guests, Datacenter Manager, the backup server and two datastores
• Stream Deck +: 8 keys and all four dials: two nodes, the backup server and a datastore on the dials
• Stream Deck Neo: 8 keys: a node, five guests, the backup server and a datastore

2. Create an API token

Give the deck its own user and token, with only the rights you want it to have. The token's secret is shown once, when you create it, so keep it on screen until the connection is set up.

Proxmox VE

In a shell on any node of the cluster:

pveum user add streamdeck@pve
pveum role add StreamDeck --privs "VM.Audit,VM.PowerMgmt,Sys.Audit,Sys.PowerMgmt,Datastore.Audit,Pool.Audit"
pveum acl modify / --users streamdeck@pve --roles StreamDeck
pveum user token add streamdeck@pve deck --privsep 0

That gives the token its user's rights: reading everything, guest power (VM.PowerMgmt) and node reboot and shutdown (Sys.PowerMgmt). Leave out either power right to keep the deck from using it, or use the built-in PVEAuditor role for a deck that only watches. You can do the same in the web UI under Datacenter → Permissions.

Proxmox Backup Server

In a shell on the Backup Server:

proxmox-backup-manager user create streamdeck@pbs
proxmox-backup-manager user generate-token streamdeck@pbs deck
proxmox-backup-manager acl update / Audit --auth-id streamdeck@pbs
proxmox-backup-manager acl update / Audit --auth-id 'streamdeck@pbs!deck'

A Backup Server never gives a token more than its user has, so grant both. For garbage collection and verification from the deck, add DatastorePowerUser on /datastore; for reboot and shutdown, Admin on /system.

Proxmox Datacenter Manager

In the Datacenter Manager's web UI, under Configuration → Access Control:

1. Add a user in the pdm realm, for example streamdeck@pdm.
2. Add an API token for it, for example deck, and copy the secret.
3. Under Permissions, give both the user and the token a role on /resource: Auditor for a deck that only watches, or Administrator to also start, shut down and stop guests. The Datacenter Manager has no role in between.

The Datacenter Manager talks to its remotes with its own tokens, so the deck needs nothing on the Proxmox VE servers behind it.

3. Add a connection

Drag any Proxmox key onto your deck, open its settings and expand Connections. There are three slots, A, B and C, shared by every Proxmox key, so you set each up once.

Refresh every sets how often the keys update, from 5 to 60 seconds. However many keys you have, each connection costs one request per refresh.

4. Add the keys

You will find five actions in the Proxmox & PBS Control category. Leave each key's title empty; the key draws its own text.

• Node: name, CPU and RAM bars, uptime and memory. Press it for a page of that node's VMs and containers. On a Stream Deck + it works as a dial: rotate for CPU or RAM, push for the web UI.
• Guest (VM / CT): VM or CT badge, ID, name, status, and CPU and RAM while running. Press it for the guest's detail page.
• Datacenter (PDM): a Datacenter Manager at a glance. It shows remotes, nodes online, CPU and RAM across every node, and guests running, and turns red when it cannot reach a remote. Press it for every node on every remote.
• PBS Server: CPU, RAM, uptime and running tasks. Press it for the Backup Server page.
• PBS Datastore: used and free space, newest backup, garbage-collection state, and group and snapshot counts. Press it for that datastore's backups.

Each key has a Connection and, for nodes, guests and datastores, a list to pick from, read from the server. On a Datacenter Manager connection the lists are grouped by remote.

5. The pages

Pressing a key opens a page made for it. The pages come with the plugin as read-only profiles; the first time, Stream Deck asks permission to install them, so accept it. Back always returns you to where you came from, and arrows in the bottom corners page through long lists.

A Datacenter Manager's nodes

Press a node for its guests, and a guest for its detail page, all through the one Datacenter Manager connection.

A node's guests

A guest's detail page

On an XL and a 15-key Stream Deck the graphs are two keys wide. Smaller decks show CPU and RAM, the newest backup and the power keys that fit.

A Backup Server

Groups turn yellow after 36 hours without a backup and red after 7 days. VM and container groups show the guest's name from your Proxmox VE connections. Press a datastore to see only its groups; Back widens the page again.

6. Hold to confirm

Power and maintenance actions only run after you hold the key for 2 seconds. A short press only tells you what a hold would do. Actions that do not apply, such as Start on a running guest, are refused on the key, and results and errors show on the key itself.

The XENEON EDGE

On Windows, version 2.1.0 and later of the plugin can also feed Proxmox Dashboard, our iCUE widget for the Corsair XENEON EDGE. Every few seconds the plugin writes what it reads to one file, %APPDATA%\ProxmoxControl\state.json, and the widget draws from that file: each connection's health, nodes, guests, storage, backups and Datacenter Manager remotes.

• The setting is Feed the XENEON EDGE widget, under Connections in any Proxmox key's settings. It is on by default; untick it and the plugin stops writing the file.
• While it is on, every connection that is set up is polled, even with none of its keys on screen.
• The file holds host names and figures only, never a token or secret. Your tokens stay in the plugin.

Start Stream Deck with the plugin once before you add the widget in iCUE. That makes the folder the widget reads, and iCUE only watches a folder that existed when the widget was added.

No Stream Deck? Use Proxmox Link

Proxmox Link is a small Windows program that writes the same file, for people who want the widget without a Stream Deck. It is written in PowerShell, so there is nothing else to install. It reads your Proxmox VE servers or clusters, Backup Servers and Datacenter Managers with a read-only API token, and sits in the notification area with a light: green when every connection answers, amber when some fail, red when all fail.

You can run both. If you do, Proxmox Link writes the file and the plugin steps aside. Quit or pause Proxmox Link and the plugin takes over again within a few seconds.

Download Proxmox Link 1.0.0 Windows 10 or 11 · PowerShell · 48 KB zip

Proxmox Link is open source (MIT), so you can read exactly what it does before you give it a token: github.com/AussieH/proxmox-link.

It runs on Windows PowerShell 5.1, which comes with Windows; PowerShell 7 works too. You also need iCUE 5.51 or later with the Proxmox Dashboard widget on a XENEON EDGE.

Install Proxmox Link

1. Download ProxmoxLink-1.0.0.zip.
2. Unblock the zip before you extract it: right-click it, choose Properties, tick Unblock, then OK. In PowerShell, Unblock-File .\ProxmoxLink-1.0.0.zip does the same. Unblocking the zip also unblocks the files you extract from it.
3. Extract the zip anywhere, then double-click Install.cmd.

The installer:

• copies Proxmox Link to %LOCALAPPDATA%\Programs\ProxmoxLink, for your account only. No administrator rights are needed;
• clears the "downloaded from the internet" mark on the installed files;
• adds Proxmox Link, Proxmox Link setup and Uninstall Proxmox Link to the Start menu;
• if you answer yes, adds a shortcut to your Startup folder so Proxmox Link starts when you sign in;
• opens setup.

By default, Windows won't run unsigned PowerShell scripts, so every shortcut starts PowerShell with -ExecutionPolicy Bypass. That applies to that one launch only:

powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "...\ProxmoxLink.ps1"

Your computer's execution policy and your own are never changed. One exception: if your organization sets the execution policy by Group Policy, that policy wins over the command line, and Proxmox Link can't run.

Set up Proxmox Link

Open Proxmox Link setup from the Start menu, or double-click the tray icon.

1. Connection A, B or C. Each connection has these fields:
   • Type: Proxmox VE (port 8006), Proxmox Backup Server (8007) or Proxmox Datacenter Manager (8443).
   • Name: shown on the widget.
   • Host: the host name or address only, for example pve01.home.arpa.
   • Port, Token ID (for example linkreader@pve!edge) and Secret.
   One Datacenter Manager covers all of its remotes.
2. Test. The first Test stops at the server's certificate and shows its SHA-256 fingerprint. Compare it with the fingerprint the server reports, then press Trust this certificate. Test runs again and shows what it found, for example "3 nodes (3 online), 24 guests (18 running), 5 storages".
3. Save. If Proxmox Link isn't running yet, setup offers to start it.
4. Under Settings you can change Refresh every (5 to 60 seconds, 30 by default), tick Start Proxmox Link when I sign in, and Start or Stop it.

Within a few seconds the widget shows your servers. A running Proxmox Link picks up saved changes by itself.

Proxmox servers make their own self-signed certificates, so Proxmox Link trusts the certificate you checked in setup and nothing else. To see a server's own fingerprint, run this on the server itself (use port 8006, 8007 or 8443):

openssl s_client -connect localhost:8006 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256

You can also find it in the web UI: on Proxmox VE, select the node, then System → Certificates; on a Backup Server, Dashboard → Show Fingerprint. When a server gets a new certificate, its connection shows TLS cert; press Test, check the new fingerprint and trust it if it is right.

A read-only API token for Proxmox Link

Proxmox Link only reads, so give it its own user and a token with a read-only role. Each server shows a new token's secret only once, when you create it.

Proxmox VE. In a shell on any node:

pveum user add linkreader@pve
pveum acl modify / --users linkreader@pve --roles PVEAuditor
pveum user token add linkreader@pve edge --privsep 0

The token ID is linkreader@pve!edge. In the web UI, go to Datacenter → Permissions → API Tokens → Add and untick Privilege Separation. If you keep privilege separation, give the token itself PVEAuditor on /.

Proxmox Backup Server. In a shell on the Backup Server:

proxmox-backup-manager user create linkreader@pbs
proxmox-backup-manager user generate-token linkreader@pbs edge
proxmox-backup-manager acl update / Audit --auth-id linkreader@pbs
proxmox-backup-manager acl update / Audit --auth-id 'linkreader@pbs!edge'

A Backup Server never gives a token more rights than its user has, so grant Audit to both. The Audit role includes Datastore.Audit.

Proxmox Datacenter Manager. In the web UI, under Configuration → Access Control:

1. Add a user in the pdm realm, for example linkreader@pdm.
2. Add an API token for that user and copy the secret.
3. Under Permissions, give both the user and the token the Auditor role on /resource.

The Datacenter Manager reaches its remotes with its own tokens, so you don't need a token on the servers behind it.

Your settings are kept in %LOCALAPPDATA%\ProxmoxLink, with token secrets encrypted for your Windows account, outside the folder the widget can read. A token's secret is only ever sent to the host you entered, and only after that host's certificate checks out.

Uninstall Proxmox Link

Use Uninstall Proxmox Link in the Start menu, or run Uninstall.cmd. It stops Proxmox Link, removes the shortcuts and the program folder, and asks before it deletes your settings and saved tokens. It leaves %APPDATA%\ProxmoxControl alone, because the Stream Deck plugin uses that folder too.

Troubleshooting

Frequently asked

Does it work on a Mac?

It should. Nothing in the plugin is specific to Windows, and it installs on macOS 12 and newer. But it has only been tested on Windows so far. If you try it on a Mac, we would like to hear how it goes at support@teatimeservers.ca.

Where is my token kept?

In the Stream Deck app's own settings on your computer. The plugin only ever sends it to the server it belongs to, never writes it to a log, and needs no account or password of any kind.

Can I watch more than one cluster?

Yes. Use up to three connections, or point one connection at a Datacenter Manager and see every cluster and node it manages.

Does it change anything on my servers?

Only when you hold a power or maintenance key for 2 seconds. Everything else only reads. For a deck that only watches, give its token a read-only role.

Is this made by Proxmox?

No. It is an unofficial plugin, not affiliated with or endorsed by Proxmox Server Solutions GmbH.

Something is still wrong.

Email support@teatimeservers.ca with what the key says, and we will take a look.