summaryrefslogtreecommitdiffstats
path: root/modules/view/README.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--modules/view/README.rst92
1 files changed, 92 insertions, 0 deletions
diff --git a/modules/view/README.rst b/modules/view/README.rst
new file mode 100644
index 0000000..daffd30
--- /dev/null
+++ b/modules/view/README.rst
@@ -0,0 +1,92 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _mod-view:
+
+Views and ACLs
+==============
+
+The :ref:`policy <mod-policy>` module implements policies for global query matching, e.g. solves "how to react to certain query".
+This module combines it with query source matching, e.g. "who asked the query". This allows you to create personalized blacklists, filters and ACLs.
+
+There are two identification mechanisms:
+
+* ``addr``
+ - identifies the client based on his subnet
+* ``tsig``
+ - identifies the client based on a TSIG key name (only for testing purposes, TSIG signature is not verified!)
+
+View module allows you to combine query source information with :ref:`policy <mod-policy>` rules.
+
+.. code-block:: lua
+
+ view:addr('10.0.0.1', policy.suffix(policy.TC, policy.todnames({'example.com'})))
+
+This example will force given client to TCP for names in ``example.com`` subtree.
+You can combine view selectors with RPZ_ to create personalized filters for example.
+
+.. warning::
+
+ Beware that cache is shared by *all* requests. For example, it is safe
+ to refuse answer based on who asks the resolver, but trying to serve
+ different data to different clients will result in unexpected behavior.
+ Setups like **split-horizon** which depend on isolated DNS caches
+ are explicitly not supported.
+
+
+Example configuration
+---------------------
+
+.. code-block:: lua
+
+ -- Load modules
+ modules = { 'view' }
+ -- Whitelist queries identified by TSIG key
+ view:tsig('\5mykey', policy.all(policy.PASS))
+ -- Block local IPv4 clients (ACL like)
+ view:addr('127.0.0.1', policy.all(policy.DENY))
+ -- Block local IPv6 clients (ACL like)
+ view:addr('::1', policy.all(policy.DENY))
+ -- Drop queries with suffix match for remote client
+ view:addr('10.0.0.0/8', policy.suffix(policy.DROP, policy.todnames({'xxx'})))
+ -- RPZ for subset of clients
+ view:addr('192.168.1.0/24', policy.rpz(policy.PASS, 'whitelist.rpz'))
+ -- Do not try this - it will pollute cache and surprise you!
+ -- view:addr('10.0.0.0/8', policy.all(policy.FORWARD('2001:DB8::1')))
+ -- Drop all IPv4 that hasn't matched
+ view:addr('0.0.0.0/0', policy.all(policy.DROP))
+
+Rule order
+----------
+
+The current implementation is best understood as three separate rule chains:
+vanilla ``policy.add``, ``view:tsig`` and ``view:addr``.
+For each request the rules in these chains get tried one by one until a :ref:`non-chain policy action <mod-policy-actions>` gets executed.
+
+By default :ref:`policy module <mod-policy>` acts before ``view`` module due to ``policy`` being loaded by default. If you want to intermingle universal rules with ``view:addr``, you may simply wrap the universal policy rules in view closure like this:
+
+.. code-block:: lua
+
+ view:addr('0.0.0.0/0', policy.<rule>) -- and
+ view:addr('::0/0', policy.<rule>)
+
+
+Properties
+----------
+
+.. function:: view:addr(subnet, rule)
+
+ :param subnet: client subnet, e.g. ``10.0.0.1``
+ :param rule: added rule, e.g. ``policy.pattern(policy.DENY, '[0-9]+\2cz')``
+
+ Apply rule to clients in given subnet.
+
+.. function:: view:tsig(key, rule)
+
+ :param key: client TSIG key domain name, e.g. ``\5mykey``
+ :param rule: added rule, e.g. ``policy.pattern(policy.DENY, '[0-9]+\2cz')``
+
+ Apply rule to clients with given TSIG key.
+
+ .. warning:: This just selects rule based on the key name, it doesn't verify the key or signature yet.
+
+.. _RPZ: https://dnsrpz.info/