Commit cd497526 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[master] Merge branch 'trac5132' (flex-id)

parents b8f1bc5b 413bce5e
# This is an example configuration file for the DHCPv4 server in Kea.
# It contains one subnet in which there are two static address reservations
# for the clients identified by the MAC addresses.
// This is an example configuration file for the DHCPv4 server in Kea.
// It contains one subnet in which there are two static address reservations
// for the clients identified by the MAC addresses.
{ "Dhcp4":
{
# Kea is told to listen on ethX interface only.
// Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify the the database used to store leases. As of
# September 2016, four database backends are supported: MySQL,
# PostgreSQL, Cassandra, and the in-memory database, Memfile.
# We'll use memfile because it doesn't require any prior set up.
// We need to specify the the database used to store leases. As of
// September 2016, four database backends are supported: MySQL,
// PostgreSQL, Cassandra, and the in-memory database, Memfile.
// We'll use memfile because it doesn't require any prior set up.
"lease-database": {
"type": "memfile",
"lfc-interval": 3600
},
# Addresses will be assigned with a lifetime of 4000 seconds.
// Addresses will be assigned with a lifetime of 4000 seconds.
"valid-lifetime": 4000,
# Renew and rebind timers are commented out. This implies that options
# 58 and 59 will not be sent to the client. In this case it is up to
# the client to pick the timer values according to RFC2131. Uncomment the
# timers to send these options to the client.
# "renew-timer": 1000,
# "rebind-timer": 2000,
# Kea supports reservations by several different types of identifiers:
# hw-address (hardware/MAC address of the client), duid (DUID inserted by the
# client), client-id (client identifier inserted by the client) and circuit-id
# (circuit identifier inserted by the relay agent). When told to do so, Kea can
# check for all of those identifier types, but it takes a costly database lookup
# to do so. It is therefore useful from a performance perspective to use only
# the reservation types that are actually used in a given network.
# The example below is not optimal from a performance perspective, but it
# nicely showcases the host reservation capabilities. Please use the minimum
# set of identifier types used in your network.
// Renew and rebind timers are commented out. This implies that options
// 58 and 59 will not be sent to the client. In this case it is up to
// the client to pick the timer values according to RFC2131. Uncomment the
// timers to send these options to the client.
// "renew-timer": 1000,
// "rebind-timer": 2000,
// Kea supports reservations by several different types of identifiers:
// hw-address (hardware/MAC address of the client), duid (DUID inserted by the
// client), client-id (client identifier inserted by the client) and circuit-id
// (circuit identifier inserted by the relay agent). When told to do so, Kea can
// check for all of those identifier types, but it takes a costly database lookup
// to do so. It is therefore useful from a performance perspective to use only
// the reservation types that are actually used in a given network.
// The example below is not optimal from a performance perspective, but it
// nicely showcases the host reservation capabilities. Please use the minimum
// set of identifier types used in your network.
"host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ],
# Define a subnet with four reservations. Some of the reservations belong
# to the dynamic pool. Kea is able to handle this case, but it is not
# recommended from a performance perspective, as Kea would not only need to
# check if a given address is free, but also whether it is reserved.
# To avoid this check, one can change reservation-mode to out-of-pool, rather
# than 'all'. If a subnet does not have reservations at all, the reservation
# lookup can be skipped altogether (reservation-mode is set to 'disabled').
# Note that the second reservation is for an address which is within the
# range of the pool of the dynamically allocated address. The server will
# exclude this address from this pool and only assign it to the client which
# has a reservation for it.
// Define a subnet with four reservations. Some of the reservations belong
// to the dynamic pool. Kea is able to handle this case, but it is not
// recommended from a performance perspective, as Kea would not only need to
// check if a given address is free, but also whether it is reserved.
// To avoid this check, one can change reservation-mode to out-of-pool, rather
// than 'all'. If a subnet does not have reservations at all, the reservation
// lookup can be skipped altogether (reservation-mode is set to 'disabled').
// Note that the second reservation is for an address which is within the
// range of the pool of the dynamically allocated address. The server will
// exclude this address from this pool and only assign it to the client which
// has a reservation for it.
"subnet4": [
{
"pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
......@@ -62,26 +62,26 @@
"reservation-mode": "out-of-pool",
"reservations": [
# This is a reservation for a specific hardware/MAC address. It's a very
# simple reservation: just an address and nothing else.
// This is a reservation for a specific hardware/MAC address. It's a very
// simple reservation: just an address and nothing else.
{
"hw-address": "1a:1b:1c:1d:1e:1f",
"ip-address": "192.0.2.201"
},
# This is a reservation for a specific client-id. It also shows
# the this client will get a reserved hostname. A hostname can be defined
# for any identifier type, not just client-id.
// This is a reservation for a specific client-id. It also shows
// the this client will get a reserved hostname. A hostname can be defined
// for any identifier type, not just client-id.
{
"client-id": "01:11:22:33:44:55:66",
"ip-address": "192.0.2.202",
"hostname": "special-snowflake"
},
# The third reservation is based on DUID. This reservation also
# defines special option values for this particular client. If
# the domain-name-servers option would have been defined on a global,
# subnet or class level, the host specific values take preference.
// The third reservation is based on DUID. This reservation also
// defines special option values for this particular client. If
// the domain-name-servers option would have been defined on a global,
// subnet or class level, the host specific values take preference.
{
"duid": "01:02:03:04:05",
"ip-address": "192.0.2.203",
......@@ -91,9 +91,9 @@
} ]
},
# The fourth reservation is based on circuit-id. This is an option inserted
# by the relay agent that forwards the packet from client to the server.
# In this example the host is also assigned vendor specific options.
// The fourth reservation is based on circuit-id. This is an option inserted
// by the relay agent that forwards the packet from client to the server.
// In this example the host is also assigned vendor specific options.
{
"client-id": "01:11:22:33:44:55:66",
"ip-address": "192.0.2.204",
......@@ -109,23 +109,36 @@
}
]
},
# This reservation is for a client that needs specific DHCPv4 fields to be
# set. Three supported fields are next-server, server-hostname and
# boot-file-name
// This reservation is for a client that needs specific DHCPv4 fields to be
// set. Three supported fields are next-server, server-hostname and
// boot-file-name
{
"client-id": "01:0a:0b:0c:0d:0e:of",
"client-id": "01:0a:0b:0c:0d:0e:0f",
"ip-address": "192.0.2.205",
"next-server": "192.0.2.1",
"server-hostname": "hal9000",
"boot-file-name": "/dev/null"
},
// This reservation is using flexible identifier. Instead of relying on specific
// field, sysadmin can define an expression similar to what is used for client
// classification, e.g. substring(relay[0].option[17],0,6). Then, based on the
// value of that expression for incoming packet, the reservation is matched.
// Expression can be specified either as hex or plain text using single
// quotes.
// Note: flexible identifier requires flex_id hook library to be loaded to work.
{
"flex-id": "s0mEVaLue",
"ip-address": "192.0.2.206"
}
]
}
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error and fatal) should be logged to stdout.
// The following configures logging. It assumes that messages with at least
// informational level (info, warn, error and fatal) should be logged to stdout.
"Logging": {
"loggers": [
{
......
# This is an example configuration file for DHCPv6 server in Kea
# that showcases how to do host reservations. It is
# assumed that one subnet (2001:db8:1::/64) is available directly
# over ethX interface. A number of hosts have various combinations
# of addresses and prefixes reserved for them.
// This is an example configuration file for DHCPv6 server in Kea
// that showcases how to do host reservations. It is
// assumed that one subnet (2001:db8:1::/64) is available directly
// over ethX interface. A number of hosts have various combinations
// of addresses and prefixes reserved for them.
{ "Dhcp6":
{
# Kea is told to listen on ethX interface only.
// Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify the the database used to store leases. As of
# September 2016, four database backends are supported: MySQL,
# PostgreSQL, Cassandra, and the in-memory database, Memfile.
# We'll use memfile because it doesn't require any prior set up.
// We need to specify the the database used to store leases. As of
// September 2016, four database backends are supported: MySQL,
// PostgreSQL, Cassandra, and the in-memory database, Memfile.
// We'll use memfile because it doesn't require any prior set up.
"lease-database": {
"type": "memfile",
"lfc-interval": 3600
},
# This is pretty basic stuff, it has nothing to do with reservations.
// This is pretty basic stuff, it has nothing to do with reservations.
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
# Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address
# of the client) and duid (DUID inserted by the client). When told to do so, Kea can
# check for each of these identifier types, but it takes a costly database lookup
# to do so. It is therefore useful from a performance perspective to use only
# the reservation types that are actually used in a given network.
// Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address
// of the client) and duid (DUID inserted by the client). When told to do so, Kea can
// check for each of these identifier types, but it takes a costly database lookup
// to do so. It is therefore useful from a performance perspective to use only
// the reservation types that are actually used in a given network.
"host-reservation-identifiers": [ "duid", "hw-address" ],
# The following list defines subnets. Subnet, pools and interface definitions
# are the same as in the regular scenario, without host reservations.
# least subnet and pool entries.
// The following list defines subnets. Subnet, pools and interface definitions
// are the same as in the regular scenario, without host reservations.
// least subnet and pool entries.
"subnet6": [
{
"subnet": "2001:db8:1::/48",
......@@ -44,90 +44,102 @@
"pools": [ { "pool": "2001:db8:1::/120" } ],
"pd-pools": [
{
"prefix": "2001:db8:1:8000::",
"prefix-len": 56,
"delegated-len": 64
}
{
"prefix": "2001:db8:1:8000::",
"prefix-len": 56,
"delegated-len": 64
}
],
"interface": "ethX",
"reservation-mode": "out-of-pool",
# Host reservations. Define several reservations, note that
# they are all within the range of the pool of the dynamically
# allocated address. The server will exclude the addresses from this
# pool and only assign them to the client which has a reservation for
# them.
// Host reservations. Define several reservations, note that
// they are all within the range of the pool of the dynamically
// allocated address. The server will exclude the addresses from this
// pool and only assign them to the client which has a reservation for
// them.
"reservations": [
# This is a simple host reservation. The host with DUID matching
# the specified value will get an address of 2001:db8:1::100.
{
"duid": "01:02:03:04:05:0A:0B:0C:0D:0E",
"ip-addresses": [ "2001:db8:1::100" ]
},
# This is similar to the previous one, but this time the reservation is done
# based on hardware/MAC address. The server will do its best to extract
# the hardware/MAC address from received packets (see 'mac-sources' directive
# for details). This particular reservation also specifies two extra options
# to be available for this client. If there are options with the same code
# specified in a global, subnet or class scope, the values defined at host level
# take precedence.
{
"hw-address": "00:01:02:03:04:05",
"ip-addresses": [ "2001:db8:1::101" ],
"option-data": [
{
"name": "dns-servers",
"data": "3000:1::234"
},
{
"name": "nis-servers",
"data": "3000:1::234"
}],
"client-classes": [ "special_snowflake", "office" ]
},
# This is a bit more advanced reservation. The client with the specified
# DUID will get a reserved address, a reserved prefix and a hostname.
# This reservation is for an address that it not within the dynamic pool.
# Finally, this reservation features vendor specific options for CableLabs,
# which happen to use enterprise-id 4491. Those particular values will
# be returned only to the client that has a DUID matching this reservation.
{
"duid": "01:02:03:04:05:06:07:08:09:0A",
"ip-addresses": [ "2001:db8:1:cafe::1" ],
"prefixes": [ "2001:db8:2:abcd::/64" ],
"hostname": "foo.example.com",
"option-data": [ {
"name": "vendor-opts",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
} ]
// This is a simple host reservation. The host with DUID matching
// the specified value will get an address of 2001:db8:1::100.
{
"duid": "01:02:03:04:05:0A:0B:0C:0D:0E",
"ip-addresses": [ "2001:db8:1::100" ]
},
// This is similar to the previous one, but this time the reservation is done
// based on hardware/MAC address. The server will do its best to extract
// the hardware/MAC address from received packets (see 'mac-sources' directive
// for details). This particular reservation also specifies two extra options
// to be available for this client. If there are options with the same code
// specified in a global, subnet or class scope, the values defined at host level
// take precedence.
{
"hw-address": "00:01:02:03:04:05",
"ip-addresses": [ "2001:db8:1::101" ],
"option-data": [
{
"name": "dns-servers",
"data": "3000:1::234"
},
{
"name": "nis-servers",
"data": "3000:1::234"
}],
"client-classes": [ "special_snowflake", "office" ]
},
// This is a bit more advanced reservation. The client with the specified
// DUID will get a reserved address, a reserved prefix and a hostname.
// This reservation is for an address that it not within the dynamic pool.
// Finally, this reservation features vendor specific options for CableLabs,
// which happen to use enterprise-id 4491. Those particular values will
// be returned only to the client that has a DUID matching this reservation.
{
"duid": "01:02:03:04:05:06:07:08:09:0A",
"ip-addresses": [ "2001:db8:1:cafe::1" ],
"prefixes": [ "2001:db8:2:abcd::/64" ],
"hostname": "foo.example.com",
"option-data": [ {
"name": "vendor-opts",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
} ]
},
// This reservation is using flexible identifier. Instead of relying on specific
// field, sysadmin can define an expression similar to what is used for client
// classification, e.g. substring(relay[0].option[17],0,6). Then, based on the
// value of that expression for incoming packet, the reservation is matched.
// Expression can be specified either as hex or plain text using single
// quotes.
// Note: flexible identifier requires flex_id hook library to be loaded to work.
{
"flex-id": "'somevalue'",
"ip-addresses": [ "2001:db8:1:cafe::2" ]
}
}
]
}
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error and fatal) should be logged to stdout.
// The following configures logging. It assumes that messages with at least
// informational level (info, warn, error and fatal) should be logged to stdout.
"Logging": {
"loggers": [
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "stdout"
}
],
"debuglevel": 0,
"severity": "INFO"
}
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "stdout"
}
],
"debuglevel": 0,
"severity": "INFO"
}
]
}
......
......@@ -205,28 +205,23 @@
example and create your own custom logging hooks.</entry>
</row>
<row>
<entry>Lightweight 4over6</entry>
<entry>Flexible Identifier</entry>
<entry>Support customers</entry>
<entry>Autumn 2016</entry>
<entry>Lightweight 4over6
(<ulink url="http://tools.ietf.org/html/rfc7596">RFC 7596</ulink>)
is a new IPv6 transition
technology that provides IPv4 as a service in IPv6-only
network. It assumes that dual-stack clients will get a regular IPv6
address and IPv6 prefix, but only a fraction of an IPv4 address. The
fraction is specified as port-set, which is essentially a range of
TCP and UDP ports a client can use. By doing the transition on the
client side, this technology eliminates the need to deploy
expensive Carrier Grade NATs within the operator's network. The
problem on the DHCP side is the non-trivial logic behind it: each
client needs to receive an unique set of lightweight 4over6 options
(<ulink url="http://tools.ietf.org/html/rfc7598">RFC 7598</ulink>),
that include the IPv4 address (shared among several
clients), port-set (which is unique among clients sharing the same
IPv4 address) and a number of additional parameters. This hooks
library will generate values of those options dynamically, thus
eliminating the need to manually configure values for each client
separately.
<entry>Kea 1.2.0 beta</entry>
<entry>Kea software provides a way to handle host reservations
that include addresses, prefixes, options, client classes and
other features. The reservation can be based on hardware address,
DUID, circuit-id or client-id in DHCPv4 and using hardware address
or DUID in DHCPv6. However, there are sometimes scenarios where the
reservation is more complex, e.g. uses other options that
mentioned above, uses part of specific options or perhaps even a
combination of several options and fields to uniquely identify a
client. Those scenarios are addressed by the Flexible Identifiers
hook application. It allows defining an expression, similar to
the one used in client classification,
e.g. substring(relay6[0].option[37],0,6). Each incoming packet is
evaluated against that expression and its value is then searched
in the reservations database.
</entry>
</row>
</tbody>
......@@ -341,7 +336,7 @@ and may have the zero or more of the following entries:
</section>
<section>
<title>Forensic Logging Hooks</title>
<title>legal_log: Forensic Logging Hooks</title>
<para>
This section describes the forensic log hooks library. This library
provides hooks that record a detailed log of lease assignments
......@@ -551,6 +546,114 @@ link address: 3001::1, hop count: 1, identified by remote-id:
</para>
</section>
</section>
<section>
<title>flex_id: Flexible Identifiers for Host Reservations</title>
<para>
This section describes a hook application dedicated to generate
flexible identifiers for host reservation. Kea software provides a way
to handle host reservations that include addresses, prefixes, options,
client classes and other features. The reservation can be based on
hardware address, DUID, circuit-id or client-id in DHCPv4 and using
hardware address or DUID in DHCPv6. However, there are sometimes
scenario where the reservation is more complex, e.g. uses other
options that mentioned above, uses part of specific options or perhaps
even a combination of several options and fields to uniquely identify
a client. Those scenarios are addressed by the Flexible Identifiers
hook application.</para>
<para>The library allows defining an expression, using notation
initially used for client classification only. See <xref
linkend="classification-using-expressions" /> for detailed description
of the syntax available. One notable difference is that for client
classification the expression currently has to evaluate to either true
or false, while the flexible identifier expression is expected to
evaluate to a string that will be used as identifier. It is a valid case
for the expression to evaluate to empty string (e.g. in cases where a
client does not sent specific options). This expression is then
evaluated for each incoming packet. This evaluation generates an
identifier that is used to identify the client. In particular, there may
be host reservations that are tied to specific values of the flexible
identifier.</para>
<para>
The library can be loaded in similar way as other hook libraries. It
takes one mandatory parameter identifier-expression:
<screen>
"Dhcp6": { <userinput>
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
"parameters": {
"identifier-expression": "<userinput>expression</userinput>"
}
},
...
] </userinput>
}
</screen>
</para>
<para>
The flexible identifier library supports both DHCPv4 and DHCPv6.
</para>
<para>
EXAMPLE: Let's consider a case of an IPv6 network that has an
independent interface for each of the connected customers. Customers
are able to plug in whatever device they want, so any type of
identifier (e.g. a client-id) is unreliable. Therefore the operator
may decide to use an option inserted by a relay agent to differentiate
between clients. In this particular deployment, the operator verified
that the interface-id is unique for each customer facing
interface. Therefore it is suitable for usage as reservation. However,
only the first 6 bytes of the interface-id are interesting, because
remaining bytes are either randomly changed or not unique between
devices. Therefore the customer decided to use first 6 bytes of the
interface-id option inserted by the relay agent. This could be
achieved by using the following configuration:
<screen>
"Dhcp6": {