diff options
Diffstat (limited to 'modules/view/README.rst')
| -rw-r--r-- | modules/view/README.rst | 92 |
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/ |