From: Tomek Mrugalski Date: Wed, 29 Mar 2017 19:43:44 +0000 (-0500) Subject: [5132] Flex-id described X-Git-Tag: trac5196_base~12^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b864228eaa8653bfb20e4018a4761c89c25ec36d;p=thirdparty%2Fkea.git [5132] Flex-id described --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 79b9bb629f..4ae200b0cb 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -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:
flex_id: Flexible Identifiers for Host Reservations - 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. + + The library allows defining an expression, using notation + initially used for client classification only. See 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. + + + The library can be loaded in similar way as other hook libraries. It + takes one mandatory parameter identifier-expression: + +"Dhcp6": { + "hooks-libraries": [ + { + "library": "/path/libdhcp_flex_id.so", + "parameters": { + "identifier-expression": "expression" + } + }, + ... + ] +} + + + + + The flexible identifier library supports both DHCPv4 and DHCPv6. + + + + 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: + +"Dhcp6": { + "subnet6": [{ ..., // subnet definition starts here + "reservations": [ + "flex-id": "'port1234'", // 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": "substring(relay6[0].option[18],0,8)" + } + }, + ... + ] +} + + + + + 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. + + + + 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.