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

[5132] Flex-id described

parent 161e61ec
......@@ -216,9 +216,9 @@
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 Identifier
client. Those scenarios are addressed by the Flexible Identifiers
hook application. It allows defining an expression, similar to
the one used in client classiciation,
the one used in client classifiation,
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.
......@@ -550,7 +550,107 @@ link address: 3001::1, hop count: 1, identified by remote-id:
<section>
<title>flex_id: Flexible Identifiers for Host Reservations</title>
<para>
This section describes ... TODO.
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": {
"subnet6": [{ ..., // subnet definition starts here
"reservations": [
<userinput>"flex-id": "'port1234'"</userinput>, // value of the first 8 bytes of the interface-id
"ip-addresses": [ "2001:db8::1" ]
],
}], // end of subnet definitions
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
"parameters": {
"identifier-expression": "<userinput>substring(relay6[0].option[18],0,8)</userinput>"
}
},
...
]
}
</screen>
</para>
<para>
NOTE: Care should be taken when adjusting the expression. If the
expression changes, then all the flex-id values may change, possibly
rendering all reservations based on flex-id unusable until they're
manually updated. Therefore it is strongly recommended to start with
the expression and a handful reservations, adjust the expression as
needed and only after it was confirmed the expression does exactly
what is expected out of it go forward with host reservations on any
broader scale.
</para>
<para>
flex-id values in host reservations can be specified in two
ways. First, they can be expressed as hex string, e.g. bar string
can be represented as 626174. Alternatively, it can be expressed
as quoted value (using double and single quotes), e.g. "'bar'".
The former is more convenient for printable characters, while hex
string values are more convenient for non-printable characters.
</para>
</section>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment