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