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.
+
+
+