Changes between Version 82 and Version 83 of HostReservationDesign


Ignore:
Timestamp:
Sep 30, 2016, 7:48:58 AM (14 months ago)
Author:
marcin
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HostReservationDesign

    v82 v83  
    325325Kea should support any custom storage for host reservations, but typically host reservations will be stored in an SQL database. The first implemented lease database backend used MySQL to store leases, so it seems natural that the first backend for storing host reservations should also use MySQL. This way we create no new dependencies for users already using MySQL for leases. Although, the schema presented here is created specifically for implementation of the MySQL backend, the schemas for other types of SQL databases will be very similar or the same.
    326326
    327 The proposed schema is depicted on the picture below.
     327The Kea 1.1.0 MySQL schema is depicted on the picture below.
    328328
    329329[[Image(kea-host-reservation-schema.svg)]]
     
    336336- A name which has a postfix ''_id'' holds an identifier of row in the database which is used to create relations between tables.
    337337
    338 DHCPv6 protocol allows for allocating multiple IPv6 addresses or/and prefixes in a single session. Moreover, these resources may be sent in the same or distinct IA options. Although, in most common scenario a client would only get one IPv6 address at the time, it is very common that the client gets an address and prefix in a single Reply message from a server. This is reflected in the database schema as a 1:n relation between the ''hosts'' and ''ipv6_reservations'' tables and the ''host_id'' is a primary and foreign key for this relation. Note, that this is an ''Indentifying Relation'' which means that the entry in the ''ipv6_reservations'' doesn't make sense without a corresponding entry in the ''hosts'' table because this table contains a unique identifier of the client (MAC address or DUID). This in turn implies that removal of the host from the ''hosts'' table should trigger a removal of all corresponding entries in the ''ipv6_reservations'' table. This can be achieved by the following trigger executed before deletion of an entry in the ''hosts'' table:
     338DHCPv6 protocol allows for allocating multiple IPv6 addresses or/and prefixes in a single session. Moreover, these resources may be sent in the same or distinct IA options. Although, in most common scenario a client would only get one IPv6 address at the time, it is very common that the client gets an address and prefix in a single Reply message from a server. This is reflected in the database schema as a 1:n relation between the ''hosts'' and ''ipv6_reservations'' tables and the ''host_id'' is a primary and foreign key for this relation. Note, that this is an ''Indentifying Relation'' which means that the entry in the ''ipv6_reservations'' doesn't make sense without a corresponding entry in the ''hosts'' table because this table contains a unique identifier of the client (MAC address or DUID). This in turn implies that removal of the host from the ''hosts'' table should trigger a removal of all corresponding entries in the ''ipv6_reservations'' table. Kea 1.1.0 uses the following trigger to remove IPv6 reservations belonging to a removed host.
    339339
    340340{{{
     
    345345}}}
    346346
     347However, the ticket #4521 proposes a more generic approach using CASCADE DELETE, which will replace this trigger.
    347348
    348349The detailed description of each column of the ''hosts'' and ''ipv6_reservations'' tables is presented below.
     
    359360|| dhcp4_client_classes || A comma separated list of classes to which the DHCPv4 client is assigned. In the future, it will be possible to specify a collection of options that the group of clients of a particular class will be given. A NULL or empty value indicates that the client doesn't belong to any class. ||
    360361|| dhcp6_client_classes || See above for ''dhcp4_client_classes''. ||
     362|| dhcp4_next_server || An IPv4 address to be included in the siaddr field of the DHCPv4 message sent to a client. ||
     363|| dhcp4_server_hostname || Server hostname to be included in the sname field of the DHCPv4 message sent to a client. ||
     364|| dhcp4_boot_file || Boot file name to be included in the file field of the DHCPv4 message sent to a client. ||
    361365||||= ipv6_reservations =||
    362366|| reservation_id || Unique identifier of the reservation in the database; an auto-incremented primary key for this table. The values stored in this column are not used by the DHCP server but may be used by the third party updating the reservations for a host to refer to a specific reservation. ||
    363367|| address || Address or prefix being reserved. This is represented as a string value in the canonical address format. ||
    364368|| prefix_len || Length of the prefix. The default value is 128 which is used for addresses. The allowed range for this value is 0..128. ||
    365 || type || Type of the reservation. A value of 0 is IPv6 address reservation, a value of 1 is IPv6 prefix reservation. ||
     369|| type || Type of the reservation. A value of 0 is IPv6 address reservation, a value of 2 is IPv6 prefix reservation. ||
    366370|| dhcp6_iaid || This value is only used for reservations for the addresses or prefixes to be handed out to the client in the IA options with specific IAIDs. The IAID field in the IA_NA or IA_PD option is generated by the client. If known in advance, it is possible to specify that the particular address or prefix is only assigned if the client sends the IA option with this IAID. Otherwise, the reserved address or prefix is not sent to a client and client may obtain a dynamically allocated address or prefix. The NULL value of this field indicates that the reservation is not bound to any IAID and will be handed out to the client regardless of the value of the IAID sent in IA option. ||
    367371|| host_id || Foreign key which links the reservation with the particular host in the database. It is also used by the trigger which deletes reservations for the hosts being deleted from the ''hosts'' table. ||
     
    380384|| persistent || A boolean value which indicates if the particular option should always be returned to the client or only if the client requested the option using ORO or PRL option. ||
    381385|| host_id || A host identifier referring to the ''host_id'' field of the ''hosts'' table. This field matches the option instance with a host reservation. ||
    382 
    383 [[span(style=color: #FF0000, Implementation Note (March 9th, 2016): In Kea 1.0.0 release the dhcp4_options and dhcp6_options tables contain extraneous columns: dhcp_client_class, dhcp4_subnet_id and dhcp6_subnet_id. These columns should be removed from the schema in the Kea 1.1.0 release because they are unused in host reservations. )]].
    384 
    385 The MySQL script for creating a database schema proposed above is given below.
    386 {{{
    387 
    388 -- -----------------------------------------------------
    389 -- Table `hosts`
    390 -- -----------------------------------------------------
    391 CREATE  TABLE IF NOT EXISTS `hosts` (
    392   `host_id` INT UNSIGNED NOT NULL AUTO_INCREMENT ,
    393   `dhcp_identifier` VARBINARY(128) NOT NULL ,
    394   `dhcp_identifier_type` TINYINT NOT NULL ,
    395   `dhcp4_subnet_id` INT UNSIGNED NULL ,
    396   `dhcp6_subnet_id` INT UNSIGNED NULL ,
    397   `ipv4_address` INT UNSIGNED NULL ,
    398   `hostname` VARCHAR(255) NULL ,
    399   `dhcp4_client_classes` VARCHAR(255) NULL ,
    400   `dhcp6_client_classes` VARCHAR(255) NULL ,
    401   PRIMARY KEY (`host_id`) ,
    402   INDEX `key_dhcp4_identifier_subnet_id` (`dhcp_identifier` ASC, `dhcp_identifier_type` ASC) ,
    403   INDEX `key_dhcp6_identifier_subnet_id` (`dhcp_identifier` ASC, `dhcp_identifier_type` ASC, `dhcp6_subnet_id` ASC) )
    404 ENGINE = InnoDB;
    405 
    406 -- -----------------------------------------------------
    407 -- Table `ipv6_reservations`
    408 -- -----------------------------------------------------
    409 CREATE  TABLE IF NOT EXISTS `ipv6_reservations` (
    410   `reservation_id` INT NOT NULL AUTO_INCREMENT ,
    411   `address` VARCHAR(39) NOT NULL ,
    412   `prefix_len` TINYINT(3) UNSIGNED NOT NULL DEFAULT 128 ,
    413   `type` TINYINT(4) UNSIGNED NOT NULL DEFAULT 0 ,
    414   `dhcp6_iaid` INT UNSIGNED NULL ,
    415   `host_id` INT UNSIGNED NOT NULL ,
    416   PRIMARY KEY (`reservation_id`) ,
    417   INDEX `fk_ipv6_reservations_host_idx` (`host_id` ASC) ,
    418   CONSTRAINT `fk_ipv6_reservations_Host`
    419     FOREIGN KEY (`host_id` )
    420     REFERENCES `hosts` (`host_id` )
    421     ON DELETE NO ACTION
    422     ON UPDATE NO ACTION)
    423 ENGINE = InnoDB;
    424 
    425 
    426 -- -----------------------------------------------------
    427 -- Table `dhcp4_options`
    428 -- -----------------------------------------------------
    429 CREATE  TABLE IF NOT EXISTS `dhcp4_options` (
    430   `option_id` INT UNSIGNED NOT NULL AUTO_INCREMENT ,
    431   `code` TINYINT UNSIGNED NOT NULL ,
    432   `value` BLOB NULL ,
    433   `formatted_value` TEXT NULL ,
    434   `space` VARCHAR(128) NULL ,
    435   `persistent` TINYINT(1) NOT NULL DEFAULT 0 ,
    436   `host_id` INT UNSIGNED NULL ,
    437   PRIMARY KEY (`option_id`) ,
    438   UNIQUE INDEX `option_id_UNIQUE` (`option_id` ASC) ,
    439   INDEX `fk_options_host1_idx` (`host_id` ASC) ,
    440   CONSTRAINT `fk_options_host1`
    441     FOREIGN KEY (`host_id` )
    442     REFERENCES `hosts` (`host_id` )
    443     ON DELETE NO ACTION
    444     ON UPDATE NO ACTION)
    445 ENGINE = InnoDB;
    446 
    447 
    448 -- -----------------------------------------------------
    449 -- Table `dhcp6_options`
    450 -- -----------------------------------------------------
    451 CREATE  TABLE IF NOT EXISTS `dhcp6_options` (
    452   `option_id` INT UNSIGNED NOT NULL AUTO_INCREMENT ,
    453   `code` INT UNSIGNED NOT NULL ,
    454   `value` BLOB NULL ,
    455   `formatted_value` TEXT NULL ,
    456   `space` VARCHAR(128) NULL ,
    457   `persistent` TINYINT(1) NOT NULL DEFAULT 0 ,
    458   `host_id` INT UNSIGNED NULL ,
    459   PRIMARY KEY (`option_id`) ,
    460   UNIQUE INDEX `option_id_UNIQUE` (`option_id` ASC) ,
    461   INDEX `fk_options_host1_idx` (`host_id` ASC) ,
    462   CONSTRAINT `fk_options_host10`
    463     FOREIGN KEY (`host_id` )
    464     REFERENCES `hosts` (`host_id` )
    465     ON DELETE NO ACTION
    466     ON UPDATE NO ACTION)
    467 ENGINE = InnoDB;
    468 
    469 DELIMITER $$
    470 
    471 CREATE TRIGGER `host_BDEL` BEFORE DELETE ON hosts FOR EACH ROW
    472 -- Edit trigger body code below this line. Do not edit lines above this one
    473 BEGIN
    474 DELETE FROM `ipv6_reservations` WHERE `ipv6_reservations`.host_id = OLD.host_id;
    475 END
    476 $$
    477 
    478 
    479 DELIMITER ;
    480 
    481 }}}
     386|| scope_id || An identifier of the scope for the given option: global, subnet specific, class specific or host specific option. The value of '3' is used for host reservations. ||
     387
     388The ''dhcp_option_scope'' table associate option scope identifiers with their names. This table is not used in queries issued by the host data source. It is meant to be used in queries issued by management tools when displaying associations of options with scopes.
     389
     390The MySQL script for creating a database schema proposed above can be found in Kea sources, under src/share/databases/scripts/mysql/dhcpdb_create.mysql.
    482391
    483392=== Queries to MySQL hosts database ===
    484393Performance measurements of Kea DHCP server using MySQL lease database indicate that the number of queries sent to the database for a processed message is one of the most important factors impacting server's performance. To minimize the impact of host reservation mechanism on the servers' performance, the implementation must gather all required data for a processed packet in a single query (rather than multiple queries). Experiments conducted as part of this design show that even a complex query would typically be more efficient than multiple simple queries gathering the same data. In this section we present examples how to retrieve full information about host, reserved options and IPv6 reservations for using a single query to the MySQL database.
    485394
    486 The following query retrieves information about multiple hosts, their IPv6 address/prefix reservations and assigned options from three tables using "LEFT JOIN" condition:
     395The following is the simplified query which retrieves information about multiple hosts, their IPv6 address/prefix reservations and assigned options from three tables using "LEFT JOIN" condition:
    487396
    488397{{{
     
    589498The PostgreSQL database will use the same schema and queries to manage the host reservation information.
    590499
     500
     501== More comprehensive list of queries ==
     502To ease working with Kea MySQL and PostgreSQL databases we have created a wiki page [[HostReservationsHowTo]] which explains how to insert host reservations into the database with external tools, as well what queries the server is using to retrieve these reservations during its operation.
     503
    591504== Class diagram ==
    592505