Proxmox

Proxmox

This page shows how to add a Proxmox server with an API token, what the token needs to be allowed to do, and what you can then do with its machines from the tree.

Adding a server

Settings, Proxmox servers, Add a Proxmox server (also from New session under Source, or a right-click in the tree, Add a Proxmox server). Fill in:

• Address: pve.lan or https://10.0.0.5:8006.
• Name in the tree.
• Network (the server, and the sessions of its guests): a WireGuard network, if the server is only reachable through one. See below.
• API token: either From a credential source (user name = token ID, password = secret), a login in one of your Credential sources, or Type it here, kept encrypted on this PC, with Token ID (root@pam!cablebag) and Secret.
• Opening a guest: SSH user (root by default), SSH key file (optional) and RDP user (optional), used for the sessions Cablebag opens for the machines.

Save and test connects and reports how many virtual machines and containers it sees. When the server's certificate is not signed by a known authority, Cablebag asks you to trust it once and then shows the fingerprint under Trusted certificate.

To remove a server, right-click it in the tree and choose Remove this Proxmox server, or use Remove in its edit window or the bin icon under Settings, Proxmox servers: its guests leave the tree; nothing changes on the server.

The API token and its roles

Make the token on the Proxmox server under Datacenter, Permissions, API Tokens. With "Privilege Separation" switched on, give the token itself the roles below (not only the user).

What you want to do	What the token needs
See the machines, their state and addresses	the PVEAuditor role on /
Start, shut down, reboot and force stop	also PVEVMUser, or the VM.PowerMgmt privilege
Take, roll back and delete snapshots	VM.Snapshot, and VM.Snapshot.Rollback to roll back
Let the assistant run commands inside a VM	VM.GuestAgent.Unrestricted (Proxmox 9), and the QEMU guest agent switched on and installed in the VM

Without a privilege Cablebag says so at the moment you need it. If Proxmox refuses the token, the message asks you to check the token ID and secret.

The live folder

A Proxmox server shows in the session tree as a folder of its machines, with the state, the node and the addresses of each one, and a count of running against all. Type in Find a session to filter them by name, id, node, address or tag.

Right-click a machine:

• Open with SSH and Open with RDP (with the SSH user, key file and RDP user from the server's settings).
• Open the console (a running machine) and Open the console in the browser.
• Containers (a running Linux machine): its Docker containers in a tab, see Containers. It uses your saved SSH session for that address when you have one, otherwise the SSH user and key from the server's settings.
• Save as a session, to keep it in the tree with options of its own.
• Snapshots and Tasks of this guest.
• Start, or Shut down, Reboot and Force stop.

Double-click opens Remote Desktop, SSH or the console. Drag a machine onto a folder of the tree to keep it there as a saved session, with the SSH or RDP user from the server's settings.

A Proxmox server can be dragged into a folder of the tree too (a customer's folder, for example), and dragged above or below another Proxmox server to change their order; see Sessions, Drag and drop.

Right-click the server itself for Refresh, Open the Proxmox web interface (in a Cablebag tab), Shell on the node ..., Recent tasks, Edit this Proxmox server and Remove this Proxmox server.

Console

Open the console shows the machine's console in a Cablebag tab. From that tab the assistant can run commands inside the VM or container; see Assistant.

Snapshots and tasks

Snapshots lists the snapshots of a VM or container with when they were taken. Give a Name and an optional Description and take one; for a VM, With memory also saves its RAM, so a rollback resumes the running VM. Roll back or delete from the list; Cablebag follows the Proxmox task until it is done.

Tasks of this guest and Recent tasks (on the server) list the recent Proxmox tasks with what each one wrote.

Shell on the node

Right-click the server, Shell on the node ... opens an SSH terminal on that node. When you have a saved SSH session whose host is the node's name or address, Cablebag uses it; otherwise it opens an SSH session as root on the node's address, and the password comes from the vault or is asked.

Behind WireGuard

Choose a network under Network when you add or edit the server. Then the API, the machines list, start and stop, snapshots, the console, the node shell and the SSH and RDP sessions Cablebag opens for its machines all go through that network. The Proxmox web interface and the console in the browser open in a Cablebag tab through it too, because the web browser on this PC cannot reach the server. See WireGuard per session.

Proxmox servers travel with Sync; the token secret does not.