1.6 DHCP: scopes and pools

Part 1 · FoundationsOperator⏱ ~30 min▶ Narrated video🖱 Interactive walkthrough🧪 Lab 4 (auto-checked)✓ Knowledge check

So far, Staff VLAN 21 exists only on paper. A DHCP scope turns it into a range that Kea actually serves: a staff laptop plugs in and gets an address, a router and a domain name. In this module you create that scope from the subnet itself, decide which addresses DHCP may hand out, and see how the configuration reaches Kea without anyone logging in to the server.

What you’ll learn

• Explain what a DHCP server group owns, and when it becomes an HA pair
• Create a scope from a subnet, with its initial pool and options
• Choose between dynamic, excluded and reserved pools
• Describe how a scope reaches Kea, and where leases appear

Video and walkthrough

The video starts at the Kea server group, then builds the Staff VLAN 21 scope from the subnet: it narrows the suggested pool to the laptop range, checks the pre-filled router, adds the domain name and excludes the infrastructure range. The walkthrough replays the same clicks.

▶ DHCP: scopes and pools · 2:09 · narrated, captions on (CC) · recorded on SpatiumDDI 1.0.0-beta.3

Chapters

1. 0:00Welcome
2. 0:14The DHCP server group
3. 0:36Create the scope from the subnet
4. 0:53The staff laptop pool
5. 1:12Exclude the infrastructure range
6. 1:27Pools on the address grid
7. 1:42Delivered to Kea
8. 1:56Recap

Transcript

0:00Module 1.6: DHCP scopes and pools. You'll hand out addresses on Ridgeline's staff network: a scope bound to the subnet, a dynamic pool for laptops, and an excluded range for network gear.

0:14Open DHCP. Like DNS, DHCP is organised in server groups, and the Kea container registered itself into this default group. A group with two Kea servers can run them as a high-availability pair, in hot-standby or load-balancing mode. With a single server, as in our lab, it simply serves on its own.

0:36A scope binds an IPAM subnet to a DHCP group. The easiest place to create one is the subnet itself: open Staff VLAN 21, go to DHCP Pools, and choose Create Scope. The group is already filled in, inherited from the campus block.

0:53SpatiumDDI proposes a pool from the subnet. Narrow it to the staff laptop range, from .100 to .199. In the options, the router is already set to the subnet's gateway, 10.20.21.1. Add the domain name, corp.example.edu, then save.

1:12Now keep room for network gear. Add a second pool from .1 to .9 and make it excluded, so DHCP never hands those addresses out. The gateway at .1 sits inside that range, which is exactly why we're excluding it.

1:27Back on the address list, the pool ranges now show up against each address. Next available never picks an address inside the dynamic pool, and a manual allocation there asks you to confirm first, so you don't collide with your own leases.

1:42Nothing needs pushing by hand. The Kea agent picked up the new scope through its configuration long-poll within seconds, and the scope now appears on the group. As clients arrive, their leases show up on each server's Leases tab.

1:56Staff VLAN 21 now has a DHCP scope, a laptop pool and an excluded range for infrastructure, all served by Kea. Next: give Ridgeline's printer a name and an address.

▶ Try it yourself · 21 steps

Nice work — walkthrough complete.
Now do it for real in the lab below.

↺ Replay

← Back

Skip →

Server groups own the configuration

Like DNS, DHCP is organized in server groups, and the group is where configuration lives. Scopes, pools, reservations and client classes all belong to the group, and every server in it renders the same Kea configuration. The lab’s Kea container, dhcp-kea, registered itself into the group default when it started.

The group’s Mode decides how its servers share the work:

Mode	Servers	Behavior
Standalone	One	The server answers on its own
Hot Standby (one active, one passive)	Two Kea	The primary serves every client; the standby takes over when the primary is down
Load Balancing (both active)	Two Kea	Both serve, and Kea splits clients between them

The HA modes need at least two Kea servers with an HA Peer URL. With one Kea server, as in the lab, the HA settings are ignored and the server answers on its own; that’s why the lab’s auto-created group works even though it reads “hot-standby”. With a pair, Kea replicates leases between the two servers itself; module 3.4 covers the design, including what happens when a third server joins, in High availability. The group also sets Client reachability (directly attached or relay-only), which matters once real clients arrive; see the DHCP tips.

