Connections

The Connections page is where you manage your Proxmox VE (PVE) and Proxmox Backup Server (PBS) connections. Each connection represents a link between ProxCenter and a Proxmox instance, providing the credentials and access configuration needed to communicate with the Proxmox API and SSH.

Overview

ProxCenter needs two types of access to fully manage a Proxmox instance:

• API access -- Used for reading cluster state, managing VMs, monitoring resources, and executing most operations
• SSH access -- Used for operations that require direct node access, such as disk imports, compliance scans, CVE scanning, and system updates

Adding a Connection

1. Navigate to Settings > Connections
2. Click Add Connection
3. Select the connection type: Proxmox VE or Proxmox Backup Server
4. Fill in the connection details

PVE Connection Settings

Field	Description
Name	A friendly name for this connection (e.g., "Production Cluster")
Host	The IP address or hostname of any node in the cluster
Port	API port (default: 8006)
Token ID	API token in the format user@realm!tokenid
Token Secret	The API token secret
SSH User	SSH username for node access (default: root)
SSH Port	SSH port (default: 22)
SSH Key / Password	Authentication method for SSH
Verify TLS	Whether to validate the server's TLS certificate

PBS Connection Settings

Field	Description
Name	A friendly name for this PBS instance
Host	The IP address or hostname of the PBS server
Port	API port (default: 8007)
Token ID	API token for PBS access
Token Secret	The API token secret
Fingerprint	The PBS server's TLS certificate fingerprint (optional)

API Token Setup

ProxCenter uses Proxmox API tokens rather than username/password authentication. To create an API token on Proxmox:

1. Log in to the Proxmox web UI
2. Go to Datacenter > Permissions > API Tokens
3. Click Add and select the user (e.g., root@pam)
4. Uncheck Privilege Separation if you want the token to inherit the user's full permissions
5. Copy the token ID and secret -- the secret is only shown once

warning

The API token secret is only displayed at creation time. If you lose it, you must create a new token. Store it securely.

Reverse Proxy Configuration

If your Proxmox instance is behind a reverse proxy (e.g., nginx, Traefik, HAProxy), ensure the proxy forwards WebSocket connections, as ProxCenter uses them for real-time updates. The proxy should pass through the Upgrade and Connection headers.

tip

When using a reverse proxy with TLS termination, you can disable TLS verification in the ProxCenter connection settings since the connection between the proxy and Proxmox will be internal.

Connection Health

Each connection shows a status indicator:

• Connected -- API and SSH connections are both active
• API Only -- API is reachable but SSH is not configured or unreachable
• Disconnected -- Cannot reach the Proxmox instance

ProxCenter periodically checks connection health and alerts you if a connection goes down.

XCP-ng Connections

XCP-ng is a migration source rather than a managed hypervisor: it is declared from Settings > Connections too, with the Add XCP-ng button, but it is used by VM migration rather than by the rest of the dashboard. Two connection modes are available.

XCP-ng pool (direct XAPI)

Connects straight to the pool over the XAPI, without going through Xen Orchestra.

Field	Description
Name	A friendly name for this connection
Host	The pool master's address, or the address of any host in the pool
Username	An account with root privileges on the pool (typically root)
Password	The account's password

The connection always uses HTTPS. If the host you entered turns out to be a pool slave, ProxCenter follows the HOST_IS_SLAVE redirection to the pool master automatically, so you do not need to look up which host currently holds that role.

This is the mode warm migration requires: it needs direct XAPI access to enable changed block tracking and to read the NBD export of a snapshot, neither of which a Xen Orchestra connection exposes.

Xen Orchestra (XO/XOA)

The existing connection type: ProxCenter talks to the pool through a Xen Orchestra or XOA instance.

Field	Description
Name	A friendly name for this connection
XO URL	The address of the Xen Orchestra or XOA instance
Account	The Xen Orchestra user ProxCenter authenticates as

Connections created before this mode selector was introduced are all Xen Orchestra connections.

Through a Xen Orchestra connection, only offline migration is available; warm migration is rejected, since it needs direct access to the pool's XAPI. Offline migration works with either connection mode. See Migration modes for how the mode is picked.

Hyper-V Connections

Like XCP-ng, a Hyper-V host is a migration source rather than a managed hypervisor: it is declared from Settings > Connections with the Add Hyper-V button and used by VM migration. ProxCenter talks to the host over WinRM (PowerShell remoting on TCP 5985, HTTP Basic authentication) and reads the VHDX files through an SMB share during the migration.

Prerequisites on the Hyper-V host

