Proxmox VE SPICE Connector

Bash script that runs Virt-viewer's SPICE session via API call to a remote ProxmoxVE.

run-vm-via-desktop-shortcut-generated-by-pve-spice-connector.webm

Deploy

Clone the repository, create environment (configuration) file on the base of the provided example. Then optionally locate the script somewhere on your $PATH in order to use it as shell command. Here is an example:

git clone git@github.com:metalevel-tech/pve-spice-connector.git

cp pve-spice-connector.env{-example,}

ln -s /home/${USER}/Git/pve-spice-connector/pve-spice-connector.sh /home/${USER}/bin
ln -s /home/${USER}/Git/pve-spice-connector/pve-spice-connector.env /home/${USER}/bin

Setup

Generate API token on the ProxmoxVE server. Uncheck the Privilege separation option if you don't want to make additional setup for the privileges. Copy the generated authentication data, then edit the environment file and set the default values of the configuration variables:

• $TOKEN name and $UUID of the token;
• $PROTO you can remove this variable if you use https;
• $NODE the name of the node in your cluster, you can remove this variable if you use pve;
• $VMID the Id of the default virtual machine you want to connect to, this variable will be overridden via the script call command.
• Choice one of the examples for the $SPICE_PROXY_ARGS and $PVE_URL variables and remove the rest. I'm using the parameters provided via $SPICE_PROXY_ARGS to override the default proxy within the Virt-viewer configuration object, because I'm using ReverseProxy for the ProxmoxVE Web GUI interface, but I don't want to use it for the SPICE session.

Usage

While the scrip is in your $PATH you can use it as a shell command in the following way:

pve-spice-connector.sh            # Connect to the VM with the default VMID
VMID=155 pve-spice-connector.sh   # Connect to the VM with VMID 155
VMID=200 pve-spice-connector.sh   # Connect to the VM with VMID 200

The script will check whether the VM is running and if it is, it will immediately connect to it via SPICE session. If the VM is not running, the script will start it and few seconds later will connect to it.

Assets

Use the example-launcher.desktop file as template to create launchers on your GNU/Linux GUI desktop. Copy the icons from the directory assets/icons/ to ~/.local/share/icons/ and after a while they will be available for usage within your desktop environment.

References

• ProxmoxVE: Proxmox VE API Reference

• ProxmoxVE Wiki: Proxmox VE API

• ProxmoxVE Docs: Pveproxy

• ProxmoxVE Docs: Spiceproxy

• Examples of similar scripts (and topics) which use password authentication:

  • Proxmox Forum: Accessing SPICE without WEB GUI | spice-example-.sh
  • Proxmox Forum: Spiceproxy via API
  • Apalrd.net: Using a Raspberry Pi as a Thin Client for Proxmox VMs
  • JamesCoyle.net Limited: Getting Started With Proxmox HTTP API Commands

• Proxmox Forum: Change Spice Proxy port (not related to the current topic, but I want to keep it as a note for myself)

• Metalevel.tech Wiki: The Proxmox Category in my wiki