wiki:ConfigurationMigration

Configuration Migration

IN PREPARATION

Introduction

On the list of things we want to do, but with no firm date in the roadmap yet, is some way of converting an ISC DHCP configuration file to a Kea one. Although the packaging has not yet been finalised (e.g. module within Kea or a standalone tool), the broad requirements are reasonably clear. All that remains is a determination of how complete the tool will be. Owing to the complexity of the ISC DHCP configuration, a 100% conversion is probably not possible. Much more likely is a utility that will convert the common configuration elements, the more obscure ones requiring some manual intervention.

This page represents work in progress and maps each DHCP configuration element to the Kea equivalent. As new features are added to Kea, so this page will be updated. At the time that the migration utility comes to be written, this page will form the requirements document.

ISC DHCP/Kea Correspondences

The following is a set of tables identifying the mapping between ISC DHCP configuration statements and the Kea equivalents. The following conventions are used/points should be noted:

  • Many Kea parameters are similar for both DHCPv4 and DHCPv6. This is indicated by using notation Dhcp(4|6); this should be understood to mean using Dhcp4 or Dhcp6 depending on what protocol the parameter is being set for. (Similarly Dhcp(4|6)/subnet(4|6) should be taken to mean either Dhcp4/subnet4 or Dhcp6/subnet6. It is not meaningful to use Dhcp4 with subnet6 or to use Dhcp6 with subnet4.)
  • As square brackets are used in Kea syntax, optional values in the table below are enclosed in braces: "{" and "}".
  • If a keyword is one that starts a clause in ISC DHCP (e.g. the class keyword opens a clause in which the criteria for membership of the class is defined) and is not implemented in Kea, then none of the keywords specific to that clause are implemented either.

Command-Line Switches

A number of options specified on the dhcpd command line are handled in Kea by configuration options.

Switch Meaning Kea Equivalent Notes
-p port Selects port on which the server listens. -p Works exactly the same.
-f Run as a foreground process.
-d Send error messages to standard error. Logging/loggers[n] Kea logging is more flexible than that of ISC DHCP and has more options (including sending error messages to the console).
-q Be quiet at startup. N/A Not implemented in Kea.
-t Test the configuration file.
-T Test the lease file.
-4 Selects DHCPv4 functionality. N/A Explicitly run the Kea DHCPv4 server.
-6 Selects DHCPv6 functionality. N/A Explicitly run the Kea DHCPv6 server.
-s server (DHCPv4 only) Address of host name to which the server should send replies rather than the broadcast address.
-cf config-file Path to the configuration file. N/A Configuration backend is a compile-time option.
-lf lease-file Path to the lease file. Dhcp(4|6)/lease-database/name Other Dhcp(4|6)/lease-database options supply information such as access string.
-pf pid-file Path to the PID file.
--no-pid Disable the creation of the PID file.
-tf trace-output-file File into which the entire startup state of the server and all the transactions it processes are logged.
-play trace-playback-file File from which the entire startup state of the server and all the transactions it processed are read.
if0 {... ifN} Interfaces on which the server listens. Dhcp(4|6)/interfaces These are command arguments in ISC DHCP.

Server Parameters

The following are parameters related to the server. Depending on the parameter, some have global scope whiles others may be restricted (e.g. to a host, subnet, pool etc.):

