DynDNS names for Proxmox nodes

DynDNS gives a Proxmox node a stable name under nxvdns.link, for example pve-1.yourlabel.nxvdns.link, that follows the node’s public IPv4 and IPv6. It is free and useful for nodes on a home or office line with a changing address: the WireGuard VPN uses it as the endpoint automatically.

The names, your label and the DNS records are managed by your NexoVirt account. The panel only turns a name on or off for a node and shows its status; the node agent on the node reports the node’s addresses.

Requirements

• The install is claimed to your NexoVirt account. Until then, the DynDNS card and Settings > DynDNS show “Claim this install to your NexoVirt account to use DynDNS names under nxvdns.link.” with a Claim this install link. See Editions.
• Your NexoVirt account has a DynDNS label (claim one in your account under DynDNS). The label is the part between the node name and nxvdns.link.
• The node runs the NexoVirt agent, in a current version. On a cluster the agent runs on one node, and only that node can have a DynDNS name; the card on the other nodes says which node the agent is installed on.
• The number of nodes with a name can be limited by your edition.

Enabling a name

1. Open the node page, Network tab, and scroll to the DynDNS card.
2. Turn the switch on. Setting up the node can take up to 30 seconds.
3. When it is done, the card shows the Name (click it to copy), IPv4, IPv6, Last update and Status.

Right after enabling, the card may say “Waiting for the node’s first IP report.” The agent reports the node’s addresses every 5 minutes (immediately after it is configured), and the name resolves once the first report arrives. A node without a public IPv4 (carrier-grade NAT or DS-Lite) gets a name that resolves over IPv6 only.

Status is Active, or No update for 30 days when the node has not reported for that long (for example because it is offline or the agent was stopped).

The node page’s Overview also shows the DynDNS name in its facts.

Disabling a name

Turn the switch off and confirm Disable. The name is released in your account and stops resolving, and the agent stops updating it.

Names are also released when you remove the agent from a host or delete the host.

Settings > DynDNS

Settings > DynDNS lists every node with a name, grouped by public IPv4 (nodes behind the same address are marked Same network; nodes without one are under No public IPv4). Each row shows the node, the name, the IPv6 address, the last update and the status, and links to the node’s Network tab. Names are enabled and disabled on the node page only.

The panel refreshes these values from your account every 5 minutes with the php spark dyndns:status cron job (installed by deploy/install-cron.sh). It does nothing while no name is enabled.

Use as VPN endpoint

When a node has an active DynDNS name, VPN configs for that node connect to it, ahead of an Endpoint override or the address the host was added with. The VPN readiness checklist compares what the endpoint resolves to with the address reported through DynDNS. See WireGuard VPN.

Troubleshooting

Code	Meaning	What to do
NX-DYNDNS-0001	DynDNS service unreachable.	Try again in a minute. Check that the panel can reach the internet.
NX-DYNDNS-0002	DynDNS request refused.	The message says why: no valid license, no DynDNS label yet, label blocked, the edition’s node limit reached, or a node name that cannot be used.
NX-DYNDNS-0003	Install not claimed.	Claim the install (Settings > Edition & license), then enable DynDNS.
NX-DYNDNS-0004	Node has no agent.	Set up the agent, or enable DynDNS on the node the agent runs on.
NX-DYNDNS-0005	Agent could not be configured.	Check that the agent is online and current, then try again. The name is released again, so nothing is left behind.

See the full error code reference.

What the agent stores

The agent keeps the update token in a root-only file on the node and only sends updates to NexoVirt’s own update endpoints over HTTPS. The panel never stores or shows the token.