steward/docs/subnets.md

Subnets, pools, reservations and leases

Subnets and interfaces

A subnet is an IPv4 network Steward hands addresses out in, served on one network interface:

steward subnet add 10.0.10.0/24 --interface eth0 --name office \
    --pool 10.0.10.100-10.0.10.199 --option routers=10.0.10.1

The interface decides. stewardd opens one socket on port 67 per interface that has a subnet, bound to that interface. A request is answered only from the subnets of the interface it came in on. A client on eth0.20 never gets an eth0 address, even if it asks for one. It gets a NAK, then an address of its own VLAN.

For VLANs, give the server an interface on each, such as eth0.20, or a bridge such as br-iot, each with an address in its subnet. That address is the server identifier clients see, and the one they renew their lease with. steward interface list shows the server's interfaces with their addresses and subnets.

An interface that doesn't exist yet is fine. The subnet gets a warning (interface_unknown), and stewardd starts serving it within 30 seconds of the interface appearing. steward status and the dashboard show each interface's state; when one isn't served, they say why.

Several subnets on one interface form a shared network: two networks on the same wire, the server with an address in each. Addresses come from the first subnet's pools, then the next. Clients of every subnet are answered from the interface's address in their own subnet, or its first address.

A subnet can be disabled: its configuration and leases stay, but its clients get no answers (steward subnet disable NAME, or Disable in the web UI).

Pools

Pools are the ranges handed out to any client: FIRST-LAST, or a prefix, 10.0.10.128/25. A subnet may have several pools, or none if only clients with a reservation should get addresses. Pools must be inside the subnet, must not overlap, and can't include the network or broadcast address.

Pool sizes are shown as the addresses that can really be handed out. Reserved addresses inside a pool don't count, since nobody else gets them.

Reservations

A reservation fixes a client's address:

steward reservation add 10.0.10.20 aa:bb:cc:dd:ee:01 --hostname nas
steward lease reserve 10.0.10.57       # the address a client has now

• The client is known by its MAC address, or by its client identifier (option 61) when the reservation has one (--client-id; give - as the MAC). Some devices change their identifier but not their MAC address, and others the other way round. When unsure, use the MAC address.
• The address picks the subnet: the subnet whose network holds it. It may be inside a pool or outside one; either way, nobody else gets it.
• The host name is sent to the client (option 12).
• Options set on the reservation are for that client only, and win over the subnet's and the settings'.
• A device on two VLANs can have a reservation in each subnet. Within one subnet, a client has at most one.

A reservation can be disabled (steward reservation disable RES, or Disable in the web UI). It is kept but ignored: the client gets a pool address like any other, and the reserved address, if it is inside a pool, may go to someone else. The client keeps the address it has until its lease runs out. While it is disabled, another reservation may use its address or client; enabling it again is then refused until one of them moves.

A client with a reservation always gets that address, not a pool address. If it asks for another one, for example after the reservation was added, it gets a NAK that names its reserved address, and then the reservation.

Options

Options are set at three levels. A reservation's win over its subnet's, and a subnet's over the settings' (the options every subnet gets):

steward settings set --option domain-name-servers=10.0.10.2 --option domain-name=lan
steward subnet update office --option routers=10.0.10.1 --option ntp-servers=10.0.10.2
steward reservation update nas --option domain-name-servers=1.1.1.1

--option NAME=VALUE sets one and keeps the others; --unset-option NAME removes one. options.md lists the names, and how to write each kind of value. Any other option can be set by number, with its type: --option 224:string=hello.

Every reply carries the subnet mask, the server identifier and, for a lease, the lease time and the times to renew (half of it) and rebind (7/8 of it). With a parameter request list (most clients send one), the client gets the options it asked for, in its order. The subnet mask, routers, DNS servers, domain name and host name are sent even if it didn't ask. Without a list, it gets every option set for it.

Lease times

The settings have the default (12 hours, steward settings set --lease-time 1d); a subnet can have its own (--lease-time 1h). Clients renew halfway through. Short times let changes reach clients sooner; long ones keep clients working longer if Steward is down.

How an address is chosen

For a DISCOVER, Steward offers, in this order:

1. the client's reservation in a subnet of the interface;
2. the address the client had before, from its last lease, even if that ended, as long as it is still free and in a pool;
3. the address the client asks for (option 50), if it is free and in a pool;
4. a free pool address: one never handed out before, else the one that has been free the longest.

An address is free when no other client has an active lease on it, it isn't held back, and it isn't offered to someone else in the last minute. The server's own addresses are never offered. A fresh pool address is pinged first: if something answers, it is held back and the next one is tried.

When the client confirms with a REQUEST, the lease is saved, and only then is the ACK sent.

Leases

State	Meaning
active	the client holds the address until the lease ends
expired	the lease ran out; the client gets the address back if it returns while it is free
released	the client gave the address back
held back	a client declined the address because another device answered for it, or it answered Steward's ping. It isn't handed out until the hold ends (a day; --decline-hold)

steward lease list shows active and held-back leases; --all shows the others too. Leases that ended more than 30 days ago are deleted.

steward lease delete IP frees an address at once. A client still using it gets a NAK when it next renews, then asks for a new address.

Authority

Steward is authoritative for its interfaces. A client that asks to keep an address that doesn't belong on its interface, or that someone else holds, gets a NAK and starts over at once, rather than keeping a wrong address until its lease runs out. Turn this off (steward settings set --authoritative off) only when another DHCP server serves the same network. Requests for addresses Steward knows nothing about then get no answer.

Not in 0.1

Relayed requests (with giaddr) are ignored and logged once an hour: a subnet must be on one of the server's own interfaces. DHCPv6, failover, client classes and DNS names through Jarl are planned (design.md).