DHCP and iPXE Server
[!IMPORTANT]
The Smee repo has been deprecated. All functionality has been moved to https://github.com/tinkerbell/tinkerbell. For more details, see the roadmap issue #41. This repository is scheduled for archive by the end of 2025.
Smee is the network boot service in the Tinkerbell stack, formerly known as Boots. It is comprised of the following services.
DHCP Reservation: A fixed IP address that is reserved for a specific client.
DHCP Lease: An IP address, that can potentially change, that is assigned to a client by the DHCP server. The IP is typically pulled from a pool or subnet of available IP addresses.
ProxyDHCP: "[A] Proxy DHCP server behaves much like a DHCP server by listening for ordinary DHCP client traffic and responding to certain client requests. However, unlike the DHCP server, the PXE Proxy DHCP server does not administer network addresses, and it only responds to clients that identify themselves as PXE clients. The responses given by the PXE Proxy DHCP server contain the mechanism by which the client locates the boot servers or the network addresses and descriptions of the supported, compatible boot servers." -- IBM
Smee's DHCP functionality can operate in one of the following modes:
DHCP Reservation
To enable this mode set -dhcp-mode=reservation.
Smee will respond to DHCP requests from clients and provide them with IP and next boot info when netbooting. This is the default mode. IP info is all reservation based. There must be a corresponding Hardware record for the requesting client's MAC address.
Proxy DHCP
To enable this mode set -dhcp-mode=proxy.
Smee will respond to PXE enabled DHCP requests from clients and provide them with next boot info when netbooting. In this mode an existing DHCP server that does not serve network boot information is required. Smee will respond to PXE enabled DHCP requests and provide the client with the next boot info. There must be a corresponding Hardware record for the requesting client's MAC address. The auto.ipxe script will be served with the MAC address in the URL and the MAC address will be used to lookup the corresponding Hardware record. Layer 2 access to machines or a DHCP relay agent that will forward the DHCP requests to Smee is required.
Auto Proxy DHCP
To enable this mode set -dhcp-mode=auto-proxy.
Smee will respond to PXE enabled DHCP requests from clients and provide them with next boot info when netbooting. In this mode an existing DHCP server that does not serve network boot information is required. In this mode, if no corresponding Hardware record is found for the requesting client's MAC address, Smee will provide the client with a statically defined iPXE script. If a Hardware record is found, then the normal auto.ipxe script will be served. Use -backend-noop-enabled to disable all backend look ups. Layer 2 access to machines or a DHCP relay agent that will forward the DHCP requests to Smee is required.
-dhcp-mode=auto-proxy-osie-url -tink-server -extra-kernel-args="tink_worker_image=quay.io/tinkerbell/tink-worker:"-dhcp-mode=auto-proxy-dhcp-http-ipxe-script-url=https://boot.netboot.xyz-dhcp-http-ipxe-script-prepend-mac=falseDHCP disabled
To enable this mode set -dhcp-enabled=false.
Smee will not respond to DHCP requests from clients. This is useful when the network has an existing DHCP server that will provide both IP and next boot info and Smee's TFTP and HTTP functionality will be used. The IP address in the Hardware record must be the same as the IP address of the client requesting the auto.ipxe script. See this doc for more details. In most situations--dhcp-http-ipxe-script-prepend-mac=false should also be set when in this mode.
When a DHCP server exists on the network, Smee should be set to run proxy or auto-proxy mode. This will allow Smee to provide the next boot information to clients that request it. The existing DHCP server will provide the IP address and other network boot details. Layer 2 access to machines or a DHCP relay agent that will forward the DHCP requests to Smee is required.
It is not recommended, but it is possible for Smee to be run in reservation mode in networks with another DHCP server(s). To get the intended behavior from Smee one of the following must be true.
All DHCP servers besides Smee are configured to ignore the MAC addresses that Smee is configured to serve.
All DHCP servers are configured to serve the same IP address and network boot details as Smee. In this scenario the DHCP functionality of Smee is redundant. It would be recommended to run Smee with the DHCP server functionality disabled (-dhcp=false). See the doc on using your existing DHCP service for more details.
It's important to note that CLI flags take precedence over environment variables. All CLI flags can be set as environment variables. Environment variable names are the same as the flag names with some modifications. For example, the flag -dhcp-addr has the environment variable of SMEE_DHCP_ADDR. The modifications of CLI flags to environment variables are as follows:
SMEE_-) are replaced with underscores (_)There is one environment variable that does not have a corresponding CLI flag. The environment variable is SMEE_PUBLIC_IP_INTERFACE. This environment variable takes a local network interface name and uses it to auto detect the IP address to use as the default in all other CLI flags that require an IP address. This is useful when the machine running Smee has multiple network interfaces and you want the default detected IP to be from this specified interface.
Running the Tests
# run the tests
make testBuild/Run Smee
…The quickest way to get started is docker-compose up. This will start Smee using the file backend. This uses the example Yaml file (hardware.yaml) in the test/ directory. It also starts a client container that runs some tests.
docker compose up --build # build images and start the network & services
# it's fine to hit control-C twice for fast shutdown
docker compose down # stop the network & containersAlternatively Smee can be run by itself. It requires a few flags or environment variables for configuration.
test/hardware.yaml should be safe enough for most developers to
use on the command line locally without getting a call from your network
administrator. That said, you might want to contact them before running a DHCP
server on their network. Best to isolate it in Docker or a VM if you're not
sure.
…No open issues yet, or sync has not completed.