WireGuard VPN for Proxmox nodes

NexoVirt runs a WireGuard VPN on each of your Proxmox nodes with one click. You create named configs for your devices that reach every node, a single node, or only chosen SDN projects, without exposing those networks to the internet and without editing WireGuard or iptables by hand.

Where things are

Page	What you do there
Node page > Network tab > WireGuard VPN tile	Enable the VPN on that node, set its port, subnet, endpoint and forward networks, check its readiness, see the devices that reach it.
VPN (sidebar, `/panel/vpn`)	Create, renew and revoke your own VPN configs.
Settings > VPN	Global defaults (VPN range, default port, customer device limit, client networks) and a list of all nodes with their VPN state and an Open link.
Portal VPN (`/portal/vpn`, Enterprise)	Customers create devices that reach only their own servers or SDN projects.

On the node, the agent manages a dedicated wg-nexovirt interface, a nexovirt-wg.service unit and its own NEXOVIRT-VPN, NEXOVIRT-VPN-IN and NEXOVIRT-VPN-NAT firewall chains. Traffic from the tunnel is dropped by default and only the allowed destinations are opened. The node’s private key is generated on the node and never leaves it.

Enabling the VPN on a node

Make sure the node runs a current agent (0.23.2 or newer; the panel asks you to update an outdated agent).
Open the node page, Network tab, and click Set up on the WireGuard VPN tile.
Turn on VPN enabled, check the settings and click Save. The first apply installs wireguard-tools on the node and can take up to 2 minutes; the page shows the progress. Later changes apply in seconds.
Check the status: Listening should read yes and Last applied shows the time of the apply. The Readiness checklist below tells you what is still missing.

On a cluster, the VPN belongs to the connection: the page says it applies to the whole cluster and you can open it from any node.

Settings on the node page:

Port: the UDP port (1024 to 65535). New nodes start with the Default port from Settings > VPN (51820).
Subnet: Automatic (the next free /24 in the VPN range, 10.88.0.0/16 by default) or Custom (any private RFC1918 range from /16 to /29). Changing the subnet gives every device a new address, so their configs become outdated.
Endpoint override: the name or IP devices connect to. Devices use, in this order: the node’s active DynDNS name, the endpoint override, then the address the host was added with.
Forward networks: the private networks the VPN routes (bridges, IP zones, SDN subnets). Untick a network that is the same as the network your devices sit in.

Nodes behind a router. If the host was added with a private address (a home lab or office), the card shows the rule to add on your router, for example “Forward UDP 51820 to 192.0.2.20 on your router.”

Readiness checklist

Once the VPN is enabled, Readiness checks the node (Check again reruns it). Each line is OK, a warning, a failure or unknown, with a message and the fix. It checks that:

the agent is installed and current,
the WireGuard tools are installed,
wg-nexovirt is up and listens on the configured UDP port,
IP forwarding is on, so devices reach guest networks,
no other firewall on the node seems to block the VPN port,
the endpoint name resolves to the node’s public IPv4 (compared against DynDNS or the node’s own address); a name that resolves to a private address is a warning,
a device has connected recently. “No device has ever connected” comes with the exact port forward to add, for example “Allow/forward UDP 51820 to 192.0.2.20 in your router or provider firewall.”

Saving the node’s VPN settings again fixes most failures: the agent reinstalls the tools, brings the interface up and turns IP forwarding on.

Subnets and conflicts

Every node gets its own VPN subnet; the node uses the first address and devices get the others. A VPN subnet never overlaps a network the panel already knows: inventory networks, IP zones, SDN subnets, NAT ranges, other nodes’ VPN subnets and your Client networks. An overlap is refused with a message naming the conflicting network. The check runs again before every apply, so a network added later puts the node into an error state instead of silently routing a conflicting range. New IP zones and SDN subnets that overlap a VPN subnet are refused too.

In Settings > VPN, VPN range & client networks:

VPN range: where automatic subnets come from. Changing it does not move existing subnets.
Default port: the port new nodes start with.
Customer device limit: devices per customer (default 5).
Client networks: the networks your devices live in (home LAN, office), one per line, for example 192.0.2.0/24. They are never routed through the tunnel.

Your VPN configs

On VPN (/panel/vpn), New config asks for a Name (letters, digits, spaces, dots, dashes or underscores; each name once) and what it Reaches:

Reaches	Kind	What the config can reach
All nodes (master config)	Master	Every VPN-enabled node, the nodes themselves and their private guest networks.
A single node	Node	One node or cluster (pick it under Node / cluster).
SDN projects	SDN	Only the subnets of the SDN projects you pick. No node, no LAN, no other project.

You can create as many named configs as you need, for example one per laptop and phone.

Create config: the config is shown once, with a QR code for the WireGuard mobile app, a copy button and a download button. NexoVirt does not keep the private key, so it cannot show it again.
Import the file into the WireGuard app and connect. The nodes apply the new device in the background, usually within a few seconds.

The table shows each config’s Kind, the Nodes it covers (a node with the VPN off is marked), Created, Last config, Last handshake and Status:

Up to date, or Outdated: download a new config when the config no longer matches what the nodes expect (a node was enabled, a subnet changed, a project got its network). Click Download new config: it creates a fresh key pair and shows the new config once; the old one stops working.
No access for an SDN config whose projects are all gone. Revoke it.

Revoke removes a config; its access ends with the next apply. Creating and renewing configs is limited to 5 per minute per owner. The node’s VPN page lists every device that can reach it, with its owner and address on that node.

Security details:

Every new or renewed config gets a random preshared key in addition to the key pair. It is stored encrypted and is part of the one-time config only. Configs created before preshared keys keep working until you renew them.
A device that reaches several nodes has one address per node. Every node knows all of the device’s addresses, so traffic from any of them is accepted.

Customer portal (Enterprise)

On an Enterprise license, customers see a VPN item in the portal. Add device with Reaches my servers (only the customer’s own guests) or Reaches SDN projects (only their own projects). Other guests, the nodes and the panel stay unreachable; the node firewall enforces it. Reachable servers lists what their devices can reach. Each customer can have up to the Customer device limit devices (default 5).

When a server changes owner, is deleted, migrated or failed over, the VPN rules follow within seconds. On the Community Edition the portal VPN item is hidden.

Keeping in sync

Changes (new devices, ownership changes, migrations) are applied in the background. The php spark vpn:sync --once cron job (every 15 minutes, installed by deploy/install-cron.sh) re-applies any node whose VPN state changed, so a missed change heals itself.

Troubleshooting

NX-VPN-0001 (VPN could not be applied on the node): update the agent, check that the node can reach the Debian mirrors for the first install, then save the node’s VPN settings again.
NX-VPN-0002 (VPN subnet conflict): pick a custom subnet for the node, change the VPN range, or fix the client networks.
NX-VPN-0003 (VPN device refused): name taken, device limit reached, too many requests in a minute, or no VPN-enabled node is reachable for this config yet.
NX-VPN-0004 (Customer VPN needs Enterprise): activate an Enterprise license.

See the full error code reference.