DHCP relay on shared networks

A DHCP relay (IP helper) forwards DHCP requests from a remote subnet to a central DHCP server. When nodes on a remote subnet boot through a relay, luna's DHCP server (Kea or ISC dhcpd) must be told which relay source address belongs to which subnet so it hands out the right lease. Luna's dhcp_relay setting on a network provides that mapping.

Setting a relay

dhcp_relay takes one or more relay source IPs, comma-separated. These are the addresses from which relayed DHCP traffic arrives (the relay/giaddr addresses on the remote gateways).

luna network change <network> --shared <base-network>
luna network change <network> --dhcp_relay 10.141.255.1
luna network change <network> --dhcp_relay 10.141.255.1,172.16.255.1     # multiple relays

Short flag -dr is equivalent to --dhcp_relay. In luna network show the setting appears under shared, next to the other shared-network fields.

Clearing a relay

Pass an empty string to remove the relay mapping:

luna network change <network> --dhcp_relay ""

Clearing is always allowed, including on a network that is no longer shared. Clearing the relay also clears any link-selection anchor on the network (see below): the anchor only has meaning on a relayed path, so it is removed with the relay rather than left orphaned.

Selecting the subnet by link (option 82.5)

A relay usually identifies the subnet by its own source address (the giaddr). On some topologies that is not enough — the relay's address does not sit inside the subnet the client is really on, or one relay fronts several links. For those, RFC 3527 defines option 82, sub-option 5 (link-selection): the relay adds the client's actual link prefix to the request, and the DHCP server selects the subnet from that prefix instead of from the giaddr.

Luna's dhcp_link_subnet sets the link prefix(es) that identify this network, so Kea can match a relayed request by its option-82.5 link address:

luna network change <network> --dhcp_link_subnet 10.141.0.0/16
luna network change <network> --dhcp_link_subnet 10.141.0.0/16,2001:db8:141::/64   # per family

Short flag -dls is equivalent to --dhcp_link_subnet. The value is one or more CIDR prefixes, IPv4 and/or IPv6, comma-separated; each is sorted into the matching address family automatically.

Two rules apply:

• It requires a relay. dhcp_link_subnet only makes sense on a relayed path, so dhcp_relay must be set first; a request without one is rejected.
• The anchor must differ from the network's own subnet. A link prefix equal to this network's own subnet would render a duplicate subnet inside the same shared network, which Kea refuses — and the whole configuration then fails to load. Use the prefix of the link the relay reports, not the boot subnet itself.
• A link prefix may be used once. The same prefix on a network in a different shared group is refused for the same reason: two blocks cannot both carry it. Within one group it is set on a single member and applies to all of them.

Clear the anchor by passing an empty string (this also happens automatically when the relay is cleared):

luna network change <network> --dhcp_link_subnet ""

What gets rendered

When a relay is set, luna's Kea configuration for that subnet gains a relay block listing the source addresses:

"relay": { "ip-addresses": [ "10.141.255.1", "172.16.255.1" ] }

When dhcp_link_subnet is also set, a small, pool-less anchor subnet carrying the link prefix is placed at the head of the shared network this network belongs to. A relayed request that arrives with an option-82.5 link address in that prefix is matched to the anchor and served its lease and boot options from whichever subnet in that block holds its reservation or pool.

The anchor applies to the whole group, so set it on one member. Every pool in a block that carries an anchor is fenced by client class: a request arriving with a link-selection sub-option that is not a netboot client is not served, so devices on the link prefix that are not part of the cluster cannot draw from a cluster pool.

Luna regenerates the DHCP server configuration, validates it, and restarts the service automatically when the relay or link setting changes — there is no manual apply or verify step. The rendered config is checked with the server's own test before it is installed, and an invalid one is logged and left unapplied, so a live config is always valid.

Ignoring the sub-option instead

Where a relay sets option 82.5 but you do not want its prefix in the configuration, and each link has its own giaddr, Kea can be told to ignore the sub-option and select on the giaddr — which luna already knows from dhcp_relay. It is a server-wide setting in luna.ini, off by default:

[DHCP]
IGNORE_LINK_SELECTION = yes

Restart the daemon (systemctl restart luna2-daemon) after changing it.

See Shared network shapes: worked examples for the two side by side, and for the shapes these settings combine into.