ISC DHCP Element Kea Equivalent Notes
adaptive-lease-time-threshold
allow-booting
allow-bootp N/A Kea does not implement BOOTP.
always-broadcast
always-reply-rfc1408 N/A Kea does not implement BOOTP.
{not} authoritative
boot-unknown-clients
db-time-format N/A The format of times output by Kea (always UTC) is fixed and cannot be changed.
ddns-domainname Dhcp(4|6)/dhcp-ddns/qualifying-suffix DHCP servers use the qualifying-suffix when generating FQDNs, or when the given FQDN consists only of only hostname. Kea uses FQDNs to select the appropriate DNS server(s).
ddns-hostname Dhcp(4|6)/dhcp-ddns/generated-prefix
ddns-local-address(4|6)
ddns-rev-domainname N/A Kea forms the reverse name based on the lease address and a hard-coded suffix. For IPv4 addresses the suffix is "in-addr.arpa." and for IPv6 addresses, it is "ip6.arpa."
ddns-ttl
ddns-update-style N/A Kea supports only one mode: DDNS with Conflict Resolution as per RFC 4703.
ddns-updates Dhcp(4|6)/dhcp-ddns/enable-updates When true it causes the Kea DHCP servers to send requests to Kea DHCP-DDNS component. For these to succeed, that component must be running, and must be configured with have matching forward and/or reverse domains.
declines
default-lease-time
delayed-ack N/A Kea does not have the concept of "delayed ack".
dhcp-cache-threshold
dhcpv6-lease-file-name Dhcp6/lease-database/name Other Dhcp6/lease-database options supply information such as access string.
dhcpv6-pid-file-name
do-forward-updates Dhcp(4|6)/dhcp-ddns/override-client-updates; Dhcp(4|6)/dhcp-ddns/override-no-updates If updates are enabled, then DHCP servers will generate requests based on the Client's FQDN flags and these two flags.
do-reverse-updates
dont-use-fsync
duplicates
dynamic-bootp N/A Kea does not implement BOOTP.
dynamic-bootp-lease-cutoff N/A Kea does not implement BOOTP.
dynamic-bootp-lease-length N/A Kea does not implement BOOTP.
filename N/A Kea does not implement BOOTP.
fixed address
fixed address6
fqdn-reply
get-lease-hostnames
hardware
host-identifier option
ignore-client-uids
infinite-is-reserved
lease-file-name Dhcp4/lease-database/name Other Dhcp4/lease-database options supply information such as access string.
leasequery
limit-addrs-per-ia
limit-prefs-per-ia
limited-broadcast-address
local-address
local-port
log-facility Logging/loggers[n] Kea logging is more flexible than that of ISC DHCP and has more options.
log-threshold-high Logging/loggers[n] Kea logging is more flexible than that of ISC DHCP and has more options.
log-threshold-low Logging/loggers[n] Kea logging is more flexible than that of ISC DHCP and has more options.
max-ack-delay N/A Kea does not have the concept of "delayed ack".
max-lease-time
min-lease-time
min-secs
next-server Dhcp4/next-server
Dhcp4/subnet4[n]/next-server
This can be defined in both global and subnet scope.
omapi-key N/A Kea does not support OMAPI.
omapi-port N/A Kea does not support OMAPI.
one-lease-per-client
pid-file-name
ping-check
ping-timeout
preferred-lifetime
remote-port
server-identifier
server-duid
server-name
site-option-space
stash-agent-options
update-conflict-detection N/A When entering names into DNS, Kea always performs conflict detection.
update-optimization
update-static-leases
use-host-decl-names
use-lease-addr-for-default-route
vendor-option-space

Other Server Configuration

ISC DHCP Element Kea Equivalent Notes
class In Kea, an incoming packet with the vendor class option (60 in DHCPv4, 16 in DHCPv6) set is assigned to the class VENDOR_CLASS_value (where "value" is the value in the vendor class option).
failover peer Failover is not currently implemented in Kea
group
host Host reservations are planned for Kea 1.0
include This is likely to be implemented in the future in Kea, but is not available now.
netmask See subnet
pool  
prefix
range Dhcp(4|6)/subnet(4|6)[n]/pool In Kea, a single "pool" statement can define multiple address ranges. The address range can also be expressed in CIDR notation.
shared-network
subnet Dhcp4/subnet4[n]/subnet
subnet6 Dhcp6/subnet6[n]/subnet
subclass

Option Definitions and Settings

