DHCP and address assignment: from empty interface to configured host

IPv4
|-- static address (configured by hand)
|-- DHCPv4 (lease from a server)
'-- IPv4 link-local 169.254.0.0/16 when normal configuration fails

IPv6
|-- link-local fe80::/10 (always present, never routed)
|-- SLAAC (address built from a Router-Advertised prefix)
|-- stateful DHCPv6 (IA_NA: server assigns the address)
|-- stateless DHCPv6 options (DNS, search lists via O flag)
|-- static/global address (infrastructure interfaces)
|-- temporary/privacy addresses (rotating outbound identity)
'-- DHCPv6 Prefix Delegation (IA_PD: prefix routed to another router)

Client                              Server
  |                                   |
  | DHCPDISCOVER  (broadcast)         |
  |---------------------------------->|
  |                                   |
  | DHCPOFFER     (proposed address)  |
  |<----------------------------------|
  |                                   |
  | DHCPREQUEST   (broadcast, names   |
  |  the offer it accepts)            |
  |---------------------------------->|
  |                                   |
  | DHCPACK       (lease granted,     |
  |  options attached)                |
  |<----------------------------------|

lease granted ------------------------- expiry
        |            |               |
      T1 renew    T2 rebind       hard stop
      (unicast    (broadcast,     (address
       to owner)   any server)     released)

# Watch the whole dance on the server-side interface.
tcpdump -eni servergw0 'port 67 or port 68'

# What you will see and what it means:
#  0.0.0.0.68 > 255.255.255.255.67:  DHCPDISCOVER  <- new client, no address
#  192.168.20.1.67 > 255.255.255.255.68: DHCPOFFER  <- server proposal
#  0.0.0.0.68 > 255.255.255.255.67:  DHCPREQUEST   <- client names its winner
#  192.168.20.1.67 > 255.255.255.255.68: DHCPACK    <- lease + options granted

// /etc/kea/kea-dhcp4.conf
{
  "Dhcp4": {

    // Listen ONLY on the intended gateway interface.
    "interfaces-config": {
      "interfaces": [ "servergw0" ]
    },

    // Memfile: leases survive restart, file cleaned hourly.
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "kea-leases4.csv",
      "lfc-interval": 3600
    },

    // Lease contract. Omitting renew/rebind lets clients pick
    // their own timers; set them to emit options 58/59.
    "valid-lifetime": 86400,
    "renew-timer": 43200,
    "rebind-timer": 75600,

    "subnet4": [
      {
        "id": 1,
        "subnet": "192.168.20.0/24",
        "interface": "servergw0",
        "pools": [ { "pool": "192.168.20.100 - 192.168.20.199" } ],
        "option-data": [
          { "name": "routers",              "data": "192.168.20.1" },
          { "name": "domain-name-servers",  "data": "192.168.20.53" },
          { "name": "domain-name",          "data": "example.test" }
        ]
      }
    ],

    "loggers": [ {
      "name": "kea-dhcp4",
      "output-options": [ { "output": "stdout" } ],
      "severity": "INFO"
    } ]
  }
}

// Inside "subnet4": [ { ... "reservations": [ ... ] } ]

// 1. By hardware (MAC) address - the everyday workhorse.
{
  "hw-address": "00:11:22:33:44:55",
  "ip-address": "192.168.20.20",
  "hostname": "printer01"
}

// 2. By client identifier - survives NIC replacement, common for VMs.
{
  "client-id": "01:11:22:33:44:55:66",
  "ip-address": "192.168.20.21",
  "hostname": "libvirt-lamp"
}

// 3. By DUID - the IPv6-native identity, with per-host options.
{
  "duid": "01:02:03:04:05",
  "ip-address": "192.168.20.22",
  "option-data": [ {
    "name": "domain-name-servers",
    "data": "192.168.20.53,192.168.20.54"
  } ]
}

Client                              Server
  |                                   |
  | SOLICIT   -> ff02::1:2            |
  |---------------------------------->|
  |                                   |
  | ADVERTISE                         |
  |<----------------------------------|
  |                                   |
  | REQUEST                           |
  |---------------------------------->|
  |                                   |
  | REPLY (addresses/options granted) |
  |<----------------------------------|