Run these commands in an elevated PowerShell on the Hyper-V server (they are also shown in the connection dialog):

# Enable WinRM remote management with Basic authentication over HTTP
Enable-PSRemoting -Force
Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true
Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true

# Share the folder that holds the virtual disks (works in any language)
$everyone = New-Object Security.Principal.SecurityIdentifier("S-1-1-0")
$account = $everyone.Translate([Security.Principal.NTAccount]).Value
New-SmbShare -Name "VMs" -Path "C:\Path\To\Your\VMs" -FullAccess $account

Three points are easy to miss:

• Use a local account of the Hyper-V host, member of the local Administrators group. WinRM Basic authentication does not accept domain accounts. A successful Enter-PSSession or winrs from another Windows machine proves nothing here: those use Kerberos or Negotiate, not Basic.
• The Hyper-V PowerShell module must be installed on the host (Get-Command Get-VM must succeed). Installing the role through Server Manager includes it; Install-WindowsFeature Hyper-V without -IncludeManagementTools does not.
• TCP 5985 must be reachable from the machine that runs ProxCenter. The firewall rule created by Enable-PSRemoting on a Public network profile only allows the local subnet.

Connection settings

Field	Description
Name	A friendly name for this connection
Hyper-V Host	Hostname or IP address of the Hyper-V server
Username	The local administrator account used for WinRM
Password	The account's password
SMB Share Name	Name of the share created above that contains the VHDX files (default VMs)

The Ignore TLS certificate errors switch has no effect on Hyper-V: the WinRM session always uses plain HTTP on port 5985 with the commands above.

Where the share must point

Share the folder that holds the VMs, not each VM's disk folder. Hyper-V stores a VM's disks under <folder>\<VM name>\Virtual Hard Disks\; ProxCenter reads the local path behind the share (Get-SmbShare) and resolves every disk relative to it, so a share on D:\HYPERV covers D:\HYPERV\vm1\Virtual Hard Disks\vm1.vhdx as well as disks stored directly at the root. The migrate dialog shows, for each disk, the path it will use on the mounted share. If a disk is not found at that path during the migration, ProxCenter searches the share for a file with the same name and uses it when it is unique; the paths can also be typed by hand in the VHDX Disk Paths field.

Requirements on the VM being migrated

Migration from Hyper-V is offline: ProxCenter copies the virtual disk files as they are, so before starting it the VM must be:

• powered off (Stop-VM); a running VM's disk is locked and inconsistent;
• without checkpoints (Get-VMSnapshot -VMName <name> must return nothing). With a checkpoint the active disk is a differencing .avhdx whose parent chain only resolves on the Windows host; remove the checkpoints (Remove-VMSnapshot) so Hyper-V merges them into the base disk.

ProxCenter verifies both over WinRM at the start of the migration and stops with an explicit message otherwise. A failed migration can be relaunched with Retry from the migration dialog.

Windows guests installed with Compact OS

Windows may install itself with system compression ("Compact OS"): its system files are then stored as compressed reparse points, which the NTFS driver of libguestfs only reads through a plugin that Debian, and therefore Proxmox VE, does not ship. Without it virt-v2v ends with No root device found in this operating system image although the disk is readable. ProxCenter builds and installs that plugin (ntfs-3g-system-compression) on the Proxmox node during the migration tooling setup, and checks for it at the start of every virt-v2v migration; the node needs Internet access to fetch it the first time. To check a guest, run compact /compactos:query in an elevated prompt; compact /compactos:never decompresses it if you prefer not to rely on the plugin.

Inventory listing and timing

The inventory tree lists the guests of every Hyper-V connection by running Get-VM over WinRM. Each remote command starts powershell.exe and imports the Hyper-V module, which takes several seconds on Windows Server 2019, so a host with many virtual disks can need 10 to 20 seconds to answer. ProxCenter waits up to 150 seconds for a Hyper-V listing (15 seconds for the REST-based sources).

Troubleshooting

• A host shown as unreachable in the inventory carries the cause in the tooltip of that label, and the same message is written to the ProxCenter server log with a [hyperv] prefix (docker compose logs).
• The status chip in Settings > Connections reports Error with the WinRM message when the host rejects the credentials.
• To check WinRM independently of ProxCenter, run from the ProxCenter host: curl -i --basic -u 'Administrator:password' http://HYPERV_HOST:5985/wsman. A 405 Method Not Allowed means the network path, Basic authentication and the account are all fine. A 401 points at the credentials or at Basic authentication being disabled; a timeout at the firewall.

Permissions

Permission	Description
connection.view	View configured connections
connection.manage	Add, edit, and delete connections