From 03129cf654b917d06d699f61d01936a4e3e06969 Mon Sep 17 00:00:00 2001 From: Daniel Hilst <392820+dhilst@users.noreply.github.com> Date: Sat, 7 Nov 2026 19:15:10 -0300 Subject: [PATCH 1/2] test(dhcp): a DHCPv6 client with no reservation is told nothing to boot Sequential discovery over IPv6 starts with a node xCAT has never seen. It has no DUID in the dhcp6duid table, so kea_node_reservations6 writes no reservation for it, and option 59 (bootfile-url) is written only inside a reservation. The subnet carries a dynamicrange, so Kea answers the node with an address and no boot file. Measured on xcat88-mn: an unknown client took 2001:db8:188::1000 from the pool, and the running kea-dhcp6.conf held no client-classes at all. dhcp6_boot_client_classes.t asserts that render_dhcp6_config carries client-classes, that _render_subnet6 scopes a class to its subnet, and that the class builder names a loader per architecture from option 61. Without the fix 10 of its 11 assertions fail. dhcp_kea_plugin_intent.t gains four assertions on the wiring: that kea_subnet6_intent carries the classes and evaluates them only for its own subnet. Emptying the class list in kea_subnet6_intent fails those four and no other test in the file. Signed-off-by: Daniel Hilst <392820+dhilst@users.noreply.github.com> --- xCAT-test/unit/dhcp6_boot_client_classes.t | 91 ++++++++++++++++++++++ xCAT-test/unit/dhcp_kea_plugin_intent.t | 21 +++++ 2 files changed, 112 insertions(+) create mode 100644 xCAT-test/unit/dhcp6_boot_client_classes.t diff --git a/xCAT-test/unit/dhcp6_boot_client_classes.t b/xCAT-test/unit/dhcp6_boot_client_classes.t new file mode 100644 index 0000000000..f8b70d58b1 --- /dev/null +++ b/xCAT-test/unit/dhcp6_boot_client_classes.t @@ -0,0 +1,91 @@ +#!/usr/bin/perl +# A DHCPv6 client with no reservation must still be told what to boot. +# +# Sequential discovery starts with a node xCAT has never seen: it has no DUID in the dhcp6duid +# table and no reservation, so kea_node_reservations6 writes nothing for it. The subnet has a +# dynamicrange, so Kea answers it with an address -- measured on xcat88-mn, where an unknown +# client took 2001:db8:188::1000 from the pool. What it never gets is option 59, bootfile-url, +# because that option is written only inside a reservation. The node boots nothing and +# seq_discovery_ipv6 fails before it powers the node on. +# +# DHCPv4 solves this with client classes keyed on option 93, the client system architecture, each +# naming a boot file. RFC 5970 gives DHCPv6 the same registry in option 61 and the boot file URL +# in option 59, so the same shape works. Two things were missing: +# +# render_dhcp6_config dropped client-classes entirely. render_dhcp4_config renders them. +# _render_subnet6 dropped the additional-class list. _render_subnet4 renders it. +# +# So classes could not reach the config even once something built them. +use strict; +use warnings; +use Test::More tests => 11; +use FindBin; +use lib "$FindBin::Bin/../../perl-xCAT"; +use JSON; + +require xCAT::DHCP::Backend::Kea; +require xCAT::DHCP::BootPolicy; + +my $backend = xCAT::DHCP::Backend::Kea->new( kea_version => '3.0.1' ); + +# --- the renderer must carry classes into Dhcp6 ------------------------------------------------- +my $json = decode_json( + $backend->render_dhcp6_config({ + interfaces => ['eth1'], + subnets => [ { id => 10001, subnet => '2001:db8:188::/64', + additional_client_classes => ['xcat-uefi6-x64'] } ], + 'client-classes' => [ + { name => 'xcat-uefi6-x64', + test => 'option[61].hex == 0x0007', + 'option-data' => [ { name => 'bootfile-url', data => 'tftp://[2001:db8:188::1]/x' } ] }, + ], + }) +); + +ok( exists $json->{Dhcp6}{'client-classes'}, + 'render_dhcp6_config emits client-classes' ) + or diag 'Dhcp6 keys: ' . join( ' ', sort keys %{ $json->{Dhcp6} } ); +is( scalar @{ $json->{Dhcp6}{'client-classes'} || [] }, 1, 'it keeps the one class it was given' ); +is( $json->{Dhcp6}{'client-classes'}[0]{name}, 'xcat-uefi6-x64', 'with its name' ); +is( $json->{Dhcp6}{'client-classes'}[0]{test}, 'option[61].hex == 0x0007', + 'and its option 61 architecture test' ); +is( $json->{Dhcp6}{'client-classes'}[0]{'option-data'}[0]{name}, 'bootfile-url', + 'and the bootfile-url it supplies' ); + +# Kea 3.0.1 takes the modern spelling, the same choice _render_subnet4 already makes. +my $sn = $json->{Dhcp6}{subnet6}[0]; +is_deeply( $sn->{'evaluate-additional-classes'}, ['xcat-uefi6-x64'], + '_render_subnet6 scopes the class to the subnet that named it' ); + +# --- the classes themselves --------------------------------------------------------------------- +my $host = '[2001:db8:188::1]'; + +# An eval, not a bare call: a missing sub would end the file and the assertions below would report +# nothing at all. Absent builder and wrong classes must both read as a failure here. +sub classes6 { + my (%opts) = @_; + my $out = eval { xCAT::DHCP::BootPolicy->kea_client_classes6(%opts) }; + return $out && ref($out) eq 'ARRAY' ? $out : []; +} + +my $classes = classes6( uri_host => $host, ipxe_uefi => 1, tftpdir => '/tftpboot' ); + +my ($x64) = grep { $_->{test} =~ /0x0007/ } @$classes; +ok( $x64, 'an x86_64 UEFI class is built' ); +is( $x64 && $x64->{'option-data'}[0]{data}, + "tftp://$host/xcat/ipxe/x86_64-sb/snponly-shim.efi", + 'it hands the signed iPXE shim, the same first stage a reserved node gets' ); + +my ($aa) = grep { $_->{test} =~ /0x000b/ } @$classes; +is( $aa && $aa->{'option-data'}[0]{data}, "tftp://$host/boot/grub2/grub2.aarch64", + 'aarch64 gets its grub2 loader' ); + +my ($rv) = grep { $_->{test} =~ /0x001b/ } @$classes; +is( $rv && $rv->{'option-data'}[0]{data}, "tftp://$host/boot/grub2/grub2.riscv64", + 'riscv64 gets its grub2 loader' ); + +# Naming a file the TFTP server does not have costs the client a timeout it cannot diagnose, which +# is the reason the DHCPv4 classes check the loader before naming it. +my $no_loader = classes6( uri_host => $host, ipxe_uefi => 0, tftpdir => '/tftpboot' ); +is( scalar( grep { $_->{test} =~ /0x0007/ } @$no_loader ), 0, + 'with no iPXE shim on disk the x86_64 class is left out rather than pointing at nothing' ); diff --git a/xCAT-test/unit/dhcp_kea_plugin_intent.t b/xCAT-test/unit/dhcp_kea_plugin_intent.t index 03eff1bce0..ce94e2e345 100644 --- a/xCAT-test/unit/dhcp_kea_plugin_intent.t +++ b/xCAT-test/unit/dhcp_kea_plugin_intent.t @@ -266,6 +266,27 @@ my %network_entry = ( is_deeply( [ grep { /^xcat-ipxe-net-/ } @{ $subnet->{additional_client_classes} } ], [], 'without the upstream loader on this server, the Kea subnet names no network script' ); + # The DHCPv6 subnet answers an unknown client the same way, with option 59 instead of a boot + # file name. Without these a node being discovered gets a pool address and nothing to boot, + # which is where seq_discovery_ipv6 stops: the DUID cannot be reserved before it is known. + my %entry6 = ( net => '2001:db8:188::/64', mgtifname => 'eth1', mask => '64', + dynamicrange => '2001:db8:188::1000-2001:db8:188::1fff' ); + my $subnet6 = xCAT_plugin::dhcp::kea_subnet6_intent( \%entry6, 'eth1', 0, 10001 ); + my %classes6 = map { $_->{name} => $_ } @{ $subnet6->{client_classes} || [] }; + ok( $classes6{'xcat-aarch64-6-10001'}, + 'the Kea DHCPv6 subnet carries boot classes for an unreserved client' ) + or diag 'classes: ' . join( ' ', sort keys %classes6 ); + is( $classes6{'xcat-aarch64-6-10001'} && $classes6{'xcat-aarch64-6-10001'}{'option-data'}[0]{name}, + 'bootfile-url', 'and each one supplies bootfile-url, which is option 59' ); + is( $classes6{'xcat-aarch64-6-10001'} && $classes6{'xcat-aarch64-6-10001'}{'option-data'}[0]{data}, + 'tftp://[2001:db8::1]/boot/grub2/grub2.aarch64', + 'naming the management node facing this network, bracketed for a URL' ); + is_deeply( + [ grep { /^xcat-aarch64-6/ } @{ $subnet6->{additional_client_classes} || [] } ], + ['xcat-aarch64-6-10001'], + 'and the class is evaluated only for the subnet it was built for', + ); + local *xCAT_plugin::dhcp::kea_ipxe_loader_flags = sub { return ( ipxe_bios => 1, ipxe_uefi => 1 ); }; $subnet = xCAT_plugin::dhcp::kea_subnet4_intent( $nettab, '10.0.0.0', '255.255.255.0', 'eth0', 0, 1, 80 ); %classes = map { $_->{name} => $_ } @{ $subnet->{client_classes} }; From 69737e20ffda937939b9ce5f6e6c4053b57bb1b8 Mon Sep 17 00:00:00 2001 From: Daniel Hilst <392820+dhilst@users.noreply.github.com> Date: Sat, 7 Nov 2026 19:15:27 -0300 Subject: [PATCH 2/2] fix(dhcp): a DHCPv6 client with no reservation is told nothing to boot A node that xCAT has not yet discovered has no DUID, so kea_node_reservations6 writes no reservation for it. Option 59, bootfile-url, is written only inside a reservation, so Kea answers the node with an address from the dynamicrange and no boot file. The node boots nothing, and sequential discovery over IPv6 cannot start: xCAT learns the DUID from the Genesis image, and the image needs a boot file to run. DHCPv4 answers an unknown client from client classes keyed on option 93, the client system architecture. RFC 5970 gives DHCPv6 the same registry in option 61 and the boot file URL in option 59, so the same shape applies. Two places dropped it: render_dhcp6_config did not render client-classes, which render_dhcp4_config has always done. _render_subnet6 did not render the additional-class list, which _render_subnet4 renders. Both now render them. kea_client_classes6 builds one class per architecture: the signed iPXE shim for a UEFI x86_64 client when the loader is on disk, and the grub2 loader for aarch64, riscv64 and ppc64. kea_subnet6_intent builds them per network, because option 59 carries a server and that server is the management node facing that network, and names them per subnet so two provisioning networks cannot collide. A node with a reservation keeps the boot file the reservation carries. The classes answer only what no reservation matched. Signed-off-by: Daniel Hilst <392820+dhilst@users.noreply.github.com> --- perl-xCAT/xCAT/DHCP/Backend/Kea.pm | 14 ++++++ perl-xCAT/xCAT/DHCP/BootPolicy.pm | 72 ++++++++++++++++++++++++++++ xCAT-server/lib/xcat/plugins/dhcp.pm | 36 ++++++++++++++ 3 files changed, 122 insertions(+) diff --git a/perl-xCAT/xCAT/DHCP/Backend/Kea.pm b/perl-xCAT/xCAT/DHCP/Backend/Kea.pm index 626d89afe5..b8b2b4e6f0 100644 --- a/perl-xCAT/xCAT/DHCP/Backend/Kea.pm +++ b/perl-xCAT/xCAT/DHCP/Backend/Kea.pm @@ -132,6 +132,10 @@ sub render_dhcp6_config { $dhcp6{'control-socket'} = $intent->{'control-socket'} if $intent->{'control-socket'}; $dhcp6{'hooks-libraries'} = $intent->{'hooks-libraries'} if $intent->{'hooks-libraries'}; + # Without this a DHCPv6 client that matches no reservation is answered with an address and no + # option 59, so it boots nothing. render_dhcp4_config has always carried the classes. + $dhcp6{'client-classes'} = [ map { $self->_render_client_class($_) } @{ $intent->{'client-classes'} } ] + if $intent->{'client-classes'}; $dhcp6{'option-data'} = _render_option_data( $intent->{'option-data'} ) if $intent->{'option-data'}; $dhcp6{'dhcp-ddns'} = $intent->{'dhcp-ddns'} if $intent->{'dhcp-ddns'}; @@ -1003,6 +1007,16 @@ sub _render_subnet6 { $rendered{'option-data'} = _render_option_data( _first_defined( $subnet->{'option-data'}, $subnet->{option_data} ) ); + # The boot file of one provisioning network must not be offered on another: the server address + # in the URL belongs to the network the class was built for. + my $additional_classes = _first_defined( + $subnet->{additional_client_classes}, + $subnet->{'evaluate-additional-classes'}, + $subnet->{evaluate_additional_classes}, + $subnet->{'require-client-classes'}, + $subnet->{require_client_classes}, + ); + $rendered{ $self->_additional_class_list_field() } = $additional_classes if defined $additional_classes; $rendered{reservations} = _render_entry_option_data( $subnet->{reservations} ) if $subnet->{reservations}; delete $rendered{'option-data'} unless defined $rendered{'option-data'}; diff --git a/perl-xCAT/xCAT/DHCP/BootPolicy.pm b/perl-xCAT/xCAT/DHCP/BootPolicy.pm index 99a9bc0403..f8125fb1c8 100644 --- a/perl-xCAT/xCAT/DHCP/BootPolicy.pm +++ b/perl-xCAT/xCAT/DHCP/BootPolicy.pm @@ -3,6 +3,7 @@ package xCAT::DHCP::BootPolicy; use strict; use warnings; use xCAT::HTTPUtils qw(httpport_suffix); +use JSON; sub kea_client_classes { my ( $class, %opts ) = @_; @@ -77,6 +78,77 @@ sub kea_client_classes { return \@classes; } +# The boot file for a DHCPv6 client that matches no reservation. +# +# RFC 5970 gives DHCPv6 the client system architecture in option 61, from the same registry as +# option 93 on DHCPv4, and the boot file URL in option 59. So the shape of kea_client_classes +# above carries over: one class per architecture, each naming what that architecture can load. +# +# The URL is absolute and carries the server, which option 59 requires and boot-file-name does +# not. uri_host is already bracketed for a literal IPv6 address. +# +# Without these classes an unknown client is answered with an address from the pool and no option +# 59 at all, which is what stops sequential discovery over IPv6: the node has to boot the Genesis +# image before xCAT knows its DUID, and it cannot be given a reservation before it is known. +sub kea_client_classes6 { + my ( $class, %opts ) = @_; + + my $host = $opts{uri_host}; + return [] unless $host; + # One network's classes must not take another's names: the server in each URL is the address + # of the network the class was built for. + my $sfx = defined( $opts{suffix} ) && length( $opts{suffix} ) ? "-$opts{suffix}" : ''; + + my @classes; + + # A UEFI client is the only x86 client that solicits over DHCPv6, so the BIOS loader has no + # DHCPv6 class. Both architecture ids are in use: firmware reports 0x0007, and 0x0009 appears + # on the same machines once the loader chainloads. + if ( $opts{ipxe_uefi} ) { + my $loader = $class->x86_loader( method => 'ipxe' )->{uefi}; + if ($loader) { + foreach my $arch (qw(0x0007 0x0009)) { + push @classes, { + name => "xcat-uefi6-x64-$arch$sfx", + test => "option[61].hex == $arch", + 'option-data' => [ kea_bootfile_url6_option("tftp://$host/$loader") ], + }; + } + } + } + + # grub2 ships these two names for every build, so they are named unconditionally. A client + # whose loader is missing gets a timeout either way, and leaving the class out would make an + # aarch64 node look unserved rather than unprovisioned. + push @classes, ( + { + name => "xcat-aarch64-6$sfx", + test => 'option[61].hex == 0x000b', + 'option-data' => [ kea_bootfile_url6_option("tftp://$host/boot/grub2/grub2.aarch64") ], + }, + { + name => "xcat-riscv64-6$sfx", + test => 'option[61].hex == 0x001b', + 'option-data' => [ kea_bootfile_url6_option("tftp://$host/boot/grub2/grub2.riscv64") ], + }, + { + name => "xcat-ppc64-6$sfx", + test => 'option[61].hex == 0x000c', + 'option-data' => [ kea_bootfile_url6_option("tftp://$host/boot/grub2/grub2.ppc") ], + }, + ); + + return \@classes; +} + +# always-send, because a client that does not ask for option 59 by name still needs it: the +# reservations written by kea_node_reservations6 set the same flag for the same reason. +sub kea_bootfile_url6_option { + my ($url) = @_; + + return { name => 'bootfile-url', data => $url, 'always-send' => JSON::true() }; +} + #: Every client architecture some class here, or in the per-network classes #: beside it, already answers. The fallback is what is left over. my @RECOGNISED_ARCH_IDS = qw( diff --git a/xCAT-server/lib/xcat/plugins/dhcp.pm b/xCAT-server/lib/xcat/plugins/dhcp.pm index 78ada7ee89..7ed77340bc 100644 --- a/xCAT-server/lib/xcat/plugins/dhcp.pm +++ b/xCAT-server/lib/xcat/plugins/dhcp.pm @@ -3260,12 +3260,18 @@ sub kea_build_dhcp6_intent } $nettab->close; + my @subnet_classes; + foreach my $subnet (@subnets) { + push @subnet_classes, @{ delete $subnet->{client_classes} || [] }; + } + my $intent = { interfaces => \@interfaces, preferred_lifetime => kea_dhcp_lease_time(), valid_lifetime => kea_dhcp_lease_time(), subnets => \@subnets, }; + $intent->{'client-classes'} = \@subnet_classes if @subnet_classes; # As for DHCPv4: the socket is how a reload is confirmed, so it is not # conditional on the Control Agent. @@ -3323,6 +3329,15 @@ sub kea_subnet6_intent ); $subnet{interface} = $interface unless $remote || $interface eq '*'; + # A client with no reservation is answered from the pool above, and option 59 is written only + # inside a reservation, so without these classes it is told an address and nothing to boot. + # That is what stops discovery: the node must boot Genesis before xCAT can know its DUID. + my @classes = @{ kea_boot_client_classes6( $net, $id ) }; + if (@classes) { + $subnet{client_classes} = \@classes; + $subnet{additional_client_classes} = [ map { $_->{name} } @classes ]; + } + return \%subnet; } @@ -5281,6 +5296,27 @@ sub kea_boot_client_classes return xCAT::DHCP::BootPolicy->kea_client_classes( kea_ipxe_loader_flags() ); } +# The DHCPv6 classes for one network. The boot URL carries a server, so it is built per network +# from the address of the management node facing that network -- the same source +# dhcp6_boot_server_for_node uses for a node. +sub kea_boot_client_classes6 +{ + my ( $net, $id ) = @_; + + my $peer = defined($net) ? $net : ''; + $peer =~ s{/.*$}{}; + return [] unless length($peer); + + my @facing = xCAT::NetworkUtils->my_ip_facing_family( $peer, 6 ); + return [] unless @facing && !$facing[0] && $facing[1]; + + my $uri_host = xCAT::NetworkUtils->format_uri_host( $facing[1] ); + return [] unless $uri_host; + + return xCAT::DHCP::BootPolicy->kea_client_classes6( + kea_ipxe_loader_flags(), uri_host => $uri_host, suffix => $id ); +} + # Which upstream loader files the local TFTP tree has, as the Kea class builders take them. sub kea_ipxe_loader_flags {