// /etc/kea/kea-dhcp6.conf - verified against the installed kea6 examples
{
  "Dhcp6": {

    "interfaces-config": {
      "interfaces": [ "servergw0" ]
    },

    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "kea-leases6.csv",
      "lfc-interval": 3600
    },

    // IPv6 leases carry TWO lifetimes. Preferred < valid:
    // addresses leave DNS/preference before they die.
    "preferred-lifetime": 3750,
    "valid-lifetime": 7200,
    "renew-timer": 1800,
    "rebind-timer": 3375,

    "subnet6": [
      {
        "id": 1,
        "subnet": "2a02:8012:bc57:fead::/64",
        "interface": "servergw0",
        // Pool may be a sub-range of the /64; a /80 pool is idiomatic.
        "pools": [ { "pool": "2a02:8012:bc57:fead::1000 - 2a02:8012:bc57:fead::1fff" } ],
        "option-data": [
          { "name": "dns-servers", "data": "2a02:8012:bc57:53a::53" }
        ]
      }
    ],

    "loggers": [ {
      "name": "kea-dhcp6",
      "output-options": [ { "output": "stdout" } ],
      "severity": "INFO"
    } ]
  }
}

                 IPv6 client
                     |
          +----------+----------+
          |                     |
         RA                  DHCPv6
          |                     |
   default router         address/options
   on-link prefix         DNS (option 23)
   SLAAC flags            search list (option 24)
   (M and O flags)        stateful IA_NA addresses

ip -6 addr          # which addresses exist, and which are 'mngtmpaddr'
ip -6 route         # SUCCESS looks like:
#   2a02:8012:bc57:fead::/64 dev eth0 proto kernel metric 256
#   default via fe80::XXXX dev eth0 proto ra metric 1024
#                                     ^^^ 'proto ra' means RA supplied it

# Model 1: SLAAC only (M=0, O=0) - addresses AND options from RA.
interface servergw0
{
  AdvSendAdvert on;
  prefix 2a02:8012:bc57:fead::/64
  {
    AdvOnLink on;
    AdvAutonomous on;
  };
  RDNSS 2a02:8012:bc57:53a::53 { };
};

# Model 2: SLAAC + DHCPv6 for options (M=0, O=1).
interface servergw0
{
  AdvSendAdvert on;
  AdvOtherConfigFlag on;     # options come from DHCPv6
  prefix 2a02:8012:bc57:fead::/64
  {
    AdvOnLink on;
    AdvAutonomous on;
  };
};

# Model 3: stateful DHCPv6 (M=1) - Kea assigns addresses.
interface servergw0
{
  AdvSendAdvert on;
  AdvManagedFlag on;
  AdvOtherConfigFlag on;
  # No AdvAutonomous prefix unless you ALSO want SLAAC addresses.
  prefix 2a02:8012:bc57:fead::/64
  {
    AdvOnLink on;
    AdvAutonomous off;
  };
};

ISP
 |
PPPoE
 |
ppp0
 |
dhcpcd , DHCPv6-PD (IA_PD) requests a /48
 |      , receives 2a02:8012:bc57::/48
 |
2a02:8012:bc57::/48
 |
+-- :fead::/64  servers   (static -> servergw0, radvd advertises)
+-- :db01::/64  data      (static -> datagw0)
+-- :53a::/64   nameservers (static -> ns1gw0)
'-- further /64s reserved for VPNs, guests, labs

# The WAN client on the reference router (production file, verbatim).
interface ppp0
        noipv4
        ipv6only
        ipv6rs

        # Request the delegated /48, however do not assign it to
        # LAN interfaces. LAN /64s are statically configured elsewhere.
        ia_pd 2/::48 -

VLAN 10 clients      192.168.10.0/24
      |
      | DHCP broadcast (stays local)
      v
Saphira router  <- relay agent listens here
      |
      | unicast, giaddr = 192.168.10.1
      v
Kea server       192.168.20.53
      |
      | selects 192.168.10.0/24 BECAUSE giaddr says so
      '-> reply unicast back through the relay

