pdns/recursordist/docs/lua-config/rpz.rst

   1 .. _rpz:
   2
   3 Response Policy Zones (RPZ)
   4 ===========================
   5
   6 Response Policy Zone is an open standard developed by Paul Vixie (ISC and Farsight) and Vernon Schryver (Rhyolite), to modify DNS responses based on a policy loaded via a zonefile.
   7
   8 Frequently, Response Policy Zones get to be very large and change quickly, so it is customary to update them over IXFR.
   9 It allows the use of third-party feeds, and near real-time policy updates.
  10
  11 If multiple RPZs are loaded, they get consulted in the order they were
  12 defined in. It is however possible from Lua to make queries skip specific
  13 Response Policy Zones.
  14
  15 Configuring RPZ
  16 ---------------
  17 An RPZ can be loaded from file or slaved from a master. To load from file, use for example:
  18
  19 .. code-block:: Lua
  20
  21     rpzFile("dblfilename")
  22
  23 To slave from a master and start IXFR to get updates, use for example:
  24
  25 .. code-block:: Lua
  26
  27     rpzMaster("192.0.2.4", "policy.rpz")
  28
  29 In this example, 'policy.rpz' denotes the name of the zone to query for.
  30
  31 The action to be taken on a match is defined by the zone itself, but in some cases it might be interesting to be able to override it, and always apply the same action
  32 regardless of the one specified in the RPZ zone. To load from file and override the default action with a custom CNAME to badserver.example.com., use for example:
  33
  34 .. code-block:: Lua
  35
  36     rpzFile("dblfilename", {defpol=Policy.Custom, defcontent="badserver.example.com"})
  37
  38 To instead drop all queries matching a rule, while slaving from a master:
  39
  40 .. code-block:: Lua
  41
  42     rpzMaster("192.0.2.4", "policy.rpz", {defpol=Policy.Drop})
  43
  44 Note that since 4.2.0, it is possible for the override policy specified via 'defpol' to no longer be applied to local data entries present in the zone by setting the 'defpolOverrideLocalData' parameter to false.
  45
  46 As of version 4.2.0, the first parameter of :func:`rpzMaster` can be a list of addresses for failover:
  47
  48     rpzMaster({"192.0.2.4","192.0.2.5:5301"}, "policy.rpz", {defpol=Policy.Drop})
  49
  50   In the example above, two addresses are specified and will be tried one after another until a response is obtained. The first address uses the default port (53) while the second one uses port 5301.
  51   (If no optional port is set, the default port 53 is used)
  52
  53
  54 .. function:: rpzFile(filename, settings)
  55
  56   Load an RPZ from disk.
  57
  58   :param str filename: The filename to load
  59   :param {} settings: A table to settings, see below
  60
  61 .. function:: rpzMaster(address, name, settings)
  62
  63   .. versionchanged:: 4.2.0:
  64
  65     The first parameter can be a list of addresses.
  66
  67   Load an RPZ from AXFR and keep retrieving with IXFR.
  68
  69   :param str address: The IP address to transfer the RPZ from. Also accepts a list of addresses since 4.2.0 in which case they will be tried one after another in the submitted order until a response is obtained.
  70   :param str name: The name of this RPZ
  71   :param {} settings: A table to settings, see below
  72
  73
  74 RPZ settings
  75 ------------
  76
  77 These options can be set in the ``settings`` of both :func:`rpzMaster` and :func:`rpzFile`.
  78
  79 defcontent
  80 ^^^^^^^^^^
  81 CNAME field to return in case of defpol=Policy.Custom
  82
  83 defpol
  84 ^^^^^^
  85 Default policy: `Policy.Custom`_, `Policy.Drop`_, `Policy.NXDOMAIN`_, `Policy.NODATA`_, `Policy.Truncate`_, `Policy.NoAction`_.
  86
  87 defpolOverrideLocalData
  88 ^^^^^^^^^^^^^^^^^^^^^^^
  89 .. versionadded:: 4.2.0
  90   Before 4.2.0 local data entries are always overridden by the default policy.
  91
  92 Whether local data entries should be overridden by the default policy. Default is true.
  93
  94 defttl
  95 ^^^^^^
  96 the TTL of the CNAME field to be synthesized for the default policy.
  97 The default is to use the zone's TTL,
  98
  99 maxTTL
 100 ^^^^^^
 101 The maximum TTL value of the synthesized records, overriding a higher value from ``defttl`` or the zone. Default is unlimited.
 102
 103 .. _rpz-policyName:
 104
 105 policyName
 106 ^^^^^^^^^^
 107 The name logged as 'appliedPolicy' in :doc:`protobuf <protobuf>` messages when this policy is applied.
 108
 109 zoneSizeHint
 110 ^^^^^^^^^^^^
 111 An indication of the number of expected entries in the zone, speeding up the loading of huge zones by reserving space in advance.
 112
 113 Extra settings for rpzMaster
 114 ----------------------------
 115 In addition to the settings above the settings for :func:`rpzMaster` may contain:
 116
 117 tsigname
 118 ^^^^^^^^
 119 The name of the TSIG key to authenticate to the server.
 120 When this is set, `tsigalgo`_ and `tsigsecret`_ must also be set.
 121
 122 tsigalgo
 123 ^^^^^^^^
 124 The name of the TSIG algorithm (like 'hmac-md5') used
 125
 126 tsigsecret
 127 ^^^^^^^^^^
 128 Base64 encoded TSIG secret
 129
 130 refresh
 131 ^^^^^^^
 132 An integer describing the interval between checks for updates.
 133 By default, the RPZ zone's default is used
 134
 135 maxReceivedMBytes
 136 ^^^^^^^^^^^^^^^^^
 137 The maximum size in megabytes of an AXFR/IXFR update, to prevent resource exhaustion.
 138 The default value of 0 means no restriction.
 139
 140 localAddress
 141 ^^^^^^^^^^^^
 142 The source IP address to use when transferring the RPZ.
 143 When unset, :ref:`setting-query-local-address` and :ref:`setting-query-local-address6` are used.
 144
 145 axfrTimeout
 146 ^^^^^^^^^^^
 147 .. versionadded:: 4.1.2
 148   Before 4.1.2, the timeout was fixed on 10 seconds.
 149
 150 The timeout in seconds of the total initial AXFR transaction.
 151 20 by default.
 152
 153 dumpFile
 154 ^^^^^^^^
 155 .. versionadded:: 4.2.0
 156
 157 A path to a file where the recursor will dump the latest version of the RPZ zone after
 158 each successful update. This can be used to keep track of changes in the RPZ zone, or
 159 to speed up the initial loading of the zone via the `seedFile`_ parameter.
 160 The format of the generated zone file is the same than the one used with :func:`rpzFile`,
 161 and can also be generated via:
 162
 163   rec_control dump-rpz *zone-name* *output-file*
 164
 165
 166 seedFile
 167 ^^^^^^^^
 168 .. versionadded:: 4.2.0
 169
 170 A path to a file containing an existing dump of the RPZ zone. The recursor will try to load
 171 the zone from this file on startup, then immediately do an IXFR to retrieve any updates.
 172 If the file does not exist or is not valid, the normal process of doing a full AXFR will
 173 be used instead.
 174 This option allows a faster startup by loading an existing zone from a file instead
 175 of retrieving it from the network, then retrieving only the needed updates via IXFR.
 176 The format of the zone file is the same than the one used with :func:`rpzFile`, and can
 177 for example be generated via:
 178
 179   rec_control dump-rpz *zone-name* *output-file*
 180
 181 It is also possible to use the `dumpFile`_ parameter in order to dump the latest version
 182 of the RPZ zone after each update.
 183
 184 Policy Actions
 185 --------------
 186
 187 If no settings are included, the RPZ is taken literally with no overrides applied.
 188 Several Policy Actions exist
 189
 190 Policy.Custom
 191 ^^^^^^^^^^^^^
 192 Will return a NoError, CNAME answer with the value specified with ``defcontent``,
 193 when looking up the result of this CNAME, RPZ is not taken into account.
 194
 195 Policy.Drop
 196 ^^^^^^^^^^^
 197 Will simply cause the query to be dropped.
 198
 199 Policy.NoAction
 200 ^^^^^^^^^^^^^^^
 201 Will continue normal processing of the query.
 202
 203
 204 Policy.NODATA
 205 ^^^^^^^^^^^^^
 206 Will return a NoError response with no value in the answer section.
 207
 208 Policy.NXDOMAIN
 209 ^^^^^^^^^^^^^^^
 210 Will return a response with a NXDomain rcode.
 211
 212 Policy.Truncate
 213 ^^^^^^^^^^^^^^^
 214 will return a NoError, no answer, truncated response over UDP.
 215 Normal processing will continue over TCP