From: Thomas Markwalder Date: Mon, 23 Jul 2018 11:55:56 +0000 (-0400) Subject: [5680] Updated kea admin guide X-Git-Tag: ha_phase2~28 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ae906a531ea252775ff7ba16eedebbf2acc62dd3;p=thirdparty%2Fkea.git [5680] Updated kea admin guide dhcp4-srv.xml dhcp6-srv.xml Added sections for host-name-sanitizing --- diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index e09b543b64..e8ca422461 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2579,7 +2579,6 @@ It is merely echoed by the server "replace-client-name": "never" - "generated-prefix": "myhost" @@ -2916,33 +2915,33 @@ It is merely echoed by the server
- Sanitizing Client host names - It may be that some of your DHCP clients provide values in the Host Name - option (Option code 12), that contain undesirable characters. It is possible - to configure kea-dhcp4 to sanitize these values. The most typical use case - would be ensuring that only characters that are permitted by RFC 1035 be included: + Sanitizing Client Host Name and FQDN Names + It may be that some of your DHCP clients provide values in the Host + Name option (Option code 12) or FQDN option (Option code 81), that + contain undesirable characters. It is possible to configure kea-dhcp4 + to sanitize these values. The most typical use case would be ensuring + that only characters that are permitted by RFC 1035 be included: A-Z,a-z,0-9, and '-'. This may be accomplished with following two parameters: - hostname-char-set - a regular expression describing the - invalid character set. This can be any valid, regular expression using - POSIX extended expression syntax. For example, "[^A-Za-z0-9-]" would - replace any character other then the letters A through Z, a through, digits 0 - through 9, and '-'. If your clients include domain names, you will need to make - sure that the dot, '.', is included the your expression: "[^A-Za-z0-9.-]". - The default value is an empty string and disables sanitization. + hostname-char-set - a regular expression describing + the invalid character set. This can be any valid, regular expression + using POSIX extended expression syntax. For example, "[^A-Za-z0-9-]" + would replace any character other then the letters A through z, digits + 0 through 9, and '-'. An empty string, the default value, disables + sanitization. - hostname-char-replacement - a string of zero or more characters - with which to replace each invalid character in the host name. The default value - is an empty string and will cause invalid characters to be OMITTED rather than - replaced. + hostname-char-replacement - a string of zero or + more characters with which to replace each invalid character in the + host name. The default value is an empty string and will cause + invalid characters to be OMITTED rather than replaced. - The following configuration, will replace anything other than a letter, digit, - hyphen, or dot with the letter 'x': + The following configuration, will replace anything other than a + letter, digit, hyphen, or dot with the letter 'x': "Dhcp4": { "dhcp-ddns": { @@ -2953,10 +2952,46 @@ It is merely echoed by the server ... } - Thus, a client supplied value of "myhost-$[123.org" would become "myhost-xx123.org" - Note that sanitization is peformed only on the portion of the name supplied by the - Host Name option, and that this is done before applying the qualifying suffix (if - one is defined). + Thus, a client supplied value of "myhost-$[123.org" would become + "myhost-xx123.org". Sanitizing is performed only on the portion of + the name supplied by the client and it is performed before applying + a qualifying suffix (if one is defined and needed). + + The following are some considerations to keep in mind: + + Name sanitizing is meant to catch the more common cases of invalid + characters through a relatively simple character replacement scheme. + It is difficult to devise a scheme that works well in all cases, + for both Host Name and FQDN options. If you find you have clients + that are using odd, corner cases of character combinations that cannot + be readily handled with this mechanism, you should consider writing + a hook that can carry out sufficiently complex logic to address your + needs. + + + If your clients include domain names in the Host Name option and you + want these preserved, you will need to make sure that the dot, '.', is + considered a valid character by the hostname-char-set expression, such + as this: "[^A-Za-z0-9.-]". This will not affect dots in FQDN Option + values. When scrubbing FQDNs, dots are treated as delimiters and used + to separate the option value into individual domain labels that are + scrubbed and then re-assembled. + + + If your clients are sending values that differ only by characters + considered as invalid by your hostname-char-set, be aware that scrubbing + them will yield identical values. In such cases, DDNS conflict rules + will permit only one of them from registering the name. + + + Finally, given the latitude clients have in the values they send, it is + virtually impossible to guarantee that a combination of these two + parameters will always yield a name that is valid for use in DNS. For + example, using an empty value for hostname-char-replacment could yield + an empty domain label within a name, if that label consists only of + invalid characters. + +
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index 3c3fcc94c2..2488ced5d0 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -2513,6 +2513,12 @@ should include options from the isc option space: "generated-prefix": "myhost" + + "hostname-char-set": "" + + + "hostname-char-replacement": "" + @@ -2852,6 +2858,80 @@ should include options from the isc option space: myhost-3001-1--70E.example.com. +
+ Sanitizing Client FQDN Names + It may be that some of your DHCP clients provide values in the name + component of the FQDN option (Option code 39), that contain undesirable + characters. It is possible to configure kea-dhcp5 to sanitize these + values. The most typical use case would be ensuring that only + characters that are permitted by RFC 1035 be included: + A-Z,a-z,0-9, and '-'. This may be accomplished with following two + parameters: + + + hostname-char-set - a regular expression describing + the invalid character set. This can be any valid, regular expression + using POSIX extended expression syntax. For example, "[^A-Za-z0-9-]" + would replace any character other then the letters A through z, digits + 0 through 9, and '-'. An empty string, the default value, disables + sanitization. + + + hostname-char-replacement - a string of zero or + more characters with which to replace each invalid character in the + client value. The default value is an empty string and will cause + invalid characters to be OMITTED rather than replaced. + + + The following configuration, will replace anything other than a + letter, digit, hyphen, or dot with the letter 'x': + +"Dhcp4": { + "dhcp-ddns": { + "hostname-char-set": "[^A-Za-z0-9.-]", + "hostname-char-replacement": "x", + ... + }, + ... +} + + Thus, a client supplied value of "myhost-$[123.org" would become + "myhost-xx123.org". Sanitizing is performed only on the portion of + the name supplied by the client and it is performed before applying + a qualifying suffix (if one is defined and needed). + + The following are some considerations to keep in mind: + + Name sanitizing is meant to catch the more common cases of invalid + characters through a relatively simple character replacement scheme. + It is difficult to devise a scheme that works well in all cases and + should you find you have clients that are using odd, corner cases of + character combinations that cannot be readily handled with this + mechanism, you should consider writing a hook that can carry out + sufficiently complex logic to address your needs. + + + You do not account for dots ins your hostname-char-set expression. + When scrubbing FQDNs, dots are treated as delimiters and used to + separate the option value into individual domain labels that are + scrubbed and then re-assembled. + + + If your clients are sending values that differ only by characters + considered as invalid by your hostname-char-set, be aware that scrubbing + them will yield identical values. In such cases, DDNS conflict rules + will permit only one of them from registering the name. + + + Finally, given the latitude clients have in the values they send, it is + virtually impossible to guarantee that a combination of these two + parameters will always yield a name that is valid for use in DNS. For + example, using an empty value for hostname-char-replacment could yield + an empty domain label within a name, if that label consists only of + invalid characters. + + +