DHCPv6 PXE boot fails: dnsmasq template uses option:client-arch (DHCPv4) instead of option6:client-arch (DHCPv6)

[holmboe]

Description

When using IPv6 for the provisioning network (IPV=6), UEFI nodes cannot PXE boot because the dnsmasq config relies on option:client-arch (DHCPv6 option 61) to select the correct bootfile — but neither OVMF nor iPXE sends this option in DHCPv6.

Affected file: ironic-config/dnsmasq.conf.j2 — the {% if env.IPV == "6" %} section

Expected behavior

UEFI nodes receive snponly-x86_64.efi (or snponly-arm64.efi) as the bootfile URL and successfully PXE boot IPA.

Actual behavior

Depending on whether the pxe6 vendor class tag matches:

• If pxe6 is set but amd64 is not: no bootfile-url is sent at all (the EFI rule requires both tag:pxe6,tag:amd64, and the BIOS fallback only fires on tag:!pxe6)
• If pxe6 is not set: undionly.kpxe (BIOS bootloader) is served, which UEFI firmware cannot boot

In either case the node is stuck at the UEFI PXE screen and never boots IPA.

Root cause

The IPv6 section of the dnsmasq template matches client-arch using:

dhcp-match=set:amd64,option:client-arch,7
dhcp-match=set:amd64,option:client-arch,9
dhcp-option=tag:pxe6,tag:amd64,option6:bootfile-url,tftp://…/snponly-x86_64.efi

In DHCPv4, option:client-arch maps to option 93, which PXE firmware reliably sends. The IPv4 section of the template works correctly for this reason.

In DHCPv6, option:client-arch maps to option 61 — but neither OVMF (QEMU's UEFI firmware, both with built-in virtio PXE and with the iPXE efi-virtio.rom option ROM) nor iPXE sends this option in DHCPSOLICIT. This appears to be a gap in the UEFI/iPXE DHCPv6 implementations.

Evidence from dnsmasq logs

When client-arch is received (never, in practice for DHCPv6), the amd64 tag would be set. Instead we see:

dnsmasq-dhcp: vendor class: 343
dnsmasq-dhcp: DHCPSOLICIT(metal3) …
dnsmasq-dhcp: DHCPADVERTISE(metal3) 2001:db8:…::3699 …
dnsmasq-dhcp: requested options: 59:bootfile-url, 60:bootfile-param, 23:dns-server,
dnsmasq-dhcp: requested options: 16:vendor-class
dnsmasq-dhcp: tags: pxe6, dhcpv6, metal3
                     ^^^^               ^^^^^ — no amd64 tag

The pxe6 tag is set (vendor class 343 matches) but amd64 is absent, so the EFI bootfile rule doesn't fire. In some requests even pxe6 isn't set, causing the BIOS fallback to send undionly.kpxe.

The IPv4 path does not have this problem — its dhcp-match=set:efi,option:client-arch,7 works because DHCPv4 clients reliably send option 93.

Environment

• Ironic image: quay.io/metal3-io/ironic:release-34.0
• Provisioning network: IPv6
• Firmware: OVMF (OVMF_CODE_4M.fd) with virtio NIC (tested both with and without efi-virtio.rom iPXE ROM)
• Nodes tested: QEMU/KVM virtual machines via VBMC

Possible fix

Since the pxe6 vendor class tag (enterprise 343, "PXEClient") already indicates a PXE client, and DHCPv6 PXE boot is exclusively UEFI (there is no BIOS PXE over IPv6), the IPv6 section could default to serving the EFI bootfile when pxe6 is set, without requiring client-arch:

dhcp-option=tag:pxe6,option6:bootfile-url,tftp://…/snponly-x86_64.efi

If arm64 differentiation is needed, it could use a separate signal or be configured explicitly. The BIOS fallback (tag:!pxe6 → undionly.kpxe) is arguably unnecessary in the IPv6 path since legacy BIOS does not support IPv6 PXE.

[holmboe]

Some additional analysis (with help from Claude opus-4.6) on the client-side options:

iPXE does not send client-arch by design. The iPXE maintainer calls it an "anti-feature" and it is not built into any iPXE ROM. All efi-*.rom variants ship from the same codebase, so switching NIC model (e1000e, etc.) does not help.

OVMF's built-in PXE client also does not send client-arch (option 61) in DHCPv6.

Here is a summary of what DHCPv6 clients actually send:

Signal	DHCPv6 option	Sent by OVMF	Sent by iPXE ROM
vendor class 343	16	sometimes	sometimes
bootfile-url in ORO	59 (requested)	yes (PXE phase)	yes (PXE phase)
user-class iPXE	15	no	yes
client-arch	61	no	no

Note that the ironic-inspector dnsmasq example also uses option6:61 for DHCPv6 client-arch matching, but this is equally affected since no client sends it.

This confirms that there is no client-side fix. The dnsmasq template must not rely on client-arch in the IPv6 path. Serving the EFI bootfile based on pxe6 (vendor class 343) alone is the correct approach, since legacy BIOS does not support IPv6 PXE boot.

[holmboe]

Root cause: option:client-arch vs option6:client-arch

Further analysis shows that the root cause is a dnsmasq option prefix bug in the template, not clients failing to send option 61.

The current IPv6 section uses option:client-arch, but option: is a DHCPv4-only prefix that resolves to option 93 via dnsmasq's opttab[] (IPv4) table. The resulting match rule is silently added to daemon->dhcp_match (the DHCPv4 match list) and is never evaluated by the DHCPv6 server code in rfc3315.c, which only iterates daemon->dhcp_match6.

The correct DHCPv6 syntax is option6:client-arch, which resolves to option 61 via opttab6[] (IPv6 table).

option6:client-arch already works in the ironic container

Running dnsmasq --help dhcp6 inside the ironic container (CentOS Stream 9, dnsmasq 2.85) confirms that client-arch (61) is a known DHCPv6 option:

dnsmasq --help dhcp6
...
 61 client-arch
 62 client-interface-id
...

This is thanks to a Red Hat downstream patch that has been carried since 2021:

• dnsmasq-2.86-dhcpv6-client-arch.patch by Petr Menšík (pemensik@redhat.com)

The patch adds the missing RFC 5970 entries (client-arch option 61, client-interface-id option 62) to dnsmasq's opttab6[] table. It is included in RHEL 9, CentOS Stream 9, and Fedora packages, but has not been upstreamed.

Both OVMF and iPXE send DHCPv6 option 61

Contrary to the initial analysis in this issue, both EDK2/OVMF and iPXE do send option 61 (Client System Architecture Type) in their DHCPv6 SOLICIT messages:

• EDK2: PxeBcDhcp6.c constructs option 61 via DHCP6_OPT_ARCH with EFI_PXE_CLIENT_SYSTEM_ARCHITECTURE
• iPXE: dhcpv6.c includes DHCPV6_CLIENT_ARCHITECTURE in its option template

The reason the amd64 tag was never set was not that clients don't send the option, but that option:client-arch directed the match rule to the wrong (DHCPv4) match list entirely.

Fix

The fix for the template is to change the IPv6 dhcp-match directives from:

dhcp-match=set:amd64,option:client-arch,7

to:

dhcp-match=set:amd64,option6:client-arch,7

I will submit a PR with this fix shortly.

[Rozzii]

/triage accepted
I will check the PR soon.
/kind feature