fedhcp

README

Description

FeDHCP is a DHCP server for the IronCore Project network. It is based on coredhcp.

Plugins

Bluefield

Leases a single IP address to a single client as a non temporary IPv6 address.

Meant to be used in 1:1 client-server connection scenarios, for example a smartnic (Bluefield) leasing a single address to the host.

Configuration

The IP address to lease shall be passed as a string.

Notes

• supports IPv6 addresses only
• IPv6 relays are supported

HTTPBoot

Implements HTTP boot from Unifed Kernel Image.

Delivers the HTTP boot image as a BootFileURL. Based on configuration it delivers either a client-specific UKIs dynamically or a default UKI for all clients. When client-specific UKIs are configured, IPv6 relays must be used, so the client can be identified based on its link-local address (which the relay always provides).

Configuration

A single HTTP(s) URL shall be passed as a string. It must be either

• a direct URL to an UKI (default UKI for all clients)
• magic identifier bootservice:+ a URL to a boot service delivering dynamically client-specific UKIs based on client identification

Notes

• not tested on IPv4
• IPv6 relays are supported
• the only supported client-specific UKI delivery service is the IronCore Boot Operator
• only EFI X64_64 architecture is supported, see https://github.com/ironcore-dev/FeDHCP/issues/154

IPAM

The IPAM plugin acts as a Kubernetes persistence plugin for IronCore's in-band network. Thus, it's meant to be used in combination with the onmetal plugin only. Those two may be consolidated in the future into a new plugin called inband.

The IPAM plugin does not modify DHCP responses to the client, it rather creates (or updates) IP objects in Kubernetes. For each created IP object, the in-band plugin onmetal will lease an IP address to the client. Due to the nature of the IronCore's in-band network - /127 client networks connected to each switch port - the IP object created has and address calculated by a simple "plus one" rule. In such a way each client gets a "plus one" of the switch port address it is connected to.

Configuration

A kubernetes namespace shall be passed as a string. All IPAM processing (subnet identification, IP object creation/update) are done in that namespace. Further, as a second parameter, a comma-separated list of subnet names shall be passed. The IPAM plugin will do the subnet creation based on the IP address of the object to be created as well as on the vacant range of the corresponding subnet.

Notes

• supports only IPv6
• IPv6 relays are mandatory
• shall be used in combination with onmetal plugin
• IP addresses are just created/updated, they are not deleted upon DHCP IP address release. Cleanup process is still tbd.
• depends on IPAM operator

OnMetal

The OnMetal plugin leases a non temporary IPv6 address to an in-band client, based on the algorithm described above.

Configuration

No configuration is needed

Notes

• supports only IPv6
• IPv6 relays are mandatory
• can be used standalone or (in combination with the ipam plugin) in kubernetes

OOB

The OOB plugin leases an IP object to an out-of-band client, based on a subnet detection. The plugin is an equivalent of the metal+ipam kombination, meant to be used in IronCore's out-of-band network.

An IP object with a random IP address from the subnet's vacant list is created in IPAM, the IP address is then leased back to the client. Currently no cleanup-on-release is performed, so clients with stable identifiers are guaranteed to become stable IP addresses.

Configuration

As for in-band, a kubernetes namespace shall be passed as a parameter. Further, a subnet label list in the form value:key shall be passed, it is used for subnet detection.

Notes

• supports both IPv4 and IPv6
• IPv6 relays are supported, IPv4 are not
• other than for in-band, where the DHCP leasing and kubernetes persistence are handled in different plugins, for out-of-band a single plugin is used
• depends on IPAM operator

Metal

The Metal plugin acts as a connection link between DHCP and the IronCore metal stack. It creates an EndPoint object for each machine with leased IP address. Those endpoints are then consumed by the metal operator, who then creates the corresponding Machine objects.

Configuration

Path to an inventory yaml shall be passed as a string. Currently, there are two different ways to provide an inventory list: either by specifying a MAC address filter or by providing the inventory list explicitly. If both a static list and a filter are specified in the inventory.yaml, the static list gets a precedence, so the filter will be ignored.

Providing an explicit static inventory list in inventory.yaml goes as follows:

hosts:
  - name: server-01
    macAddress: 00:1A:2B:3C:4D:5E
  - name: server-02
    macAddress: 00:1A:2B:3C:4D:5F

Providing a MAC address prefix filter list creates Endpoints with a predefined prefix name. When the MAC address of an inventory does not match the prefix, the inventory will not be onboarded, so for now no "onboarding by default" occurs. Obviously a full MAC address is a valid prefix filter. To get inventories with certain MACs onboarded, the following inventory.yaml shall be specified:

namePrefix: server- # optional prefix, default: "compute-"
filter:
  macPrefix:
    - 00:1A:2B:3C:4D:5E
    - 00:1A:2B:3C:4D:5F
    - 00:AA:BB

The inventories above will get auto-generated names like server-aybz.

Notes

• supports both IPv4 and IPv6
• IPv6 relays are supported, IPv4 are not
• depends on metal operator

PXEBoot

The PXEBoot plugin implements an (i)PXE network boot.

When configured properly, the PXEBoot plugin will break the PXE chainloading loop. In such a way legacy PXE clients will be handed out an iPXE environment, whereas iPXE clients (classified based on the user class for IPv6 and IPv4) will get the HTTP PXE boot script.

Configuration

Two parameters shall be passed as strings: an TFTP address to an iPXE environment and an HTTP(s) boot script address. The order matters!

Notes

• relays are supported for both IPv4 and IPv6
• TFTP server as well as HTTP boot script server must be provided externally
• as with HTTPBoot. only EFI X64_64 architecture is supported

License

FeDHCP is licensed under MIT License - Copyright 2018-2024 by coredhcp and the FeDHCP authors.