Commit f03d68a7 authored by Evan Hunt's avatar Evan Hunt
Browse files

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 !227
parents a6f99bb3 dea89f2a
Pipeline #1693 passed with stages
in 7 minutes and 58 seconds
......@@ -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>
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>
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.
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>
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 <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>
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.
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>nametype</replaceable> field has 13
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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment