mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 14:05:33 +00:00
Code Issues Releases Wiki Activity

[5680] Updated kea admin guide

Browse Source 
dhcp4-srv.xml
dhcp6-srv.xml
    Added sections for host-name-sanitizing
This commit is contained in:
Thomas Markwalder
2018-07-23 07:55:56 -04:00
committed by Tomek Mrugalski
parent ef79d382ce
commit ae906a531e
2 changed files with 138 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
doc/guide/dhcp4-srv.xml
View File

@@ -2579,7 +2579,6 @@ It is merely echoed by the server
<listitem><simpara> <listitem><simpara>
<command>"replace-client-name": "never"</command> <command>"replace-client-name": "never"</command>
</simpara></listitem> </simpara></listitem>
<listitem><simpara> <listitem><simpara>
<command>"generated-prefix": "myhost"</command> <command>"generated-prefix": "myhost"</command>
</simpara></listitem> </simpara></listitem>
@@ -2916,33 +2915,33 @@ It is merely echoed by the server
</para> </para>
</section> </section>
<section xml:id="host-name-sanitization"> <section xml:id="host-name-sanitization">
<title>Sanitizing Client host names</title> <title>Sanitizing Client Host Name and FQDN Names</title>
It may be that some of your DHCP clients provide values in the Host Name It may be that some of your DHCP clients provide values in the Host
option (Option code 12), that contain undesirable characters. It is possible Name option (Option code 12) or FQDN option (Option code 81), that
to configure kea-dhcp4 to sanitize these values. The most typical use case contain undesirable characters. It is possible to configure kea-dhcp4
would be ensuring that only characters that are permitted by RFC 1035 be included: 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 '-'. A-Z,a-z,0-9, and '-'.
This may be accomplished with following two parameters: This may be accomplished with following two parameters:
<itemizedlist> <itemizedlist>
<listitem><simpara> <listitem><simpara>
<command>hostname-char-set</command> - a regular expression describing the <command>hostname-char-set</command> - a regular expression describing
invalid character set. This can be any valid, regular expression using the invalid character set. This can be any valid, regular expression
POSIX extended expression syntax. For example, "[^A-Za-z0-9-]" would using POSIX extended expression syntax. For example, "[^A-Za-z0-9-]"
replace any character other then the letters A through Z, a through, digits 0 would replace any character other then the letters A through z, digits
through 9, and '-'. If your clients include domain names, you will need to make 0 through 9, and '-'. An empty string, the default value, disables
sure that the dot, '.', is included the your expression: "[^A-Za-z0-9.-]". sanitization.
The default value is an empty string and disables sanitization.
</simpara></listitem> </simpara></listitem>
<listitem><simpara> <listitem><simpara>
<command>hostname-char-replacement</command> - a string of zero or more characters <command>hostname-char-replacement</command> - a string of zero or
with which to replace each invalid character in the host name. The default value more characters with which to replace each invalid character in the
is an empty string and will cause invalid characters to be OMITTED rather than host name. The default value is an empty string and will cause
replaced. invalid characters to be OMITTED rather than replaced.
</simpara></listitem> </simpara></listitem>
</itemizedlist> </itemizedlist>
The following configuration, will replace anything other than a letter, digit, The following configuration, will replace anything other than a
hyphen, or dot with the letter 'x': letter, digit, hyphen, or dot with the letter 'x':
<screen> <screen>
"Dhcp4": { "Dhcp4": {
"dhcp-ddns": { "dhcp-ddns": {
@@ -2953,10 +2952,46 @@ It is merely echoed by the server
... ...
} }
</screen> </screen>
Thus, a client supplied value of "myhost-$[123.org" would become "myhost-xx123.org" Thus, a client supplied value of "myhost-$[123.org" would become
Note that sanitization is peformed only on the portion of the name supplied by the "myhost-xx123.org". Sanitizing is performed only on the portion of
Host Name option, and that this is done before applying the qualifying suffix (if the name supplied by the client and it is performed before applying
one is defined). a qualifying suffix (if one is defined and needed).
<note>
The following are some considerations to keep in mind:
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
</note>
</section> </section>
</section> </section>

80
doc/guide/dhcp6-srv.xml
View File

@@ -2513,6 +2513,12 @@ should include options from the isc option space:
<listitem><simpara> <listitem><simpara>
<command>"generated-prefix": "myhost"</command> <command>"generated-prefix": "myhost"</command>
</simpara></listitem> </simpara></listitem>
<listitem><simpara>
<command>"hostname-char-set": ""</command>
</simpara></listitem>
<listitem><simpara>
<command>"hostname-char-replacement": ""</command>
</simpara></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@@ -2852,6 +2858,80 @@ should include options from the isc option space:
<para> <para>
myhost-3001-1--70E.example.com. myhost-3001-1--70E.example.com.
</para> </para>
<section xml:id="host-name-sanitization">
<title>Sanitizing Client FQDN Names</title>
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:
<itemizedlist>
<listitem><simpara>
<command>hostname-char-set</command> - 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.
</simpara></listitem>
<listitem><simpara>
<command>hostname-char-replacement</command> - 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.
</simpara></listitem>
</itemizedlist>
The following configuration, will replace anything other than a
letter, digit, hyphen, or dot with the letter 'x':
<screen>
"Dhcp4": {
"dhcp-ddns": {
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x",
...
},
...
}
</screen>
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).
<note>
The following are some considerations to keep in mind:
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
</note>
</section>
</section> </section>
<section xml:id="dhcp6-dhcp4o6-config"> <section xml:id="dhcp6-dhcp4o6-config">