Kea DHCP custom options workshop

1 Kea DHCP Options Workshop

The virtual machines have a domain name in the form keaNNN.dane.onl.

Please login to the machines with a modern web browser under the URL https://keaNNN.dane.onl with the username user and the password kea-dhcp. You can also login with SSH and the same username and password.

The virtual machines run the cockpit tool (https://cockpit-project.org) to provide a terminal in the web browser.

Then select the terminal (last menu option on the left) and start the tutorial.

1.1 Virtual machines

Every participant has a VM number. Please replace the NNN in the instructions with your participant number from the table below:

Name Participant #
001 Aaron J
002 Benito M
003 Christopher D
004 Daniel I
005 Gabriel L
006 Jan B
007 Jeff A
008 John B
009 Maria Z
010 Michael D
011 Palash G
012 Renyk dV
013 Richard L
014 Robert M
015 Ronald R
016 Ross O
017 Tobias H
018 Stephan S
019 Torbjörn E
020 Wulf-Burkhard G
021 Chris D
022 Dan A
023 Joost K

2 Preparing the Workshop Lab Environment

2.1 The Kea DHCPv4 Server

  • Go to https://keaNNN.dane.onl (replace NNN with your participant number)
  • Login with username user and password kea-dhcp
  • Select Terminal in the menu on the left
  • Get a root-shell with sudo -i and the password kea-dhcp
  • Change directory with cd /root/lab/lab01
  • Execute the run script with ./run (ignore the error messages)
  • Execute the command running. It should report the kea-server and the client running
  • Enter into the Kea-Server Container with enter kea-server
  • Use an console text editor (emacs, vim, nano) to create a Kea DHCPv4 configuration file in /etc/kea/kea-dhcp4.conf 
    {
  "Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "server-eth0" ],
        "dhcp-socket-type": "raw"
    },
    "control-socket": {
        "socket-type": "unix",
        "socket-name": "/tmp/kea-dhcp4.socket"
    },
    "lease-database": {
        "type": "memfile",
        "lfc-interval": 3600
    },
    "renew-timer": 900,
    "rebind-timer": 1800,
    "valid-lifetime": 3600,
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.100 - 192.0.2.200" } ],
            "option-data": [
                {
                    "name": "routers",
                    "data": "192.0.2.1"
                }
            ]
        }
    ],
    "loggers": [
    {
        "name": "kea-dhcp4",
        "output_options": [
            {
                "output": "/var/log/kea-dhcp4.log"
            }
        ],
        "severity": "INFO",
        "debuglevel": 0
    }
  ]
 }
}
    • Save the file and test the configuration 
    % kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
    • If no errors are reported, start the Kea DHCPv4 Server 
    % systemctl start kea-dhcp4
% systemctl status kea-dhcp4

2.2 DHCP Client

  • Login to the lab server again on a new browser tab
  • Enter the Client Container with enter client
  • Request a lease 
    % dhclient -v

3 Session 1 - RFC 3442 Classless static routes

  • The DHCP option for classless static routes are not pre-defined in Kea DHCP (nor in ISC-DHCP, see https://kb.isc.org/docs/aa-01323)
  • Review the requierd option format in RFC 3442 (https://www.rfc-editor.org/rfc/rfc3442)
  • Create a option definition for DHCP option 121 in Kea DHCPv4 Server configuration 
    "Dhcp4": {
"option-def": [{
        "name": "classless-static-routes",
        "code": 121,
        "space": "dhcp4",
        "type": "record",
        "record-types": "uint8,uint8,uint8,ipv4-address"
}],
[...]
  • Add the option 121 with the values 9, 10, 0, 192.0.2.10 to the existing subnet inside the Kea DHCPv4 configuration (solution will be published here approx 15 minutes into the workshop)
  • On the DHCP client, create the file /etc/dhclient.conf with the following line to request option 121 from the client: 
    also request classless-static-routes;
  • Create a shell script on the client with the filename dhclient-debug.sh and the following lines 
    #!/bin/sh
env
  • Mark the script as executable 
    % chmod +x dhclient-debug.sh
  • Release the previous lease and request a new lease using the debug script 
    % dhclient -v -sf dhcpclient-debug.sh -i client-eth0
  • Result: 
    [...]
old_dhcp_renewal_time=20000
new_subnet_mask=255.255.255.0
requested_host_name=1
new_classless_static_routes=9.10.0 192.0.2.10
old_dhcp_rebinding_time=80000
_=/bin/env
bound to 192.0.2.100 -- renewal in 16011 seconds.
  • Do you see the line new_classless_static_routes=9.10.0 192.0.2.10?

3.1 Solution for Session 1:

  • This is the subnet definition including the classless static routes option: 
[...]
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.100 - 192.0.2.200" } ],
            "option-data": [
                { "name": "routers", "data": "192.0.2.1" },
                { "name": "classless-static-routes", "data": "9,10,0,192.0.2.10" }
            ]
        }
    ],
    [...]

4 Session 2 - Translating ISC-DHCP vendor options

This is a configuration example to provide MSM APs with the IP address of the MSM controller 
via DHCP (option 43) on ISC DHCP server for GNU/Linux.

#Configure an Option Space

option space MSM_Controller;


#Configure the "server-address" parameter for the Option Space. Use code 1 

option MSM_Controller.server-address code 1 = array of ip-address;  


subnet 10.1.30.0 netmask 255.255.255.0  

{   

#This is the normal pool configuration

range 10.1.30.150 10.1.30.175; 
option subnet-mask 255.255.255.0;   
option broadcast-address 10.1.30.255;   
option routers 10.1.30.1;  # Default Gateway


# Here we include the vendor identifier

class "Colubris-AP"   

{    
match if option vendor-class-identifier = "Colubris-AP";    
option vendor-class-identifier "Colubris-AP";        
vendor-option-space MSM_Controller;     
option MSM_Controller.server-address 10.1.1.2;  #This is the controller's IP 
}
  • Translate this ISC-DHCP configuration into an Kea DHCPv4 configuration and test the configuration in the lab environment. The Solution will be published approx. 20 minutes into the workshop time. Use the slides at https://webinar.defaultroutes.de/webinar/15-Kea-DHCP-Options.html as a guide
  • On the client, configure dhclient to also request the vendor-encapsulated-options
  • Test from the client container, verify that you see the MSM-Controller Server-Address option (the IP-Address 10.1.1.2) in the DHCP response to the client.

4.1 Solution - Session 2:

  • Kea DHCP4 configuration matching the ISC-DHCP configuration for "Colubris-AP": 
{
  "Dhcp4": {
  "option-def": [{
            "name": "server-address",
            "code": 1,  # Option code /inside/ option 43                                                                                        
            "space": "vendor-encapsulated-options-space",
            "type": "ipv4-address",
            "array": true
    }],
    "client-classes": [{
       "name": "Colubris-AP",
       "test": "option[vendor-class-identifier].text == 'Colubris-AP'",
       "option-data": [{
          "name": "vendor-encapsulated-options",  "always-send": true },{
          "name": "server-address",
          "space": "vendor-encapsulated-options-space",
          "code": 1, # Option code /inside/ option 43                                                                                           
          "data": "10.1.1.2"
    }]}],
    [...]