jezahost
· updated November 15, 2026
  • ipv6
  • windows-server
  • proxmox
  • cloudbase-init

IPv6 on Windows Server with cloudbase-init: why it breaks, and how we fixed it without touching the guest

Adding ip6= to a Windows VM's ipconfig0 on Proxmox wipes IPv4. Here is why cloudbase-init does that, the two obvious fixes we rejected, and the metadata-driven approach we shipped.

We recently rolled out native IPv6 to every VPS we offer. Linux was uneventful: Proxmox writes the address into the cloud-init drive, cloud-init applies it on the next boot, done. Windows Server was a different story. This is a write-up of what went wrong, why, and the approach we ended up with. If you run Windows guests on Proxmox with cloudbase-init, the first half of this article will probably save you an afternoon.

The setup

Our Windows images are standard Windows Server 2025 templates with cloudbase-init installed and configured to read the Proxmox ConfigDrive. Proxmox generates an ISO labelled config-2 that contains openstack/latest/meta_data.json plus a network configuration file. cloudbase-init reads it at first boot: hostname, admin password, network settings. That part had been working for months.

For IPv6 we did the obvious thing and added ip6=...,gw6=... to the VM's ipconfig0, exactly as for Linux.

What happened

The test VM came up with its IPv6 address and no IPv4. The adapter had only an APIPA (169.254.x.x) address. The server was reachable over IPv6, but every IPv4 path to it, including the one our provisioning pipeline relies on, was gone.

Why

Proxmox writes the network configuration in Debian ENI format (/etc/network/interfaces style). For a dual-stack interface it produces two stanzas:

auto eth0
iface eth0 inet static
    address 10.0.0.5
    netmask 255.255.255.0
    gateway 10.0.0.1

iface eth0 inet6 static
    address 2001:db8::5
    netmask 64
    gateway 2001:db8::1

cloudbase-init's ENI parser (debiface.py) was written with IPv4 in mind. It does not treat the inet6 stanza as the same interface. Instead it reads both stanzas as two interface definitions, and because the second one has no IPv4 fields it ends up configuring the adapter once more, from the IPv6 stanza only. The IPv4 settings are overwritten in the process. The documented way to get IPv6 through cloudbase-init's ENI parser is a post-up ip -6 addr add ... line, which Proxmox does not generate.

So the failure is not a Windows problem and not a Proxmox problem. It is a format mismatch between two tools that were never tested together for dual-stack.

Option 1 we rejected: guest agent exec

The first fix that comes to mind is to skip cloudbase-init and push the address in via the QEMU guest agent: qm guest exec <vmid> -- netsh interface ipv6 add address .... It works. We rejected it anyway.

In Proxmox the permission that allows guest-exec is VM.GuestAgent.Unrestricted. There is no narrower "run this one command" privilege. Granting it to the token our customer portal uses would mean the portal could execute arbitrary commands as SYSTEM inside every guest on the cluster. A portal is an internet-facing web application. That is not a trade we were willing to make for an IPv6 address.

Option 2 we rejected: regenerate the instance

cloudbase-init runs its plugins once per instance ID. Changing the ID forces everything to run again, including the network plugin. It also re-runs SetUserPassword, which resets the administrator password to whatever is in the metadata. For a customer who changed their password after provisioning, that is a nasty surprise.

What we did instead

The guest configures itself, from metadata it already has access to, with no new privileges anywhere.

  1. Metadata. The portal writes an extra, vendor-prefixed key into meta_data.json (something like "<vendor>": {"ipv6": {"address": ..., "prefix": 64, "gateway": ..., "mac": ...}}). cloudbase-init ignores keys it does not know. ipconfig0 is left IPv4-only, so the ENI parser never sees an inet6 stanza and IPv4 stays intact.
  2. Drive refresh. After writing the key, the portal asks Proxmox to regenerate the cloud-init drive (PUT /nodes/{node}/qemu/{vmid}/cloudinit). This needs only the permissions the portal already had. The guest sees the new ISO content immediately, no reboot.
  3. A small sync script in the template. C:\ProgramData\<vendor>\<script>.ps1, run by a scheduled task as SYSTEM at startup and every two minutes. It:
    • finds the volume labelled config-2 and reads meta_data.json;
    • locates the adapter by MAC, not by name ("Ethernet" vs "Ethernet 2" is not something you want to depend on);
    • waits until the adapter has a real IPv4 address before doing anything, so it never races cloudbase-init on first boot;
    • if the key is present and the address is missing: netsh interface ipv6 add address ... store=persistent plus a default route, and records what it did in a small state file;
    • if the key is gone and the state file says we added an address: removes it;
    • never touches IPv4.
  4. Verification. The portal confirms the result through the guest agent's read-only network-get-interfaces call, which needs only the audit privilege. A row shows "applied" only when the address is actually visible inside the guest, not when we think it should be.

Two gotchas on the scheduled task:

  • Register-ScheduledTask rejects RepetitionDuration = [TimeSpan]::MaxValue with "The task XML contains a value which is incorrectly formatted or out of range". Just omit the duration; on Server 2016+ that means indefinite.
  • Make the installer idempotent (unregister, overwrite, re-register). You will run it more than once while building the template.

Results

Enable from the portal: address visible in the guest in about 60 seconds, IPv4 untouched. Survives reboot. Disable: address gone in about 60 seconds. Rebuilding the VM from the template re-applies it with no manual steps, because the metadata key is carried over. A customer-facing Windows order with IPv6 ticked gets its address roughly five minutes after first boot, which is cloudbase-init's own specialize and reboot cycle plus one task interval.

Existing VMs built from the old template do not have the script. We chose not to retrofit them; IPv6 on Windows is available for new servers and for rebuilds.

Takeaways

  • Proxmox + cloudbase-init + dual-stack ipconfig0 is broken out of the box. Test it before you ship it.
  • "Just use guest exec" has a permission cost that is easy to underestimate.
  • Letting the guest pull its own configuration from metadata it already trusts is boring, needs no new privileges, and is the approach that actually held up.