// subnet4 entries (excerpt) - one per VLAN
{ "id": 10, "subnet": "192.168.10.0/24", "interface": "usergw0",
  "pools": [ { "pool": "192.168.10.100 - 192.168.10.199" } ],
  "option-data": [
    { "name": "routers",             "data": "192.168.10.1" },
    { "name": "domain-name-servers", "data": "192.168.20.53" }
  ]
},
{ "id": 20, "subnet": "192.168.20.0/24", "interface": "servergw0",
  "pools": [ { "pool": "192.168.20.100 - 192.168.20.149" } ],
  "option-data": [
    { "name": "routers",             "data": "192.168.20.1" },
    { "name": "domain-name-servers", "data": "192.168.20.53" }
  ]
},
{ "id": 30, "subnet": "192.168.30.0/24", "interface": "mgmtgw0",
  "pools": [ { "pool": "192.168.30.50 - 192.168.30.99" } ],
  "option-data": [
    { "name": "routers",             "data": "192.168.30.1" },
    { "name": "domain-name-servers", "data": "192.168.30.53" }
  ]
},
{ "id": 40, "subnet": "192.168.40.0/24", "interface": "guestgw0",
  "pools": [ { "pool": "192.168.40.100 - 192.168.40.199" } ],
  "option-data": [
    { "name": "routers",             "data": "192.168.40.1" },
    // Guests get an external resolver pair: they are not our DNS clients.
    { "name": "domain-name-servers", "data": "9.9.9.9,149.112.112.112" }
  ]
}

# Single lease by address / all leases (control channel over REST)
kea-shell --host 127.0.0.1 --port 8000 lease4-get \
+  --parameters '{ "ip-address": "192.168.20.101" }'
kea-shell --port 8000 lease4-get-all

# Raw CSV - perfectly readable on a small LAN
columns: address, hwaddr, client_id, valid_lft, ... 
tail -5 /var/lib/kea/kea-leases4.csv

kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
kea-dhcp6 -t /etc/kea/kea-dhcp6.conf

# A syntax error announces itself, e.g.:
#   /etc/kea/kea-dhcp4.conf:12.3: syntax error, unexpected '\'",
#   expecting ...   <- JSON broke; fix the file, nothing else changed
#
# Success looks like:
#   DHCPv4 server has completed configuration review: 1 subnet(s),
#   0 host reservations found, ... (and exit status 0)

# OpenRC (Saphira's init)
rc-service kea-dhcp4 status
rc-service kea-dhcp4 start
rc-update add kea-dhcp4 default

rc-service kea-dhcp6 status
rc-service kea-dhcp6 start

# Or the bundled multi-daemon controller:
keactrl status
keactrl start
keactrl reload

# Which socket belongs to which protocol:
ss -lunp | grep -E ':(67|68|546|547)\b'
#  :67/udp  kea-dhcp4  <- DHCPv4 server
#  :547/udp kea-dhcp6  <- DHCPv6 server
#  (68 and 546 are CLIENT ports - seen on clients, not servers)

# And confirm it bound the interface you intended:
ss -lunp | grep kea

nft add rule inet filter input \
+  iifname "servergw0" udp dport 67 accept \
+  comment "DHCPv4: accept 0.0.0.0:68 -> 255.255.255.255:67 from clients"

# Relayed server side: relays send from their own address to :67
nft add rule inet filter input \
+  ip saddr 192.168.10.0/24 udp dport 67 accept

# DHCPv6: clients -> ff02::1:2 port 547
nft add rule inet filter input \
+  iifname "servergw0" ip6 daddr ff02::1:2 udp dport 547 accept

# RA and NDP stay reachable on LAN interfaces:
nft add rule inet filter input \
+  iifname "servergw0" icmpv6 type { router-advertisement, \
+    neighbour-solicit, neighbour-advert, packet-too-big } accept

Client receives:  gateway 192.168.1.254   (the dusty router)
Expected:         gateway 192.168.1.1     (your Kea server)

# Catch every offer on the wire; the server MAC of each OFFER
# is visible in the link header:
tcpdump -eni servergw0 'port 67 or port 68'

# Two different source MACs answering = two DHCP servers.
# The DHCP server-identifier option inside each offer names them,
# and ip -6 equivalent for rogue RAs:
tcpdump -eni servergw0 icmp6 and 'ip6[40] == 134'

# What does the machine ACTUALLY use?
resolvectl status            # per-link resolvers + their source
# or, minimal systems:
cat /etc/resolv.conf

# On the wire, who is advertising?
tcpdump -eni servergw0 'port 547 or (icmp6 and ip6[40] == 134)'

old delegated prefix 2a02:8012:bc57::/48
        |
   ISP renumber / provider change
        |
new delegated prefix 2a02:XXXX:YYYY::/48

