diff --git a/ChangeLog b/ChangeLog index 61ca2ccdf0..93717321f3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,7 +1,7 @@ 2009. [func] tmark - Added new hook callout points: ddns4_udpate to kea_dhcp4 - and ddns6_update to kea_dhcp6. This enables use of the - ddsn-tuning hook library. + Added new hook callout points: ddns4_udpate to Kea DHCPv4 + server and ddns6_update to Kea DHCPv6 server. This enables + use of the ddsn-tuning hook library. (Gitlab #1548) 2008. [func]* tomek diff --git a/doc/sphinx/arm/hooks-ddns-tuning.rst b/doc/sphinx/arm/hooks-ddns-tuning.rst index 65c25b22c8..01328e6626 100644 --- a/doc/sphinx/arm/hooks-ddns-tuning.rst +++ b/doc/sphinx/arm/hooks-ddns-tuning.rst @@ -7,9 +7,9 @@ This hook library adds support for fine tuning various DNS update aspects. Currently it supports procedural host name generation. The DDNS Tuning hook is a premium feature. -The library, which was added in Kea 2.1.4, is loaded in a -can be loaded by ``kea--dhcp4`` and ``kea-dhcp6`` by adding it -to ``hooks-libraries`` element of the server's configuration: +The library, which was added in Kea 2.1.5, can be loaded by the ``kea-dhcp4`` +and ``kea-dhcp6`` daemons by adding it to ``hooks-libraries`` element of the +server's configuration: .. code-block:: javascript @@ -32,8 +32,8 @@ Procedural Host name generation This hook library provides the ability to generate host names, procedurally, based on an expression. The expression can be defined globally in the hook parameters, using -`hostname-expr`. If defined globally, it will apply to all hosts in all subnets. The -expressions can use all tokens defined in :ref:`classify`. An example of a global +`hostname-expr`. If defined globally, it will apply to all hosts in all subnets. The +expressions can use all tokens defined in :ref:`classify`. An example of a global expression is shown below: .. code-block:: javascript @@ -54,9 +54,9 @@ expression is shown below: } It is also possible to define this parameter in a subnet, using user-context mechanism. -If defined at the subnet level, the expression applies to specific subnet only. If the -subnet expression is defined as empty, "", it will suppresses (or disables) the use of -a global expression for that subnet. An example subnet expression is shown below: +If defined at the subnet level, the expression applies to specific subnet only. If the +subnet expression is defined as empty, "", it suppresses (or disables) the use of a +global expression for that subnet. An example subnet expression is shown below: .. code-block:: javascript @@ -83,14 +83,15 @@ a global expression for that subnet. An example subnet expression is shown belo }] .. note:: - The expression value above uses a slash, '\', to show line continuation. This is for - clarity only and is not valid JSON supported by Kea parsing. The actually value has + + The expression value above uses a slash, '\', to show line continuation. This is for + clarity only and is not valid JSON supported by Kea parsing. The actually value has to be expressed in a single line. .. note:: - Privacy should be taken into consideration when generating a host name. The host name is - usually inserted into the DNS, which is a public system. Exposing identifiers that + Privacy should be taken into consideration when generating a host name. The host name + is usually inserted into the DNS, which is a public system. Exposing identifiers that can be used to track devices, such as MAC address, are usually a very bad idea. The global expression example used MAC address for simplicity. @@ -111,10 +112,10 @@ response to a client query (e.g. DISCOVER, REQUEST) is as follows: within it along with the DDNS behavioral parameters to form the final host name. 4. If there is an ddns-tuning in-scope host name expression (either global or subnet), - calculate the host name using the expression. If the calculated value is not a fully + calculate the host name using the expression. If the calculated value is not a fully qualified name and there is an in-scope ddns-qualifying-suffix, append the suffix. - 5. If value calculated by the hook is not an empty string and is different than the + 5. If the value calculated by the hook is not an empty string and is different than the host name formed in the prior steps (1 or 2), the calculated value becomes the final host name. @@ -141,9 +142,9 @@ response to a client query (e.g. SOLICIT, REQUEST, RENEW, REBIND) is as follows: calculated in steps 1 or 2. 5. If there is a ddns-tuning in-scope host name expression (either global or subnet), - calculate the host name using the expression. If the calculated value is not a fully + calculate the host name using the expression. If the calculated value is not a fully qualified name and there is an in-scope ddns-qualifying-suffix, append the suffix. - 6. If value calculated by the hook is not an empty string and is different than the + 6. If the value calculated by the hook is not an empty string and is different than the host name formed in the prior steps (1 or 2), the calculated value becomes the final host name. diff --git a/src/bin/dhcp4/dhcp4_hooks.dox b/src/bin/dhcp4/dhcp4_hooks.dox index 120cfb7bc3..81ce5b185c 100644 --- a/src/bin/dhcp4/dhcp4_hooks.dox +++ b/src/bin/dhcp4/dhcp4_hooks.dox @@ -35,7 +35,7 @@ is located, the possible actions a callout attached to this hook could take, and a description of the data passed to the callouts. - Next step status: the action taken by the server when a callout chooses to set - status to specified value. Actions not listed explicitly are not supported. + status to specified value. Actions not listed explicitly are not supported. If a callout sets status to unsupported value, this specific value will be ignored and treated as if the status was CONTINUE. @@ -274,13 +274,13 @@ called before "subnet4_select". and various configuration values (e.g host reservations, DDNS behaviorial parameters, etc). Upon return from the callout, any changes to these values will be applied as follows: - - If hostname has changed it will be used to update the - outbound host name (option 12) if it exists, the output FQDN option - (option 81) if it exists, and used as the FQDN sent in DNS updates + - If hostname has changed it will be used to update the outbound + host name (option 12) if it exists, the output FQDN option (option 81) + if it exists, and used as the FQDN sent in DNS updates - Forward DNS update(s) will be done if fwd_udpate is true (and - kea-dhcp-ddns connectivity is enabled) + kea-dhcp-ddns connectivity is enabled) - Reverse DNS update(s) will be done if rev_udpate is true (and - kea-dhcp-ddns connectivity is enabled) + kea-dhcp-ddns connectivity is enabled) - Next step status: Not applicable, its value will be ignored. diff --git a/src/bin/dhcp4/dhcp4_messages.mes b/src/bin/dhcp4/dhcp4_messages.mes index 0e2f2e7946..28aba5c243 100644 --- a/src/bin/dhcp4/dhcp4_messages.mes +++ b/src/bin/dhcp4/dhcp4_messages.mes @@ -393,7 +393,7 @@ The server will now abort processing of the packet as if it was never received. The lease will continue to be assigned to this client. % DHCP4_HOOK_DDNS_UPDATE A hook has updated the DDNS parameters: hostname %1=>%2, forward update %3=>%4, reverse update %5=>%6 -This message indicates that there was a hook called on ddns_update hook point +This message indicates that there was a hook called on ddns4_update hook point and that hook updated the DDNS update parameters: hostname, or whether to conduct forward (A record) or reverse (PTR record) DDNS updates. diff --git a/src/bin/dhcp4/dhcp4_srv.cc b/src/bin/dhcp4/dhcp4_srv.cc index 9abee10b2a..3ef4955c13 100644 --- a/src/bin/dhcp4/dhcp4_srv.cc +++ b/src/bin/dhcp4/dhcp4_srv.cc @@ -94,7 +94,7 @@ struct Dhcp4Hooks { int hook_index_buffer4_send_; ///< index for "buffer4_send" hook point int hook_index_lease4_decline_; ///< index for "lease4_decline" hook point int hook_index_host4_identifier_; ///< index for "host4_identifier" hook point - int hook_index_ddns4_update_; ///< index for "ddns_update" hook point + int hook_index_ddns4_update_; ///< index for "ddns4_update" hook point /// Constructor that registers hook points for DHCPv4 engine Dhcp4Hooks() { @@ -107,7 +107,7 @@ struct Dhcp4Hooks { hook_index_buffer4_send_ = HooksManager::registerHook("buffer4_send"); hook_index_lease4_decline_ = HooksManager::registerHook("lease4_decline"); hook_index_host4_identifier_ = HooksManager::registerHook("host4_identifier"); - hook_index_ddns4_update_ = HooksManager::registerHook("ddns4_update"); + hook_index_ddns4_update_ = HooksManager::registerHook("ddns4_update"); } }; @@ -2049,18 +2049,19 @@ Dhcpv4Srv::processClientName(Dhcpv4Exchange& ex) { // option. In that the server should prefer Client FQDN option and // ignore the Hostname option. try { + Pkt4Ptr query = ex.getQuery(); Pkt4Ptr resp = ex.getResponse(); Option4ClientFqdnPtr fqdn = boost::dynamic_pointer_cast - (ex.getQuery()->getOption(DHO_FQDN)); + (query->getOption(DHO_FQDN)); if (fqdn) { LOG_DEBUG(ddns4_logger, DBG_DHCP4_DETAIL, DHCP4_CLIENT_FQDN_PROCESS) - .arg(ex.getQuery()->getLabel()); + .arg(query->getLabel()); processClientFqdnOption(ex); } else { LOG_DEBUG(ddns4_logger, DBG_DHCP4_DETAIL, DHCP4_CLIENT_HOSTNAME_PROCESS) - .arg(ex.getQuery()->getLabel()); + .arg(query->getLabel()); processHostnameOption(ex); } @@ -2103,12 +2104,10 @@ Dhcpv4Srv::processClientName(Dhcpv4Exchange& ex) { // Optionally, call a hook that may possibly override the decisions made // earlier. if (HooksManager::calloutsPresent(Hooks.hook_index_ddns4_update_)) { - Pkt4Ptr query = ex.getQuery(); - CalloutHandlePtr callout_handle = getCalloutHandle(query); Subnet4Ptr subnet = ex.getContext()->subnet_; - // Pass incoming packet as argument + // Setup the callout arguments. callout_handle->setArgument("query4", query); callout_handle->setArgument("response4", resp); callout_handle->setArgument("subnet4", subnet); @@ -2128,7 +2127,8 @@ Dhcpv4Srv::processClientName(Dhcpv4Exchange& ex) { callout_handle->getArgument("fwd-update", hook_fqdn_fwd); callout_handle->getArgument("rev-update", hook_fqdn_rev); - // If there's anything changed by the hook, log it and then update the parameters + // If there's anything changed by the hook, log it and then update + // the parameters. if ((hostname != hook_hostname) || (fqdn_fwd != hook_fqdn_fwd) || (fqdn_rev != hook_fqdn_rev)) { LOG_DEBUG(hooks_logger, DBGLVL_PKT_HANDLING, DHCP4_HOOK_DDNS_UPDATE) @@ -2138,7 +2138,8 @@ Dhcpv4Srv::processClientName(Dhcpv4Exchange& ex) { fqdn_fwd = hook_fqdn_fwd; fqdn_rev = hook_fqdn_rev; - // If there's an outbound host-name option in the response we need to updated it. + // If there's an outbound host-name option in the response we + // need to updated it with the new host name. OptionStringPtr hostname_opt = boost::dynamic_pointer_cast (resp->getOption(DHO_HOST_NAME)); if (hostname_opt) { diff --git a/src/bin/dhcp6/dhcp6_hooks.dox b/src/bin/dhcp6/dhcp6_hooks.dox index 3984ce8fb0..02ad8f0f71 100644 --- a/src/bin/dhcp6/dhcp6_hooks.dox +++ b/src/bin/dhcp6/dhcp6_hooks.dox @@ -325,13 +325,13 @@ called before "subnet6_select". and various configuration values (e.g host reservations, DDNS behaviorial parameters, etc). Upon return from the callout, any changes to these values will be applied as follows: - - If hostname has changed it will be used to update the outbound FQDN - option (option 39) if it exists, and used as the FQDN sent - in DNS updates + - If hostname has changed it will be used to update the outbound + FQDN option (option 39) if it exists, and used as the FQDN sent in DNS + updates - Forward DNS update(s) will be done if fwd_udpate is true (and - kea-dhcp-ddns connectivity is enabled) + kea-dhcp-ddns connectivity is enabled) - Reverse DNS update(s) will be done if rev_udpate is true (and - kea-dhcp-ddns connectivity is enabled) + kea-dhcp-ddns connectivity is enabled) - Next step status: Not applicable, its value will be ignored. diff --git a/src/bin/dhcp6/dhcp6_messages.mes b/src/bin/dhcp6/dhcp6_messages.mes index 41f1dc737a..c37db67697 100644 --- a/src/bin/dhcp6/dhcp6_messages.mes +++ b/src/bin/dhcp6/dhcp6_messages.mes @@ -445,7 +445,7 @@ book. The argument specifies the client and transaction identification information. % DHCP6_HOOK_DDNS_UPDATE A hook has updated the DDNS parameters: hostname %1=>%2, forward update %3=>%4, reverse update %5=>%6 -This message indicates that there was a hook called on ddns_update hook point +This message indicates that there was a hook called on ddns6_update hook point and that hook updated the DDNS update parameters: hostname, or whether to conduct forward (A record) or reverse (PTR record) DDNS updates. diff --git a/src/bin/dhcp6/dhcp6_srv.cc b/src/bin/dhcp6/dhcp6_srv.cc index 8ca84109ca..b5085022c7 100644 --- a/src/bin/dhcp6/dhcp6_srv.cc +++ b/src/bin/dhcp6/dhcp6_srv.cc @@ -1970,7 +1970,8 @@ Dhcpv6Srv::processClientFqdn(const Pkt6Ptr& question, const Pkt6Ptr& answer, if ((ctx.hostname_ != hook_hostname) || (ctx.fwd_dns_update_!= hook_fwd_dns_update) || (ctx.rev_dns_update_ != hook_rev_dns_update)) { LOG_DEBUG(hooks_logger, DBGLVL_PKT_HANDLING, DHCP6_HOOK_DDNS_UPDATE) - .arg(ctx.hostname_).arg(hook_hostname).arg(ctx.fwd_dns_update_).arg(hook_fwd_dns_update) + .arg(ctx.hostname_).arg(hook_hostname) + .arg(ctx.fwd_dns_update_).arg(hook_fwd_dns_update) .arg(ctx.rev_dns_update_).arg(hook_rev_dns_update); // Update the FQDN option in the response. @@ -2070,8 +2071,6 @@ Dhcpv6Srv::createNameChangeRequests(const Pkt6Ptr& answer, (*l)->fqdn_fwd_ == do_fwd && (*l)->fqdn_rev_ == do_rev)) { extended_only = true; } else { - std::cout << __LINE__ << "**** doing remove - l.hostname: " << (*l)->hostname_ - << ", opt-fqdn: " << opt_fqdn->getDomainName() << std::endl; // Queue a CHG_REMOVE of the old data. // NCR will only be created if the lease hostname is not // empty and at least one of the direction flags is true