Scopes bind a subnet to a group

A scope says: this group’s servers hand out leases on this subnet. The subnet has to exist in IPAM first, and a subnet can have one scope per server group. That’s why you built the address plan before touching DHCP.

The quickest way in is from the subnet. Its DHCP Pools tab has Create Scope, which opens New DHCP Scope with the subnet already pinned and the DHCP Server Group filled in from inheritance, with the note “Inherited group “default” from a parent block.” The dialog also fills in Routers (option 3) with the subnet’s gateway and suggests an initial pool from the tenth host address to the last usable one (.10–.254 on a /24). You can also start from the group’s Scopes tab. The fields that matter first:

• Name: what operators see in lists. Ridgeline uses Staff VLAN 21.
• Initial pool: a first dynamic range (Start IP, End IP), offered only when you create the scope. Ridgeline replaces the suggested 10.20.21.10–10.20.21.254 with 10.20.21.100–10.20.21.199, and SpatiumDDI names that pool default. Kept as suggested, the pool would swallow the fixed addresses of modules 1.7 and 1.8: allocating print-01 would stop for confirmation, and bulk allocate would treat the lab PCs’ addresses as conflicts.
• Lease times: the documented default lease is 86400 seconds (one day).
• Enabled: only active scopes reach Kea. Disabling a scope removes it, and every reservation in it, from Kea’s configuration.
• Options: what clients receive along with the address (see below).

Values you set once in Settings → DHCP Defaults (default DNS servers, domain, NTP servers and lease time) pre-fill every new scope, so set them before you create scopes in bulk.

One scope per subnet per group; pools and reservations live inside the scope · Adapted from the SpatiumDDI documentation (Apache-2.0)

Pools: which addresses DHCP may use

Pools divide the scope’s subnet by purpose. A scope can hold several, and pools in one scope can’t overlap.

Type	Meaning	Rendered into Kea?
Dynamic	Handed out to any eligible client	Yes, as a lease range
Excluded	Part of the subnet, never offered	No: IPAM bookkeeping
Reserved	Held for static assignments, never handed out automatically	No: IPAM bookkeeping

With Kea, only dynamic pools become lease ranges, and Kea hands out dynamic addresses only from those ranges. Ridgeline’s excluded pool, “Network infrastructure” (10.20.21.1–10.20.21.9), makes a promise visible: it marks the range on the address grid, and no dynamic pool can be added over it later. Everything outside the pools (.10–.99 and .200–.254) stays free for the addresses you allocate by hand in module 1.7.

“Pool created — N existing IPs…” is a heads-up, not an error

When you add a dynamic pool over addresses IPAM already records, the pool is saved, but the dialog stays open and lists them under “Pool created — N existing IPs in this range”, because Kea could lease those addresses to other clients. Narrow the pool, or reserve each device’s address (module 1.7), then click OK. Excluded and reserved pools hand out no leases, so they save without the list: Ridgeline’s “Network infrastructure” pool closes at once, even though the gateway sits inside it.

Source: GitHub issue #2445

Pools on the address grid

Once pools exist, the subnet’s IP Addresses tab draws a colored band where each pool starts and ends, such as “START OF DYNAMIC POOL — default” and “START OF EXCLUDED POOL — Network infrastructure”, with the pool’s range beside it. IPAM steers around the dynamic range:

• Next available never picks an address inside a dynamic pool, because that range belongs to Kea.
• A Specific IP inside a dynamic pool gets an amber note under the field (“… is inside the dynamic DHCP pool … Allowed, but the DHCP server may also lease it”), and Allocate stops with a warning and becomes Allocate anyway. It’s allowed because pinning a device inside the pool is standard practice, as long as you also reserve the address for that device (module 1.7): an IPAM row alone doesn’t stop Kea leasing the address to someone else.

Options: what clients receive

Options travel with every lease. The scope’s options editor has labeled fields for the common ones, and a custom-options list for any other option code:

