Skip to content

GitLab

BIND
BIND
Commit 28f17e82 authored by Evan Hunt's avatar Evan Hunt
Browse files
Options

Merge branch '233-clarify-documentation-of-update-policy-tcp-self-and-6to4-self' into 'v9_11' 

Resolve "Clarify documentation of update-policy tcp-self and 6to4-self"

Closes #233

See merge request !227
parents 72a12272 50aae06d
Pipeline #1688 passed with stages
        in 6 minutes and 46 seconds
        Hide whitespace changes
        Inline Side-by-side
        Showing with 126 additions and 103 deletions
        doc/arm/Bv9ARM-book.xml
        View file @ 28f17e82
        ......@@ -12395,69 +12395,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
        ......@@ -12470,50 +12469,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>,
        ......@@ -12601,20 +12610,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>
        ......@@ -12716,11 +12728,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
        ......@@ -12735,11 +12754,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
        ......@@ -12793,21 +12831,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