Proxmox VE Management Connector

 

This Connector allows you to manage Proxmox VE QEMU/KVM virtual machines and LXC containers from Visual TOM, including starting, stopping, restarting, and managing snapshots.

Disclaimer

No support or warranties will be provided by Absyss SAS for this project and associated files. Use is at your own risk.

Absyss SAS cannot be held responsible for damages caused by the use of any files made available in this Github repository.

Consulting days can be requested for implementation.

Prerequisites

• Visual TOM 7.1.2 or higher
• Python 3.x or higher
• Proxmox VE cluster or standalone node
• Install required python packages with pip: pip install -r requirements.txt

Instructions

• Windows :

  • Place the files submit_queue_proxmox.bat & proxmox.py in the %ABM_BIN% directory
  • Declare the queue on the agent (see administrator guide)

• Linux/Unix :

  • Place the files tom_submit.proxmox & proxmox.py in the $TOM_ADMIN directory
  • Declare the queue on the agent (see administrator guide)

• Create a Proxmox Context and define the following environment variables:

  • USERNAME: Proxmox API user (e.g. root@pam or vtom@pve)
  • PASSWORD: Password for Proxmox API connection
  • PROXMOX_HOST: IP address or hostname of your Proxmox server
  • PROXMOX_PORT: API port (optional, default: 8006)
  • VERIFY_SSL: Verify SSL certificate (optional, default: false)

• Create in Visual TOM a "Custom Application" connection with the following definition or import the MyApplication-Proxmox.xml file:

vtimport -x -f MyApplication-Proxmox.xml

The script returns specific exit codes:

• 0: Success
• 1: Error (connection, validation, or execution error)

Parameter descriptions:

• ACTION : Action to perform (List, Start, Stop, Restart, Snapshot, Revert, DeleteSnapshot, Delete)
• VM_NAME : Name or VMID of the QEMU VM or LXC container (required for all actions except 'List')
• SNAPSHOT_NAME : Name of the snapshot (required for Snapshot, Revert, DeleteSnapshot actions)
• SNAPSHOT_COMMENT : Description of the snapshot (optional, used only with Snapshot action)

The connector provides detailed logging with:

• Timestamps
• Log levels (INFO, WARNING, ERROR)
• Detailed operation status
• VM state information

Example log output:

2026-06-12 14:27:30,797 | INFO | Connecting to Proxmox: 192.168.1.100:8006
2026-06-12 14:27:30,850 | INFO | Successfully connected to Proxmox
2026-06-12 14:27:30,851 | INFO | Searching for VM: Production-Server-01
2026-06-12 14:27:30,857 | INFO | Starting VM...
2026-06-12 14:27:35,858 | INFO | Action 'Start' executed successfully on VM 'Production-Server-01'

Available Actions

List guests (VMs and containers)

• Action: List
• Parameters: VM_NAME (optional - for partial search by name or VMID)
• Description: Lists all QEMU VMs and LXC containers, or filters by partial name/VMID. Each entry shows its type (QEMU/LXC).

Power management

• Action: Start - Start a VM or LXC container
• Action: Stop - Gracefully shut down
• Action: Restart - Shut down then start
• Parameters: VM_NAME (required)

Snapshot Management

• Action: Snapshot - Create a snapshot
• Action: Revert - Rollback to a snapshot
• Action: DeleteSnapshot - Delete a snapshot
• Parameters: VM_NAME, SNAPSHOT_NAME (required), SNAPSHOT_COMMENT (optional for Snapshot)

Deletion

• Action: Delete - Delete a VM or LXC container (WARNING: Permanent deletion)
• Parameters: VM_NAME (required)

If a QEMU VM and an LXC container share the same name, use the VMID to resolve ambiguity.

Proxmox API permissions

The Proxmox user must have sufficient privileges on the target VMs and containers. For a dedicated service account, a role with at least VM.PowerMgmt and VM.Snapshot permissions on the relevant pool or / is recommended.

License

This project is licensed under Apache 2.0. See the LICENSE file for more details.

Code of Conduct

Absyss SAS has adopted the Contributor Covenant as a Code of Conduct and expects project participants to adhere to it as well. Please read the complete document to understand which actions will or will not be tolerated.