📚 Browse docs

Connect your Proxmox nodes

Before Asternodis can protect anything, it needs to reach the Proxmox cluster it manages. You do this on the Inventory page (“Add Proxmox Node”).

Two ways to connect

Give Asternodis SSH access to a node and it will provision its own API token for you, with no manual token juggling in the Proxmox UI. This is the quickest path.

You’ll provide:

  • a name for the cluster/remote (e.g. prod-cluster);
  • the node host/IP and SSH user (usually root);
  • an SSH password or private key;
  • optionally, a non-default API port and SSH port (see below).

Asternodis connects over SSH, creates a dedicated API token, and stores it. From then on it talks to Proxmox over the API.

With an SSH password, the form first asks you to verify the node’s host key: Check host key reads it (no password is sent) and shows its fingerprint. Confirm that it matches the node itself (check it on the node’s console, or with ssh-keyscan); the password field stays locked until you do, and confirming pins the password to that key, so it can only ever reach the node you meant.

What access Asternodis needs

Be aware of what this grants, because the product does not currently offer a reduced-privilege mode:

  • The API token is created with privsep=0, so it inherits the privileges of the user it belongs to. Created as root@pam, that is full administrative access to the cluster. It is a dedicated token: you can revoke it independently, and Asternodis can rotate it from Inventory → Rotate API token. But it is not a restricted one.
  • SSH access must be root, or a user with equivalent rights. Tier-2 replication runs ZFS, LVM, Ceph/RBD and qemu-nbd operations directly on the node; Asternodis does not use sudo and has no privilege-elevation step, so an unprivileged SSH user will fail.

If your policy requires a restricted token, create it yourself in Proxmox and use the API-token path below instead, but note the SSH requirement still applies for replication, and a token without sufficient rights will surface as permission errors during protect or failover rather than at setup time.

Non-default ports (reverse proxies, NAT, hardened SSH)

Both ports are per-cluster and editable when you add the cluster:

  • API port: defaults to 8006. Set it when the Proxmox API is reached through a reverse proxy or a forwarded port. The Inventory list shows each cluster as host:port so you can confirm what was saved.
  • SSH port: defaults to 22, with its own SSH host field, so the SSH transport can use a different address and port from the API.

The controller only needs to reach the entry node you add. Other members of the same cluster are reached by node name through that entry node, so they do not each need to be exposed to the controller. A reverse proxy in front of the API does not cover SSH, though, so the entry node still needs an SSH route.

Replication data is different: it flows directly between the nodes of the two sites (VM disks over an encrypted NBD stream on a port range, containers and ZFS-send over SSH). So every node that hosts a protected guest and the recovery nodes it replicates to must be able to reach each other, in both directions for failback. The full list is in the port table in Install.

API token (bring your own)

If you’d rather create the token yourself in Proxmox, provide the token ID (user@realm!tokenname) and secret directly. Use this when SSH access isn’t available or your policy requires manually-scoped tokens.

Clusters vs single nodes

Point Asternodis at any node in a Proxmox cluster and it discovers the rest of the cluster automatically. A standalone node works too: it’s just a cluster of one.

Verifying

Once added, the node appears in Inventory with its nodes, guests, storage, and live CPU/RAM. If a connection fails, Asternodis surfaces the error so you can fix credentials or reachability. You can re-test a remote at any time.

Next: create a DR Site Pair so this site has somewhere to recover to.