From 182a78f1dc9e3163854739cd0dce156aef09f332 Mon Sep 17 00:00:00 2001 From: Havard Eidnes Date: Tue, 25 May 2021 14:51:31 +0200 Subject: [PATCH] Transplant parts of the contributed RPZ documentation. This comes from the doc/IP-BasedActions.pdf file with minor adaptations. --- doc/unbound.conf.5.in | 102 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 94 insertions(+), 8 deletions(-) diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in index 9aa12c65c..7c868e820 100644 --- a/doc/unbound.conf.5.in +++ b/doc/unbound.conf.5.in @@ -1027,6 +1027,7 @@ from the query ID, for speed and thread safety). Default is yes. .TP .B minimal-responses: \fI If yes, Unbound doesn't insert authority/additional sections into response +.\" ' messages when those sections are not required. This reduces response size significantly, and may avoid TCP fallback for some responses. This may cause a slight speedup. The default is yes, even though the DNS @@ -1044,15 +1045,24 @@ of this setting, if a trust anchor is loaded. .TP .B module\-config: \fI<"module names"> Module configuration, a list of module names separated by spaces, surround -the string with quotes (""). The modules can be validator, iterator. -Setting this to "iterator" will result in a non\-validating server. -Setting this to "validator iterator" will turn on DNSSEC validation. -The ordering of the modules is important. -You must also set trust\-anchors for validation to be useful. -The default is "validator iterator". When the server is built with -EDNS client subnet support the default is "subnetcache validator iterator". +the string with quotes (""). The modules can be \fIrespip\fR, +\fIvalidator\fR, or \fIiterator\fR (and possibly more, see below). +Setting this to just "\fIiterator\fR" will result in a non\-validating +server. +Setting this to "\fIvalidator iterator\fR" will turn on DNSSEC validation. +The ordering of the modules is significant, the order decides the +order of processing. +You must also set \fItrust\-anchors\fR for validation to be useful. +Adding \fIrespip\fR to the front will cause RPZ processing to be done on +all queries. +The default is "\fIvalidator iterator\fR". +.IP +When the server is built with +EDNS client subnet support the default is "\fIsubnetcache validator +iterator\fR". Most modules that need to be listed here have to be listed at the beginning -of the line. The cachedb module has to be listed just before the iterator. +of the line. The subnetcachedb module has to be listed just before +the iterator. The python module can be listed in different places, it then processes the output of the module it is just before. The dynlib module can be listed pretty much anywhere, it is only a very thin wrapper that allows dynamic libraries to @@ -1527,6 +1537,82 @@ Use this localzone type, regardless the type configured for the local-zone (both tagged and untagged) and regardless the type configured using access\-control\-tag\-action. .TP 5 +.B response\-ip: \fI +This requires use of the "respip" module. +.IP +If the IP address in an AAAA or A RR in the answer section of a +response matches the specified IP netblock, the specified action will +apply. +\fI\fR has generally the same semantics as that for +\fIaccess-control-tag-action\fR, but there are some exceptions. +.IP +Actions for \fIresponse-ip\fR are different from those for +\fIlocal-zone\fR in that in case of the former there is no point of +such conditions as "the query matches it but there is no local data". +Because of this difference, the semantics of \fIresponse-ip\fR actions +are modified or simplified as follows: The \fIstatic, refuse, +transparent, typetransparent,\fR and \fInodefault\fR actions are +invalid for \fIresponse-ip\fR. +Using any of these will cause the configuration to be rejected as +faulty. The \fIdeny\fR action is non-conditional, i.e. it always +results in dropping the corresponding query. +The resolution result before applying the deny action is still cached +and can be used for other queries. +.TP 5 +.B response-ip-data: \fI <"resource record string"> +This requires use of the "respip" module. +.IP +This specifies the action data for \fIresponse-ip\fR with action being +to redirect as specified by "\fIresource record string\fR". "Resource +record string" is similar to that of \fIaccess-control-tag-action\fR, +but it must be of either AAAA, A or CNAME types. +If the IP-netblock is an IPv6/IPV4 prefix, the record +must be AAAA/A respectively, unless it is a CNAME (which can be used +for both versions of IP netblocks). If it is CNAME there must not be +more than one \fIresponse-ip-data\fR for the same IP-netblock. +Also, CNAME and other types of records must not coexist for the same +IP-netblock, following the normal rules for CNAME records. +The textual domain name for the CNAME does not have to be explicitly +terminated with a dot ("."); the root name is assumed to be the origin +for the name. +.TP 5 +.B response-ip-tag: \fI <"list of tags"> +This requires use of the "respip" module. +.IP +Assign tags to response IP-netblocks. If the IP address in an AAAA or +A RR in the answer section of a response matches the specified +IP-netblock, the specified tags are assigned to the IP address. +Then, if an \fIaccess-control-tag\fR is defined for the client and it +includes one of the tags for the response IP, the corresponding +\fIaccess-control-tag-action\fR will apply. +Tag matching rule is the same as that for \fIaccess-control-tag\fR and +\fIlocal-zones\fR. +Unlike \fIlocal-zone-tag\fR, \fIresponse-ip-tag\fR can be defined for +an IP-netblock even if no \fIresponse-ip\fR is defined for that +netblock. +If multiple \fIresponse-ip-tag\fR options are specified for the same +IP-netblock in different statements, all but the first will be +ignored. +However, this will not be flagged as a configuration error, but the +result is probably not what was intended. +.IP +Actions specified in an +\fIaccess-control-tag-action\fR that has a matching tag with +\fIresponse-ip-tag\fR can be those that are "invalid" for +\fIresponse-ip\fR listed above, since \fIaccess-control-tag-action\fRs +can be shared with local zones. +For these actions, if they behave differently depending on whether +local data exists or not in case of local zones, the behavior for +\fIresponse-ip-data\fR will generally result in NOERROR/NODATA instead +of NXDOMAIN, since the \fIresponse-ip\fR data are inherently type +specific, and non-existence of data does not indicate anything about +the existence or non-existence of the qname itself. +For example, if the matching tag action is \fIstatic\fR but there is +no data for the corresponding \fIresponse-ip\fR configuration, then +the result will be NOERROR/NODATA. +The only case where NXDOMAIN is returned is when an +\fIalways_nxdomain\fR action applies. +.TP 5 .B ratelimit: \fI Enable ratelimiting of queries sent to nameserver for performing recursion. If 0, the default, it is disabled. This option is experimental at this time.