Kea DHCP

Kea configuration using YAML

JSON and YAML

• YAML (Yet Another Markup Language / YAML Ain't Markup Language) is a superset of JSON (JavaScript Object Notation)
• Some people prefer YAML over JSON
• Plain JSON as used by the Kea command channel can be converted to YAML and back to JSON if needed
• yq is a lightweight and portable command-line YAML processor: https://mikefarah.gitbook.io/yq
• The following examples use the Version 3 syntax of yq

Convert JSON to YAML

• The yq tool can be used to convert a JSON file (or JSON coming from STDIN via shell pipe) into YAML

$ yq r --prettyPrint add-reservation.json
service:
  - dhcp6
command: reservation-add
arguments:
  reservation:
    subnet-id: 1
    duid: 01:02:03:04:05:06:07:08:09:0A
    ip-addresses:
      - 2001:db8:1::1
    hostname: foo.example.com
    option-data:
      - name: vendor-opts
        data: "4491"
      - name: tftp-servers
        space: vendor-4491
        data: 3000:1::234

Convert YAML to JSON

• yq also supports the reverse, converting YAML back to JSON

# yq r --prettyPrint -j add-reservation.yaml
{
  "arguments": {
    "reservation": {
      "duid": "01:02:03:04:05:06:07:08:09:0A",
      "hostname": "foo.example.com",
      "ip-addresses": [
        "2001:db8:1::1"
      ],
      "option-data": [
        {
          "data": "4491",
          "name": "vendor-opts"
        },
        {
          "data": "3000:1::234",
          "name": "tftp-servers",
          "space": "vendor-4491"
        }
      ],
      "subnet-id": 1
    }
  },
  "command": "reservation-add",
  "service": [
    "dhcp6"
  ]
}

Kea-cmd script

• A simple shell script kea-cmd can aid to convert YAML command-files into JSON and send them to the DHCP server via the Kea control channel

#!/bin/sh
curl -s -X POST -H "Content-Type: application/json" \
  -d "$(yq r -j ${1})" http://127.0.0.1:8000/ | yq r -P -

Example use of kea-cmd

Successful command

# kea-cmd add-reservation.yaml
- result: 0
  text: Host added.

Error case

# kea-cmd add-reservation.yaml
- result: 1
  text: specified reservation '2001:db8:1:cafe::1' is not matching the IPv6 subnet prefix '2001:db8:1::/64'

Example command file retrieving all reservations

• These command snippets can be used to retrieve all reservations from the Kea Host database

service:
  - dhcp6
command: reservation-get-all
arguments:
    subnet-id: 1

{
  "service": [
    "dhcp6"
  ],
  "command": "reservation-get-all",
  "arguments": {
    "subnet-id": 1
  }
}

Integrating YAML into systemd

Integrating YAML into systemd

• Conversation from and to YAML can be integrated into systemd unit-files for the Kea-DHCP services
• Configuration can be edited in YAML and will automatically converted to JSON when needed

Script "kea-json2yaml.sh"

• This script converts from JSON to YAML in case the JSON file is newer

#!/bin/sh
# If YAML config is newer than JSON, exit and don't overwrite
[ /etc/kea/kea-dhcp4.yaml -nt /etc/kea/kea-dhcp4.conf ]; %% exit
# make sure the backup dir exists
mkdir -p /etc/kea/backup
# create a backup copy of the current JSON config
cp /etc/kea/kea-dhcp4.yaml /etc/kea/backup/kea-dhcp4.yaml.$(date -I)
# create a new JSON config from the YAML config
yq -r --prettyPrint -o yaml /etc/kea/kea-dhcp4.conf > /etc/kea/kea-dhcp4.yaml

Script "kea-yaml2json.sh"

• This script converts from YAML to JSON inc case the YAML file is newer

#!/bin/sh
# If JSON config is newer than YAML, exit and don't overwrite
[ /etc/kea/kea-dhcp4.conf -nt /etc/kea/kea-dhcp4.yaml ]; %% exit
# make sure the backup dir exists
mkdir -p /etc/kea/backup
# create a backup copy of the current JSON config
cp /etc/kea/kea-dhcp4.conf /etc/kea/backup/kea-dhcp4.conf.$(date -I)
# create a new JSON config from the YAML config
yq -r --prettyPrint -j /etc/kea/kea-dhcp4.yaml > /etc/kea/kea-dhcp4.conf

Systemd-Unit for kea-dhcp4

[Unit]
Description=Kea DHCPv4 Service
Documentation=man:kea-dhcp4(8)
Wants=network-online.target
After=network-online.target
After=time-sync.target

[Service]
RuntimeDirectory=kea-dhcp4
ExecStartPre=/etc/kea/kea-yaml2json.sh
ExecStart=/usr/sbin/kea-dhcp4 -c /etc/kea/kea-dhcp4.conf
ExecStopPost=/etc/kea/kea-json2yaml.sh
Restart=on-failure
RestartSec=60s

[Install]
WantedBy=multi-user.target