wiki:HostReservationsHowTo

Version 2 (modified by marcin, 3 years ago) (diff)

--

Tips about Host Reservations in Kea 1.1

Introduction

This document has been created while the Kea 1.1.0 was still under development. The Host Reservations appears to be one of the most desired features in Kea 1.1.0 and we continuously receive many questions pertaining to Host Reservations over mailing lists. This document is intended to address some of the most common questions, i.e. how to manage reservations in the SQL database and what SQL queries the server is using to retrieve reservations.

Host Reservations in MySQL Database

Host Reservations Data Structure in MySQL Database

The host reservation information is held in multiple tables within a database:

  • hosts - includes client identification information, subnet identifiers for both DHCPv4 and DHCPv6 client, hostname reserved for a client, IPv4 address reservation and client class names
  • ipv6_reservations - holds IPv6 address and prefix reservations for a client. It provides one-to-many relation with hosts table
  • dhcp4_options - holds DHCPv4 options reserved for a client (one-to-many with hosts table)
  • dhcp6_options - holds DHCPv6 options reserved for a client (one-to-many with hosts table)

In addition, the MySQL schema contains two tables mapping the numeric identifiers to the user friendly text representations:

  • host_identifier_type - contains the mapping of host identifiers to the host identifiers names,
  • dhcp_option_scope - contains the mapping of DHCP option scopes (e.g. global, subnet etc), used in dhcp4_options and dhcp6_options tables, into the scope names.

For any host reservation there must be an entry added into the hosts table. Adding entries into other tables is optional, e.g. if only IPv4 reservation is required for a client there is no entry added into the ipv6_reservations table. Similarly, if there are no client specific options assigned, there are no entries added into the dhcp4_options or dhcp6_options tables.

IPv4 only Reservation

In order to add an IPv4 address and hostname reservation for a client, identified by its MAC address the following MySQL INSERT statement can be used:

START TRANSACTION;
SET @ipv4_reservation='192.0.2.4';
SET @hostname = 'myhost.example.org';
SET @identifier_type='hw-address';
SET @identifier_value='10:20:30:40:50:60';
SET @dhcp4_subnet_id=1;

INSERT INTO hosts (dhcp_identifier,
                   dhcp_identifier_type,
		   dhcp4_subnet_id,
                   ipv4_address,
                   hostname)
VALUES (UNHEX(REPLACE(@identifier_value, ':', '')),
	(SELECT type FROM host_identifier_type WHERE name=@identifier_type),
        @dhcp4_subnet_id,
        INET_ATON(@ipv4_reservation),
        @hostname);

COMMIT;

The reservation will be made for an address of 192.0.2.4 and hostname of myhost.example.org. The identifier type hw-address indicates that the client is identified by its MAC address. The identifier_value specifies the MAC address of the client. The dhcp4_subnet_id must match the identifier of the subnet to which the client is connected. The subnet identifier can be explicitly specified as a parameter of a subnet declaration within the Kea configuration file. This identifier should be used here.

In order to test that the reservation has been successfully added the following SELECT query can be used:

SELECT 
    HEX(h.dhcp_identifier) AS dhcp_identifier,
    i.name AS dhcp_identifier_name,
    h.dhcp4_subnet_id AS dhcp4_subnet_id,
    INET_NTOA(h.ipv4_address) AS ipv4_address,
    h.hostname AS hostname
FROM
    hosts AS h
        INNER JOIN
    host_identifier_type AS i ON h.dhcp_identifier_type = i.type;