mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-30 22:15:20 +00:00
Merge branch '233-clarify-documentation-of-update-policy-tcp-self-and-6to4-self' into 'master'
Resolve "Clarify documentation of update-policy tcp-self and 6to4-self" Closes #233 See merge request isc-projects/bind9!227
This commit is contained in:
Evan Hunt
@@ -12441,69 +12441,68 @@ example.com. NS ns2.example.net.
|
|||||||
<command>update-policy</command> option, respectively.
|
<command>update-policy</command> option, respectively.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The <command>allow-update</command> clause works the
|
The <command>allow-update</command> clause is a simple
|
||||||
same way as in previous versions of <acronym>BIND</acronym>.
|
access control list. Any client that matches
|
||||||
It grants given clients the permission to update any
|
the ACL is granted permission to update any record
|
||||||
record of any name in the zone.
|
in the zone.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The <command>update-policy</command> clause
|
The <command>update-policy</command> clause
|
||||||
allows more fine-grained control over what updates are
|
allows more fine-grained control over what updates are
|
||||||
allowed. A set of rules is specified, where each rule
|
allowed. It specifies a set of rules, in which each rule
|
||||||
either grants or denies permissions for one or more
|
either grants or denies permission for one or more
|
||||||
names to be updated by one or more identities. If
|
names in the zone to be updated by one or more
|
||||||
the dynamic update request message is signed (that is,
|
identities. Identity is determined by the key that
|
||||||
it includes either a TSIG or SIG(0) record), the
|
signed the update request using either TSIG or SIG(0).
|
||||||
identity of the signer can be determined.
|
In most cases, <command>update-policy</command> rules
|
||||||
|
only apply to key-based identities. There is no way
|
||||||
|
to specify update permissions based on client source
|
||||||
|
address.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Rules are specified in the <command>update-policy</command>
|
<command>update-policy</command> rules are only meaningful
|
||||||
zone option, and are only meaningful for master zones.
|
for zones of type <command>master</command>, and are
|
||||||
When the <command>update-policy</command> statement
|
not allowed in any other zone type.
|
||||||
is present, it is a configuration error for the
|
It is a configuration error to specify both
|
||||||
<command>allow-update</command> statement to be
|
<command>allow-update</command> and
|
||||||
present. The <command>update-policy</command> statement
|
<command>update-policy</command> at the same time.
|
||||||
(except when set to <literal>local</literal>) only
|
|
||||||
examines the signer of a message; the source
|
|
||||||
address is not relevant.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
A pre-defined <command>update-policy</command> rule can be
|
A pre-defined <command>update-policy</command> rule can be
|
||||||
switched on with the command
|
switched on with the command
|
||||||
<command>update-policy local;</command>.
|
<command>update-policy local;</command>.
|
||||||
Switching on this rule in a zone causes
|
Using this in a zone causes
|
||||||
<command>named</command> to generate a TSIG session key and
|
<command>named</command> to generate a TSIG session key
|
||||||
place it in a file. That key will then be allowed to update
|
when starting up and store it in a file; this key can then
|
||||||
the zone, if the update request is sent from localhost.
|
be used by local clients to update the zone while
|
||||||
|
<command>named</command> is running.
|
||||||
By default, the session key is stored in the file
|
By default, the session key is stored in the file
|
||||||
<filename>/var/run/named/session.key</filename>; the key name
|
<filename>/var/run/named/session.key</filename>, the key name
|
||||||
is "local-ddns" and the key algorithm is HMAC-SHA256.
|
is "local-ddns", and the key algorithm is HMAC-SHA256.
|
||||||
These values are configurable with the
|
These values are configurable with the
|
||||||
<command>session-keyfile</command>,
|
<command>session-keyfile</command>,
|
||||||
<command>session-keyname</command> and
|
<command>session-keyname</command> and
|
||||||
<command>session-keyalg</command> options, respectively).
|
<command>session-keyalg</command> options, respectively.
|
||||||
</para>
|
A client running on the local system, if run with appropriate
|
||||||
<para>
|
|
||||||
A client on the local system, if it is run with appropriate
|
|
||||||
permissions, may read the session key from the key file and
|
permissions, may read the session key from the key file and
|
||||||
use the key to sign update requests. The zone's update
|
use it to sign update requests. The zone's update
|
||||||
policy will be set to allow that key to change any record
|
policy will be set to allow that key to change any record
|
||||||
within the zone. Assuming the key name is "local-ddns",
|
within the zone. Assuming the key name is "local-ddns",
|
||||||
this policy is:
|
this policy is equivalent to:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<programlisting>update-policy { grant local-ddns zonesub any; };
|
<programlisting>update-policy { grant local-ddns zonesub any; };
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
...with an additional restriction that only clients
|
...with the additional restriction that only clients
|
||||||
connecting from the local system will be permitted to send
|
connecting from the local system will be permitted to send
|
||||||
updates.
|
updates.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Note that only one session key is generated; all zones
|
Note that only one session key is generated by
|
||||||
configured to use <command>update-policy local</command>
|
<command>named</command>; all zones configured to use
|
||||||
will accept the same key.
|
<command>update-policy local</command> will accept the same key.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The command <command>nsupdate -l</command> implements this
|
The command <command>nsupdate -l</command> implements this
|
||||||
@@ -12516,50 +12515,60 @@ example.com. NS ns2.example.net.
|
|||||||
</para>
|
</para>
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
( <command>grant</command> | <command>deny</command> ) <replaceable>identity</replaceable> <replaceable>nametype</replaceable> <optional> <replaceable>name</replaceable> </optional> <optional> <replaceable>types</replaceable> </optional>
|
( <command>grant</command> | <command>deny</command> ) <replaceable>identity</replaceable> <replaceable>ruletype</replaceable> <optional> <replaceable>name</replaceable> </optional> <optional> <replaceable>types</replaceable> </optional>
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Each rule grants or denies privileges. Once a message has
|
Each rule grants or denies privileges. Rules are checked
|
||||||
successfully matched a rule, the operation is immediately
|
in the order in which they are specified in the
|
||||||
granted or denied and no further rules are examined. A rule
|
<command>update-policy</command> statement. Once a message
|
||||||
is matched when the signer matches the identity field, the
|
has successfully matched a rule, the operation is immediately
|
||||||
name matches the name field in accordance with the nametype
|
granted or denied, and no further rules are examined. There
|
||||||
field, and the type matches the types specified in the type
|
are 13 types of rules; the rule type is specified by the
|
||||||
field.
|
<command>ruletype</command> field, and the interpretation
|
||||||
|
of other fields varies depending on the rule type.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
No signer is required for <replaceable>tcp-self</replaceable>
|
In general, a rule is matched when the
|
||||||
or <replaceable>6to4-self</replaceable> however the standard
|
key that signed an update request matches the
|
||||||
reverse mapping / prefix conversion must match the identity
|
<command>identity</command> field, the name of the record
|
||||||
field.
|
to be updated matches the <command>name</command> field
|
||||||
|
(in the manner specified by the <command>ruletype</command>
|
||||||
|
field), and the type of the record to be updated matches the
|
||||||
|
<command>types</command> field. Details for each rule type
|
||||||
|
are described below.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The identity field specifies a name or a wildcard
|
The <command>identity</command> field must be set to
|
||||||
name. Normally, this is the name of the TSIG or
|
a fully-qualified domain name. In most cases, this
|
||||||
SIG(0) key used to sign the update request. When a
|
represensts the name of the TSIG or SIG(0) key that must be
|
||||||
TKEY exchange has been used to create a shared secret,
|
used to sign the update request. If the specified name is a
|
||||||
the identity of the shared secret is the same as the
|
wildcard, it is subject to DNS wildcard expansion, and the
|
||||||
identity of the key used to authenticate the TKEY
|
rule may apply to multiple identities. When a TKEY exchange
|
||||||
exchange. TKEY is also the negotiation method used
|
has been used to create a shared secret, the identity of
|
||||||
by GSS-TSIG, which establishes an identity that is
|
the key used to authenticate the TKEY exchange will be
|
||||||
the Kerberos principal of the client, such as
|
used as the identity of the shared secret. Some rule types
|
||||||
<userinput>"user@host.domain"</userinput>. When the
|
use indentities matching the client's Kerberos principal
|
||||||
<replaceable>identity</replaceable> field specifies
|
(e.g, <userinput>"host/machine@REALM"</userinput>) or
|
||||||
a wildcard name, it is subject to DNS wildcard
|
Windows realm (<userinput>machine$@REALM</userinput>).
|
||||||
expansion, so the rule will apply to multiple identities.
|
|
||||||
The <replaceable>identity</replaceable> field must
|
|
||||||
contain a fully-qualified domain name.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
For nametypes <varname>krb5-self</varname>,
|
The <replaceable>name</replaceable> field also specifies
|
||||||
<varname>ms-self</varname>, <varname>krb5-subdomain</varname>,
|
a fully-qualified domain name. This often
|
||||||
and <varname>ms-subdomain</varname> the
|
represents the name of the record to be updated.
|
||||||
<replaceable>identity</replaceable> field specifies
|
Interpretation of this field is dependent on rule type.
|
||||||
the Windows or Kerberos realm of the machine belongs to.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The <replaceable>nametype</replaceable> field has 13
|
If no <command>types</command> are explicitly specified,
|
||||||
|
then a rule matches all types except RRSIG, NS, SOA, NSEC
|
||||||
|
and NSEC3. Types may be specified by name, including
|
||||||
|
"ANY" (ANY matches all types except NSEC and NSEC3,
|
||||||
|
which can never be updated). Note that when an attempt
|
||||||
|
is made to delete all records associated with a name,
|
||||||
|
the rules are checked for each existing record type.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The <replaceable>ruletype</replaceable> field has 13
|
||||||
values:
|
values:
|
||||||
<varname>name</varname>, <varname>subdomain</varname>,
|
<varname>name</varname>, <varname>subdomain</varname>,
|
||||||
<varname>wildcard</varname>, <varname>self</varname>,
|
<varname>wildcard</varname>, <varname>self</varname>,
|
||||||
@@ -12647,20 +12656,23 @@ example.com. NS ns2.example.net.
|
|||||||
</entry>
|
</entry>
|
||||||
<entry colname="2">
|
<entry colname="2">
|
||||||
<para>
|
<para>
|
||||||
This rule matches when the name being updated
|
This rule matches when the name of the record
|
||||||
matches the contents of the
|
being updated matches the contents of the
|
||||||
<replaceable>identity</replaceable> field.
|
<replaceable>identity</replaceable> field.
|
||||||
The <replaceable>name</replaceable> field
|
The <replaceable>name</replaceable> field
|
||||||
is ignored, but should be the same as the
|
is ignored. To avoid confusion, it is recommended
|
||||||
<replaceable>identity</replaceable> field or
|
that this field be set to the same value as the
|
||||||
|
<replaceable>identity</replaceable> field or to
|
||||||
"."
|
"."
|
||||||
The <varname>self</varname> nametype is
|
</para>
|
||||||
most useful when allowing using one key per
|
<para>
|
||||||
|
The <varname>self</varname> rule type is
|
||||||
|
most useful when allowing one key per
|
||||||
name to update, where the key has the same
|
name to update, where the key has the same
|
||||||
name as the name to be updated. The
|
name as the record to be updated. In this case,
|
||||||
<replaceable>identity</replaceable> would
|
the <replaceable>identity</replaceable> field
|
||||||
be specified as <constant>*</constant> (an asterisk) in
|
can be specified as <constant>*</constant>
|
||||||
this case.
|
(an asterisk).
|
||||||
</para>
|
</para>
|
||||||
</entry>
|
</entry>
|
||||||
</row>
|
</row>
|
||||||
@@ -12762,11 +12774,18 @@ example.com. NS ns2.example.net.
|
|||||||
</para>
|
</para>
|
||||||
</entry> <entry colname="2">
|
</entry> <entry colname="2">
|
||||||
<para>
|
<para>
|
||||||
Allow updates that have been sent via TCP and
|
This rule allows updates that have been sent via
|
||||||
for which the standard mapping from the initiating
|
TCP and for which the standard mapping from the
|
||||||
IP address into the IN-ADDR.ARPA and IP6.ARPA
|
client's IP address into the
|
||||||
namespaces match the name to be updated. The
|
<literal>in-addr.arpa</literal> and
|
||||||
name field should be set to "."
|
<literal>ip6.arpa</literal>
|
||||||
|
namespaces match the name to be updated.
|
||||||
|
The <command>identity</command> field must match
|
||||||
|
that name. The <command>name</command> field
|
||||||
|
should be set to ".".
|
||||||
|
Note that, since identity is based on the client's
|
||||||
|
IP address, it is not necessary for update request
|
||||||
|
messages to be signed.
|
||||||
</para>
|
</para>
|
||||||
<note>
|
<note>
|
||||||
It is theoretically possible to spoof these TCP
|
It is theoretically possible to spoof these TCP
|
||||||
@@ -12781,11 +12800,30 @@ example.com. NS ns2.example.net.
|
|||||||
</para>
|
</para>
|
||||||
</entry> <entry colname="2">
|
</entry> <entry colname="2">
|
||||||
<para>
|
<para>
|
||||||
Allow the 6to4 prefix to be update by any TCP
|
This allows the name matching a 6to4 IPv6 prefix,
|
||||||
connection from the 6to4 network or from the
|
as specified in RFC 3056, to be updated by any
|
||||||
corresponding IPv4 address. This is intended
|
TCP connection from either the 6to4 network or
|
||||||
to allow NS or DNAME RRsets to be added to the
|
from the corresponding IPv4 address. This is
|
||||||
reverse tree.
|
intended to allow NS or DNAME RRsets to be added
|
||||||
|
to the <literal>ip6.arpa</literal> reverse tree.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The <command>identity</command> field must match
|
||||||
|
the 6to4 prefix in <literal>ip6.arpa</literal>.
|
||||||
|
The <command>name</command> field should
|
||||||
|
be set to ".".
|
||||||
|
Note that, since identity is based on the client's
|
||||||
|
IP address, it is not necessary for update request
|
||||||
|
messages to be signed.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
In addition, if specified for an
|
||||||
|
<literal>ip6.arpa</literal> name outside of the
|
||||||
|
<literal>2.0.0.2.ip6.arpa</literal> namespace,
|
||||||
|
the corresponding /48 reverse name can be updated.
|
||||||
|
For example, TCP/IPv6 connections
|
||||||
|
from 2001:DB8:ED0C::/48 can update records at
|
||||||
|
<literal>C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa</literal>.
|
||||||
</para>
|
</para>
|
||||||
<note>
|
<note>
|
||||||
It is theoretically possible to spoof these TCP
|
It is theoretically possible to spoof these TCP
|
||||||
@@ -12839,21 +12877,6 @@ example.com. NS ns2.example.net.
|
|||||||
</tbody>
|
</tbody>
|
||||||
</tgroup>
|
</tgroup>
|
||||||
</informaltable>
|
</informaltable>
|
||||||
|
|
||||||
<para>
|
|
||||||
In all cases, the <replaceable>name</replaceable>
|
|
||||||
field must specify a fully-qualified domain name.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If no types are explicitly specified, this rule matches
|
|
||||||
all types except RRSIG, NS, SOA, NSEC and NSEC3. Types
|
|
||||||
may be specified by name, including "ANY" (ANY matches
|
|
||||||
all types except NSEC and NSEC3, which can never be
|
|
||||||
updated). Note that when an attempt is made to delete
|
|
||||||
all records associated with a name, the rules are
|
|
||||||
checked for each existing record type.
|
|
||||||
</para>
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section xml:id="multiple_views"><info><title>Multiple views</title></info>
|
<section xml:id="multiple_views"><info><title>Multiple views</title></info>
|
||||||
|
|||||||
Reference in New Issue
Block a user