server A thinks 192.168.20.150 is free
server B thinks 192.168.20.150 is free
      -> two clients, one address, intermittent doom

// Both servers, identical except this-server-name (verified
// against the shipped HA examples):
"hooks-libraries": [ {
  "library": "libdhcp_lease_cmds.so",
  "parameters": { }
},
{
  "library": "libdhcp_ha.so",
  "parameters": {
    "high-availability": [ {
      "this-server-name": "dhcp1",
      "mode": "hot-standby",        // or "load-balancing"
      "heartbeat-delay": 10000,
      "max-response-delay": 60000,
      "max-ack-delay": 5000,
      "max-unacked-clients": 5,
      "sync-timeout": 60000
    } ]
  }
} ]

// /etc/kea/kea-dhcp4.conf - home LAN
{
  "Dhcp4": {
    "interfaces-config": { "interfaces": [ "lan0" ] },
    "lease-database": { "type": "memfile", "persist": true, "lfc-interval": 3600 },
    "valid-lifetime": 86400,
    "subnet4": [ {
      "id": 1, "subnet": "192.168.1.0/24", "interface": "lan0",
      "pools": [ { "pool": "192.168.1.100 - 192.168.1.199" } ],
      "option-data": [
        { "name": "routers",             "data": "192.168.1.1" },
        { "name": "domain-name-servers", "data": "192.168.1.1" },
        { "name": "domain-name",         "data": "home.example.test" }
      ]
    } ]
  }
}

# Build, validate, start, prove
kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
rc-service kea-dhcp4 start
ss -lunp | grep ':67 '

# Client side: renew and watch the lease land
#   dhcpcd -k lan0 && dhcpcd lan0        (or your client's renew)
ip -4 addr show lan0; ip route

# Server side: watch DORA live
tcpdump -eni lan0 'port 67 or port 68'

# A client that renewed (RENEW unicast, not broadcast) proves T1 works:

// Kea DHCPv4 for the VLAN (inside subnet4)
{ "id": 20, "subnet": "192.168.20.0/24", "interface": "servergw0",
  "pools": [ { "pool": "192.168.20.100 - 192.168.20.149" } ],
  "option-data": [
    { "name": "routers",             "data": "192.168.20.1" },
    { "name": "domain-name-servers", "data": "192.168.20.53" }
  ]
}

// Kea DHCPv6: stateful model - RA (below) says M=1, O=1, so Kea
// supplies addresses AND options; no AdvAutonomous on the prefix.
// See the kea-dhcp6.conf in this chapter; subnet entry:
{ "id": 20, "subnet": "2a02:8012:bc57:fead::/64", "interface": "servergw0",
  "pools": [ { "pool": "2a02:8012:bc57:fead::1000 - 2a02:8012:bc57:fead::1fff" } ],
  "option-data": [
    { "name": "dns-servers", "data": "2a02:8012:bc57:53a::53" }
  ]
}

// radvd.conf - stateful model matching the Kea choices above
interface servergw0
{
  AdvSendAdvert on;
  AdvManagedFlag on;         # M=1: addresses via DHCPv6
  AdvOtherConfigFlag on;     # O=1: options via DHCPv6
  prefix 2a02:8012:bc57:fead::/64
  {
    AdvOnLink on;
    AdvAutonomous off;       # no SLAAC: Kea owns addresses
  };
};

            Kea 192.168.20.53
             |
          server VLAN 192.168.20.0/24
             |
       Saphira router
      /      |        \
  usergw0  servergw0  guestgw0
  192.168.10.1          192.168.40.1
      |                   |
  relay here          relay here
  (giaddr 192.168.10.1) (giaddr 192.168.40.1)
      |                   |
  users VLAN         guest VLAN

1.  Does the interface exist?          ip link
2.  Is it up?                           ip addr / carrier
3.  Is the service listening there?     ss -lunp + interfaces-config
4.  Does the client request leave?      capture on client side
5.  Does the server receive it?         capture on server side
6.  Does the server answer?             capture OFFER/ADVERTISE
7.  Does the answer return?             capture on client again
8.  What address did the client install?   ip addr
9.  What route did it install?          ip route / ip -6 route
10. What resolver did it install?       resolvectl status
11. Can it reach the gateway?           ping the gateway
12. Can it reach an external IP?        ping 1.1.1.1 / 2606:4700::1111
13. Can it resolve a name?              dig A + AAAA a public name