• Routers (option 3): the default gateway. New DHCP Scope fills it in with the subnet’s gateway, 10.20.21.1 for Ridgeline.
• Domain Name (option 15): the DNS domain. Ridgeline’s is corp.example.edu.
• Also available: DNS servers (6), NTP servers (42), domain search (119), and the TFTP and boot-file options (66, 67 and 150) used for PXE.

Options set on the scope apply to its pools unless a pool overrides them, and the group’s Option Templates let you apply a saved set to many scopes. Once saved, Ridgeline’s scope stores {"routers": ["10.20.21.1"], "domain-name": "corp.example.edu"}, and Kea renders both options.

SpatiumDDI checks option values when you save. A value Kea couldn’t parse, such as a mistyped router address, is refused with an error that names the option, so one typo can’t stall the configuration of the whole server group.

How the scope reaches Kea

Nothing is pushed by hand. Seconds after you save, the Kea agent has the new configuration, and the scope appears on the group’s Scopes tab.

Config delivery: a long-poll, not a push

The control plane builds a configuration bundle for the group from the database and hashes it. The Kea agent keeps a long-poll request open, carrying the hash of the bundle it already has. When a change produces a new hash, the request returns at once with the new bundle; a wake message through Redis makes that happen in well under a second. The agent renders Kea’s configuration from the bundle, and Kea checks it before it’s loaded. If Kea rejects it, the agent goes back to its last good configuration and keeps serving. Module 3.1 covers the lifecycle in How SpatiumDDI works.

Leases flow the other way. Each Kea server keeps its own leases, so you read them per server, on the server’s Leases tab, with a lease history kept for 90 days by default. Sync → DHCP on a subnet doesn’t push anything to Kea: it pulls leases from agentless servers such as Windows DHCP.

Note

The Academy lab has no real DHCP clients, because Kea runs on a Docker network with no machines behind it. Leases stay empty, and the labs check the configuration instead. To serve a real LAN from Docker, Kea needs host networking; see the deployment tips.

Hands-on lab

Hands-on lab 4 · about 15 min

Serve DHCP on Staff VLAN 21

You will:

• Create the Staff VLAN 21 scope from the subnet, in the inherited default group
• Replace the suggested pool with 10.20.21.100–10.20.21.199, and set the router and domain-name options
• Exclude 10.20.21.1–10.20.21.9 for network infrastructure
• Confirm that the scope reached the DHCP group

Before you start: Lab 3 is done: Staff VLAN 21 inherits the default DHCP group from the campus block.

1. In IPAM, open 10.20.21.0/24, select the DHCP Pools tab and click Create Scope.
2. In New DHCP Scope, enter the Name Staff VLAN 21. Check that the DHCP Server Group is already filled in and marked as inherited.
3. Under Initial pool, replace the suggested range (10.20.21.10–10.20.21.254): set the Start IP to 10.20.21.100 and the End IP to 10.20.21.199.
4. Check that Routers (option 3) already shows 10.20.21.1, the subnet’s gateway, and leave it as it is.
5. In Domain Name (option 15), enter corp.example.edu, then click Save.
6. Click Add Pool. Enter the name Network infrastructure, the Start IP 10.20.21.1 and the End IP 10.20.21.9, set the Type to Excluded, and save the pool. The dialog closes with no warning, and the pool joins the list on the DHCP Pools tab.
7. Select the IP Addresses tab and find where each pool starts and ends.
8. Go to DHCP, open the default group and its Scopes tab, and check that Staff VLAN 21 is listed.

✅ Check your work from the course folder:./lab/check.sh 4Copy

I finished this lab and the checks pass

Knowledge check

Knowledge check · 6 questions

DHCP: scopes and pools

1. Ridgeline's default DHCP group has a single Kea server. Which Mode fits, and why?

Standalone: HA needs two Kea membersLoad Balancing, because it's faster even with one serverHot Standby, so the server can stand by for itselfIt doesn't matter; the mode is chosen per scope