ISC DHCP Element Kea Equivalent Notes
option name value {, value ... }
(Global option setting)
Dhcp(4|6)/option-data[n]/name "option-name"
Dhcp(4|6)/option-data[n]/data "value{,value...}"
The future Kea syntax is expressed here, where option space, code and cvs-format fields are not needed.
option name value {, value ... }
(Per-subnet option setting)
Dhcp4/subnet(4|6)[m]/option-data[n]/name "option-name"
Dhcp(4|6)/subnet(4|6)[m]/option-data[n]/data "value{,value...}"
The future Kea syntax is expressed here, where option space, code and cvs-format fields are not needed.

Global Access Control

The following are access control statements that can be used globally. Although the examples use allow, prohibition of access can be obtained by using deny instead.

ISC DHCP Element Kea Equivalent Notes
allow unknown-clients
allow bootp N/A There is no correspondence in Kea: BOOTP is not supported.
allow booting
allow duplicates
allow declines
allow client-updates
allow leasequery Lease queries are not currently supported in Kea.

Pool Access Control

The following are access control statements that can be used within a pool clause. Although the examples use allow, prohibition of access can be obtained by using deny instead.

ISC DHCP Element Kea Equivalent Notes
allow known-clients
allow unknown-clients
allow members of Dhcp(4|6)/subnet(4|6)[n]/client-class
allow dynamic bootp clients N/A Kea does not support the BOOTP protocol.
allow authenticated clients
allow unauthenticated clients
allow all clients
allow after

Data Matching

In ISC DHCP, a server is able to examine the incoming packet and use the information in (for example) assigning the client to a class. The information (e.g. the value of an option) can be used as-is, but the server can also perform operations on the data and make decisions as to the results. The following tables list the various types of behavior available.

Conditional Behavior

ISC DHCP Construct Explanation Kea Equivalent Notes
if Defines clause used if result of test is true.
elsif Defines clause used if result of test is true.
else Defines clause used if result of test is false.
switch Select between multiple values.

Boolean Expressions

These expressions can be used in a conditional test.

ISC DHCP Construct Explanation Kea Equivalent Notes
= Check for equality.
~= Case-sensitive regular expression check.
~~ Case-insensitive regular expression check.
and Boolean AND.
or Boolean inclusive OR.
not Boolean NOT.
exists Used with the name of an option, returns true if the option exists in the incoming packet.
known Returns true if the client for which a request is being processed has been declared with a host declaration.
static Returns true if the lease assigned to client for which a request is being processed is derived from a static address assignment.

Data Expressions

These expressions can be used in a conditional test.

ISC DHCP Construct Explanation Kea Equivalent Notes
substring Extracts a substring from the argument.
suffix Returns the last bytes of the argument.
lcase Returns the argument converted to lowercase.
ucase Returns the argument converted to uppercase.
option Returns the value of the specified option from the packet being processed.
config-option Returns the value of the specified option that the server has been configured to send.
gethostname() Returns the name of the local system.
hardware Returns data comprising the type and hardware address of the client.
packet Extracts arbitrary bytes from the packet being processed.
concat Result of concatenating multiple data values.
reverse Reverse the bytes of a data value in fixed-size chunks.
leased-address IP address (if assigned) of the client being processed.
binary-to-ascii Converts numeric data to ASCII.
encode-int Evaluate data and encode as a data string.
pick-first-value Select first non-null expression in list passed to the function.
host-decl-name Returns name of host declaration matching that of client being processed.
extract-int Extracts an integer from a numeric expression.
lease-time Returns the duration of the current lease.
client-state Current state of the client being processed.
number Specification of an arbitrary number.
string Specification of an arbitrary string.
xx:xx:... Specification of an arbitrary set of bytes as colon-separated hexadecimal values.

Action Statements

Based on statements in the configuration file, the server can take certain actions when particular conditions are satisfied:

ISC DHCP Construct Explanation Kea Equivalent Notes
log Log information to the ISC DHCP logging channel.
execute Synchronously execute an external command.

LDAP

ISC DHCP has a number of configuration elements related to LDAP. At present, Kea does not support LDAP, so none of these elements (all with names starting "ldap-") have Kea equivalents.

Last modified 3 years ago Last modified on Jun 12, 2014, 5:04:19 PM