Skip to content
Snippets Groups Projects
Commit 3dd61e7a authored by Daniel Salzman's avatar Daniel Salzman
Browse files

doc: rework the description of extended ACL configuration for DDNS

parent 50096281
Branches
Tags
1 merge request!1462Extended documentation of ACL for DDNS
Pipeline #100312 passed with stages
in 4 minutes and 45 seconds
Hide whitespace changes
Inline Side-by-side
doc/configuration.rst
+ 64
− 48
View file @ 3dd61e7a
......@@ -138,16 +138,8 @@ the given request is applied and the remaining rules are ignored. Some examples:
- domain: acl2.example.com
acl: [deny_all, key_rule] # Allow with the TSIG except for the subnet
For dynamic DNS updates, additional conditions may be specified for more granular
filtering. Example::
acl:
- id: owner_type_rule
action: update
update-type: [A, AAAA, MX] # Updated records must match one of the specified types
update-owner: name # Updated record owners are restricted by the next conditions
update-owner-match: equal # The record owner must exactly match one name from the next list
update-owner-name: [a, b.example.com.] # Note that non-FQDN names are relative to the effective zone name
In the case of dynamic DNS updates, some additional conditions may be specified
for more granular filtering. See more in the section :ref:`Restricting dynamic updates`.
.. NOTE::
If more conditions (address ranges and/or a key)
......@@ -289,61 +281,85 @@ processed::
- domain: example.com
acl: update_acl
.. _Restricting dynamic updates:
Restricting dynamic updates
---------------------------
The :ref:`update-owner<acl_update_owner>` ACL option allows not only to
compare the updated record's name ("owner") with a list in
:ref:`update-owner-name<acl_update_owner_name>` as introduced above, but also
to compare against the name of the zone being updated::
There are several additional ACL options for dynamic DNS updates which affect
the request classification based on the update contents.
key:
- id: ddns-key
...
Updates can be restricted to specific resource record types::
acl:
- id: zone_update_acl
key: ddns-key
update-owner: zone
action: zone_update_acl
- id: type_rule
action: update
update-type: [A, AAAA, MX] # Updated records must match one of the specified types
zone:
- domain: example.com.
acl: zone_acl
- domain: example.net.
acl: zone_acl
Another possibility is restriction on the owner name of updated records. The option
:ref:`acl_update-owner` is used to select the source of domain
names which are used for the comparison. And the option :ref:`acl_update-owner-match`
specifies the required relation between the record owner and the reference domain
names. Example::
This permits update requests signed by the TSIG key `ddns-key` to update
records at the zone apex of the two zones. Updates to the whole zone can be
permitted by setting :ref:`update-owner-match<acl_update_owner_match>` to
`sub-or-equal` additionally.
acl:
- id: owner_rule1
action: update
update-owner: name # Updated record owners are restricted by the next conditions
update-owner-match: equal # The record owner must exactly match one name from the next list
update-owner-name: [foo, bar.] # Reference domain names
Furthermore update ACLs can match the record owner against an incoming
request's TSIG key id. The key id is defined by the :ref:`id<key_id>` field
in the :ref:`key<key>` section. We do this as follows::
.. NOTE::
If the specified owner name is non-FQDN (e.g. ``foo``), it's considered relatively
to the effective zone name. So it can apply to more zones
(e.g. ``foo.example.com.`` or ``foo.example.net.``). Alternatively, if the
name is FQDN (e.g. ``bar.``), the rule only applies to this name.
If the reference domain name is the zone name, the following variant can be used::
acl:
- id: owner_rule2
action: update
update-owner: zone # The reference name is the zone name
update-owner-match: sub # Any record owner matches except for the zone name itself
template:
- id: default
acl: owner_rule2
zone:
- domain: example.com.
- domain: example.net.
The last variant is for the cases where the reference domain name is a TSIG key name,
which must be used for the transaction security::
key:
- id: example.com.
...
- id: example.net.
...
- id: example.com # Key names are always considered FQDN
...
- id: steve.example.net
...
- id: jane.example.net
...
acl:
- id: ddns_acl
update-owner: key
key: [example.com., example.net.]
action: update
- id: owner_rule3_com
action: update
update-owner: key # The reference name is the TSIG key name
update-owner-match: sub # The record owner must be a subdomain of the key name
key: [example.com] # One common key for updating all non-apex records
- id: owner_rule3_net
action: update
update-owner: key # The reference name is the TSIG key name
update-owner-match: equal # The record owner must exactly match the used key name
key: [steve.example.net, jane.example.net] # Keys for updating specific zone nodes
zone:
- domain: example.com.
acl: ddns_acl
acl: owner_rule3_com
- domain: example.net.
acl: ddns_acl
This way each key can only change records in the domain corresponding to it's
name. Here we only allow updates at the zone apex but we can use
:ref:`update-owner-match<acl_update_owner_match>` again to allow updates to
the whole zone if desired.
acl: owner_rule3_net
.. _dnssec:
......
doc/man/knot.conf.5in
+ 6
− 6
View file @ 3dd61e7a
......@@ -1256,14 +1256,14 @@ set by the \fI\%update\-owner\fP option.
Possible values:
.INDENT 0.0
.IP \(bu 2
\fBsub\-or\-equal\fP — The owner of each Resource Record in an update must either be equal to
or be a subdomain of at least one domain set by \fI\%update\-owner\fP\&.
\fBsub\-or\-equal\fP — The owner of each RR in an update must either be equal to
or be a subdomain of at least one domain name set by \fI\%update\-owner\fP\&.
.IP \(bu 2
\fBequal\fP — The owner of each updated RR must be equal to at least one domain set by
\fI\%update\-owner\fP\&.
\fBequal\fP — The owner of each updated RR must be equal to at least one domain
name set by \fI\%update\-owner\fP\&.
.IP \(bu 2
\fBsub\fP — The owner of each updated RR must be a subdomain of, but MUST NOT be equal to at least
one domain set by \fI\%update\-owner\fP\&.
\fBsub\fP — The owner of each updated RR must be a subdomain of, but MUST NOT
be equal to at least one domain name set by \fI\%update\-owner\fP\&.
.UNINDENT
.sp
\fIDefault:\fP sub\-or\-equal
......
doc/migration.rst
+ 1
− 1
View file @ 3dd61e7a
......@@ -190,7 +190,7 @@ exceptions.
ACL
---
Configuration option :ref:`acl_update_owner_name` is newly FQDN-sensitive.
Configuration option :ref:`acl_update-owner-name` is newly FQDN-sensitive.
It means that values ``a.example.com`` and ``a.example.com.`` are not equivalent.
Module synthrecord
......
doc/reference.rst
+ 15
− 15
View file @ 3dd61e7a
......@@ -1336,7 +1336,7 @@ items. If no action is specified, deny all actions.
*Default:* off
.. _acl_update_type:
.. _acl_update-type:
update-type
-----------
......@@ -1346,50 +1346,50 @@ must match one of the specified types.
*Default:* not set
.. _acl_update_owner:
.. _acl_update-owner:
update-owner
------------
This option restricts possible owners of Resource Records in a zone update by comparing
them to either the :ref:`TSIG key<acl_key>` identity, the current zone name, or to a list of
domain names given by the :ref:`update-owner-name<acl_update_owner_name>` option.
The comparison method is given by the :ref:`update-owner-match<acl_update_owner_match>` option.
domain names given by the :ref:`acl_update-owner-name` option.
The comparison method is given by the :ref:`acl_update-owner-match` option.
Possible values:
- ``key`` — The owner of each updated RR must match the identity of the TSIG key if used.
- ``name`` — The owner of each updated RR must match at least one name in the
:ref:`update-owner-name<acl_update_owner_name>` list.
:ref:`acl_update-owner-name` list.
- ``zone`` — The owner of each updated RR must match the current zone name.
*Default:* not set
.. _acl_update_owner_match:
.. _acl_update-owner-match:
update-owner-match
------------------
This option defines how the owners of Resource Records in an update are matched to the domain name(s)
set by the :ref:`update-owner<acl_update_owner>` option.
set by the :ref:`acl_update-owner` option.
Possible values:
- ``sub-or-equal`` — The owner of each Resource Record in an update must either be equal to
or be a subdomain of at least one domain set by :ref:`update-owner<acl_update_owner>`.
- ``equal`` — The owner of each updated RR must be equal to at least one domain set by
:ref:`update-owner<acl_update_owner>`.
- ``sub`` — The owner of each updated RR must be a subdomain of, but MUST NOT be equal to at least
one domain set by :ref:`update-owner<acl_update_owner>`.
- ``sub-or-equal`` — The owner of each RR in an update must either be equal to
or be a subdomain of at least one domain name set by :ref:`acl_update-owner`.
- ``equal`` — The owner of each updated RR must be equal to at least one domain
name set by :ref:`acl_update-owner`.
- ``sub`` — The owner of each updated RR must be a subdomain of, but MUST NOT
be equal to at least one domain name set by :ref:`acl_update-owner`.
*Default:* sub-or-equal
.. _acl_update_owner_name:
.. _acl_update-owner-name:
update-owner-name
-----------------
A list of allowed owners of RRs in a zone update used with :ref:`update-owner<acl_update_owner>`
A list of allowed owners of RRs in a zone update used with :ref:`acl_update-owner`
set to ``name``. Every listed owner name which is not FQDN (i.e. it doesn't end
in a dot) is considered as if it was appended with the target zone name.
Such a relative owner name specification allows better ACL rule reusability across
......
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