Hot Standby (one active, one passive) and Load Balancing (both active) render Kea's libdhcp_ha.so hook only when at least two of the group's Kea members have an HA Peer URL. With one Kea member the HA settings are ignored and the server answers on its own, as in the lab, whose auto-created group reads "hot-standby" yet serves from its one server. Mode is a group setting, not a scope setting.

2. What does a DHCP scope do in SpatiumDDI?

It defines a DHCP-only subnet that IPAM doesn't need to know aboutIt's a DNS zone that DHCP clients register their names inIt holds a single reservation for one client's MAC addressIt binds an IPAM subnet to a DHCP server group so it can serve leases

The subnet must exist in IPAM first, and a subnet can have at most one scope per server group. You can create the scope from the subnet's DHCP Pools tab (Create Scope), which pins the subnet and fills in the inherited group, or from the group's Scopes tab.

3. Ridgeline never wants 10.20.21.1–10.20.21.9 offered to clients, because routers and switches live there. Which pool type is that?

DynamicExcludedReservedA second scope

Dynamic pools are handed out to clients, Reserved pools are held for static assignments, and Excluded ranges are part of the subnet but never offered. Ridgeline's dynamic pool is the scope's initial pool, named default (10.20.21.100–10.20.21.199), and .1–.9 is the excluded pool "Network infrastructure". With Kea, only dynamic pools become lease ranges; excluded and reserved pools are IPAM bookkeeping that mark the range on the address grid.

4. With the dynamic pool 10.20.21.100–10.20.21.199 in place, you click Allocate IP → Next available. Why will it never pick 10.20.21.150?

Addresses above .127 are held back for IPv6 on dual-stack subnetsNext available skips addresses inside dynamic DHCP pools.150 is reserved as the gateway for the upper half of the subnetIt will pick it, as soon as .150 is the lowest free address

The allocator skips every range in an active dynamic pool, and the dialog says so ("skips dynamic DHCP pools"): those addresses are the DHCP server's to lease. Typing one in as a Specific IP raises a warning you can override with Allocate anyway. If you do, also reserve the address for its device, because an IPAM row alone doesn't stop Kea leasing it to someone else. The same rule is why Ridgeline replaces the scope dialog's suggested pool (.10–.254) with .100–.199: kept, it would swallow the fixed addresses of modules 1.7 and 1.8.

5. You change the Staff VLAN 21 scope's options and click Save. How does Kea get the change?

You SSH to the Kea host and edit kea-dhcp4.conf to matchOnly after you click Sync → DHCP on the subnetAt the next scheduled full sync, which pushes every scope to every server nightlyThe Kea agent's long-poll picks up a new config bundle and applies it

The control plane assembles a config bundle from the database and hashes it into an ETag. The agent holds a long-poll open, and a changed ETag returns the new bundle, which the agent renders for Kea. For Kea you never push by hand: scopes, pools and reservations flow automatically, and leases stream back. Sync → DHCP only pulls leases from agentless servers such as Windows DHCP.

6. Which laptop holds 10.20.21.123 now, and which one had it last week? Where do you look?

The Kea server's Leases tab and its lease historyThe Audit Log, which records every leaseThe subnet's Trend tabThe DHCP group's Static Assignments tab

Leases are per server and read-only in SpatiumDDI, because each Kea keeps its own lease file. The server's Leases tab searches by IP, MAC or hostname. The lease history is the forensic trail of leases that expired, were released or moved to another MAC, kept for 90 days by default. The Academy lab has no DHCP clients, so both stay empty there.

Check answers

Go deeper

• DHCP features: server groups (§1), scopes and pools (§2), options (§11), Kea HA (§14) and the rules the API enforces (§16)
• DHCP drivers: how a scope is rendered into Kea’s configuration
• System architecture §4: configuration bundles, the long-poll and the Redis wake
• Getting Started, steps 5 and 9: the official DHCP setup order, and what New Scope pre-fills
• GitHub issues #1154 (the scope dialog’s router and pool pre-fill) and #1228 (option values checked on save)
• Tips and tricks: DHCP: HA pairs, client reachability, inactive scopes and more

Finished 1.6 DHCP scopes & pools?

Mark it complete to track your progress (stored only in this browser).

Mark complete