docs: quick start documentation second draft

diff --git a/daemon/README.rst b/daemon/README.rst
index c83e1e17ee1d5ada78cb60451157d95cfc400234..59fbd7b22d29a2637f5e8fc12eb3de93c91594f0 100644 (file)
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -549,15 +549,29 @@ Control sockets
 
 Unless ran manually, knot-resolver is typically started in non-interactive mode.
 The mode gets triggered by using the ``-f`` command-line parameter or by passing sockets from systemd.
+
 You can attach to the the consoles for each process; by default they are in ``rundir/tty/$PID``.
+When running kresd with systemd, you can find the location of the socket(s) using
+``systemctl status kresd-control@*.socket``. Typically, these are in ``/run/knot-resolver/control@*``.
 
-.. note:: When running kresd with systemd, you can find the location of the socket(s) using ``systemctl status kresd-control@*.socket``. Typically, these are in ``/run/knot-resolver/control@*``.
+Connection to the socket can be made by ``netcat`` or ``socat`` through command line.
 
 .. code-block:: bash
 
-   $ nc -U rundir/tty/3008 # or socat - UNIX-CONNECT:rundir/tty/3008
+   $ nc -U rundir/tty/3008 # or socat - UNIX-CONNECT:/run/knot-resolver/control@1
    > cache.count()
-   53
+   83
+
+When successfully connected to a socket, the command line should change to something like ``>``.
+Then you can interact with kresd to see configuration or set a new one.
+There are some basic commands to start with.
+
+.. code-block:: bash
+
+   > help()            # shows help
+   > net.interfaces()  # lists available interfaces
+   > net.list()        # lists running network services
+
 
 The *direct output* of the CLI command is captured and sent over the socket, while also printed to the daemon standard outputs (for accountability). This gives you an immediate response on the outcome of your command.
 Error or debug logs aren't captured, but you can find them in the daemon standard outputs.

diff --git a/doc/index.rst b/doc/index.rst
index a5e2fee0842122d5c88ec6ba60a957dd24cce536..525e083459d20e771b59779f0b41a0ea8a8935ec 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,7 +6,6 @@ Knot Resolver is a minimalistic implementation of a caching validating DNS resol
 Modular architecture keeps the core tiny and efficient,
 and it provides a state-machine like API for extensions.
 
-
 .. toctree::
    :caption: Quick Start
    :name: quickstart

diff --git a/doc/startguide.rst b/doc/startguide.rst
index 305972518012cac6eb1318449ab2d1ab48ed859b..b5f4398650a2a7eb095f1247f58bdb201b60ef11 100644 (file)
--- a/doc/startguide.rst
+++ b/doc/startguide.rst
@@ -4,38 +4,35 @@
 Installation
 ************
 
-- :ref:`build`
-- `All downloadable packages <https://secure.nic.cz/files/knot-resolver>`_
-
+We recommend using these official upstream repositories with the **latest version** of Knot Resolver.
 
-.. Warning::
+.. warning::
 
     Packages available in distribution's repositories are often outdated,
     especially in **Debian** and **Ubuntu** repositories.
 
-We recommend using these official upstream repositories with the **latest version** of Knot Resolver.
-
 **Debian/Ubuntu**
 
 .. code-block:: bash
 
-    ~$ wget https://secure.nic.cz/files/knot-resolver/knot-resolver-release.deb
-    ~$ dpkg -i knot-resolver-release.deb
-    ~$ apt update && apt install -y knot-resolver
+    $ wget https://secure.nic.cz/files/knot-resolver/knot-resolver-release.deb
+    $ dpkg -i knot-resolver-release.deb
+    $ apt update
+    $ apt install -y knot-resolver
 
 **CentOS**
 
 .. code-block:: bash
 
-    ~$ yum install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.el.rpm
-    ~$ yum install -y knot-resolver
+    $ yum install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.el.rpm
+    $ yum install -y knot-resolver
 
 **Fedora**
 
 .. code-block:: bash
 
-    ~$ dnf install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.fedora.rpm
-    ~$ dnf install -y knot-resolver
+    $ dnf install -y https://secure.nic.cz/files/knot-resolver/knot-resolver-release.fedora.rpm
+    $ dnf install -y knot-resolver
 
 **OpenSUSE Leap / Tumbleweed**
 
@@ -44,104 +41,100 @@ Add the *OBS* package repository `home:CZ-NIC:knot-resolver-latest <https://buil
 **Arch Linux**
 
 `Knot-resolver <https://aur.archlinux.org/packages/knot-resolver/>`_
-package is maintained in **AUR**. It can be installed by using AUR helper,
-for instance, ``yay``
+package for Arch Linux is maintained in AUR_.
 
-.. code-block:: bash
 
-    ~$ yay -S knot-resolver
+*****************
+Run Knot Resolver
+*****************
 
+After installation, Knot Resolver's default configuration should work for loopback
+queries. This allows you to test that installation and service setup works before
+managing configuration.
 
-*************
-Configuration
-*************
 
-.. contents::
-   :depth: 1
-   :local:
-
-**Detailed configuration of daemon and modules.**
+Single instance
+===============
 
-- :ref:`Daemon configuration <daemon>`
-- :ref:`Modules configuration <modules>`
+If you're using our packages, the simplest way to run **single instance** of
+Knot Resolver is to use provided Knot Resolver's ``systemd`` integration.
 
-.. note::
+.. note:: The instance of Knot Resolver is a single process incapable of multithreading.
 
-   The configuration syntax is **Lua** language.
+For help run ``man kresd.systemd``
 
-**Startup configuration**
+.. code-block:: bash
 
-To set startup configuration, paste required configuration to ``/etc/knot-resolver/kresd.conf``
-configuration file or run Knot Resolver with ``-c`` parameter to set path to configuration file.
+   $ systemctl start kresd@1.service
 
-**Interactive / Dynamic configuration**
+See logs and status of running instance with ``systemctl status kresd@1.service`` command.
 
-Every Knot Resolver instance has its own *unix domain socket*.
 
-For instance, you start Knot Resolver using systemd
+.. warning::
 
-.. code-block:: bash
+    ``kresd@*.service`` is not enabled by default, thus Knot Resolver won't start automatically after reboot.
+    To start and enable service in one command use ``systemctl enable --now kresd@1.service``
 
-    ~$ systemctl start kresd@1.service
 
+Multiple instances
+==================
 
-Then the related unix domain socket will be available on ``/run/knot-resolver/control@1``
+Knot Resolver can run in multiple independent processes, all sharing the same interface socket and cache.
 
-Connection to the socket can be made by ``socat`` or ``netcat`` through command line
+Because single running instance of Knot Resolver is incapable of multithreading, to use up of all resources,
+for instance, of 4 CPUs system, the best way is to run four instances at a time.
 
 .. code-block:: bash
 
-    ~$ socat - /run/knot-resolver/control@1
-    ~$ nc -U /run/knot-resolver/control@1
-
-When successfully connected to a socket, the command line should change to something like ``>``.
-Then you can interact with Knot Resolver to list configuration or set a new one.
+    $ systemctl start kresd@1.service
+    $ systemctl start kresd@2.service
+    $ systemctl start kresd@3.service
+    $ systemctl start kresd@4.service
 
-There are some useful commands.
+or simpler way
 
 .. code-block:: bash
 
-    > help()            # shows help
-    > net.interfaces()  # lists available interfaces
-    > net.list()        # lists running network services
+    ~$ systemctl start kresd@{1..4}.service
 
-==================
-Bind to interfaces
-==================
 
-Knot Resolver can listen on multiple interfaces that are defined in configuration.
+*************
+Configuration
+*************
 
-.. code-block:: lua
+.. contents::
+   :depth: 1
+   :local:
 
-    net = {'192.168.1.1','fc00::1:1'}
+.. note::
+
+   The configuration syntax is **Lua** language.
+   Please pay close attention to brackets especially in more complex configurations like :func:`policy.add` and :func:`view:addr`.
+   If you are not familiar with Lua you can read `Learn Lua in 15 minutes`_ for a syntax overview.
 
-Default port is ``53``. Port can be specified by separating it by ``@`` from ip address. For example ``'127.0.0.1@5353'``.
+Detailed configuration of daemon and implemented modules:
 
+- :ref:`Daemon configuration <daemon>`
+- :ref:`Modules configuration <modules-implemented>`
 
-Available interfaces can be listed
+Easiest way to configure Knot Resolver is to paste your configuration to
+``/etc/knot-resolver/kresd.conf`` configuration file loaded on resolver's startup.
+You can easily save configuration files and switch between them.
+All configuration files of following examples and more are stored in `/etc/config`_ directory.
 
-.. code-block:: bash
+Bind to interfaces
+==================
 
-   > net.interfaces()
-   [eth1] => {
-      [addr] => {
-         [1] => 192.168.1.1
-         [2] => fc00::1:1
-         [4] => fe80::1:1
-      }
-   }
-   [lo] => {
-      [addr] => {
-         [1] => 127.0.0.1
-         [2] => ::1
-      }
-   }
-
-``net.eth1.addr[1]`` refers to ``192.168.1.1`` and ``net.eth1.addr[2]`` refers to ``fc00::1:1``
+Knot Resolver can listen on multiple interfaces that are defined in
+configuration by :func:`net.listen()` function.
+It also makes possible to configure ports for ``tls``, ``doh``, ``webmgmt``.
 
 .. code-block:: lua
 
-    net = {net.eth1.addr[1],net.eth1.addr[2]}
+    -- examples
+    net.listen('192.168.1.1')
+    net.listen('fc00::1:1')
+    net.listen(net.eth0, 853, { kind = 'tls' })
 
 .. warning::
 
@@ -150,69 +143,39 @@ Available interfaces can be listed
     overlap, and clients would probably refuse such a response.
 
 
-=================
 Internal Resolver
 =================
 
-How to configure Knot Resolver to resolve internal-only domain.
+How to configure Knot Resolver to resolve internal-only domains.
 
 Forward internal-only domain
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For instance, ``company.example`` is the internal-only domain which is not available from the public Internet.
-To resolve internal-only domain, e.g. ``company.exmaple`` a query policy to forward query has to be added.
+To resolve internal-only domain, e.g. ``company.example`` a query policy to forward query has to be added.
 The followind example will add query policy that will trigger ``FORWARD`` action based on suffix of a domain.
 This configuration will forward everything below ``company.example`` domain to ``192.168.1.2`` IP address, port ``443``.
 
 .. code-block:: lua
 
-    -- policy module is required for query policy configuration
-    modules = { 'policy' }
+    -- define internal only domains
+    internalDomains = policy.todnames({'company.example', 'internal.example'})
 
-    -- forward all queries below 'company.example' to '192.168.1.2@443'
-    policy.add(policy.suffix(policy.FORWARD('192.168.1.2@443'), {todname('company.example')}))
-
-
-Example ``kresd.conf``
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: lua
-
-    -- bind to interfaces
-    net = {'192.168.1.1','fc00::1:1'}
-
-    -- load policy module
-    modules = { 'policy' }
-
-    -- forward all queries below suffix 'company.example' to '192.168.1.2@443'
-    policy.add(policy.suffix(policy.FORWARD('192.168.1.2@443'), {todname('company.example')}))
+    -- forward all queries below 'internalDomains' to '192.168.1.2@443'
+    policy.add(policy.suffix(policy.FORWARD({'192.168.1.2@443'}), internalDomains))
 
 
 .. _personalresolver:
 
-====================================
+
 Personal privacy-preserving Resolver
 ====================================
 
-TLS server configuration
-^^^^^^^^^^^^^^^^^^^^^^^^
-.. Warning::
-
-    By default a self-signed certificate is generated.
-    For serious deployments it is strongly recommended to
-    configure your own TLS certificates signed by a trusted CA.
-    This can be done by using function ``net.tls()``.
-
-.. code-block:: lua
-
-    net.tls("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
-
-Calling this function without parameters prints configured TLS paths.
-
 Forwarding over TLS protocol (DNS-over-TLS)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-More examples on :ref:`tls-examples`.
+Forwarding over TLS protocol protects queries send out by resolver.
+It is done by :func:`policy.TLS_FORWARD()` function which provides methods for authentication.
+There is a list of `DNS Privacy Test Servers`_ supporting DNS-over-TLS to test your configuration.
 
 CA+hostname authentication
 ``````````````````````````
@@ -224,10 +187,14 @@ with specified hostname, which is issued by one of trusted CAs.
     -- forward all queries over TLS to the specified server
     policy.add(policy.all(
        policy.TLS_FORWARD({
-          {'2001:DB8::d0c', hostname='res.example.com', ca_file='/etc/knot-resolver/tlsca.crt'}
+          {'2001:DB8::d0c', hostname='res.example.com'}
        })
     ))
 
+The system-wide CA storage is used, which should cover most of use cases.
+More on :func:`policy.TLS_FORWARD()`
+
+
 Key-pinned authentication
 ``````````````````````````
 Instead of CAs, you can specify hashes of accepted certificates in ``pin_sha256``.
@@ -263,74 +230,84 @@ targets.
        })
     ))
 
-Moving cache to tmpfs
-^^^^^^^^^^^^^^^^^^^^^
-Moving cache to temporary file storage.
-Data is stored in volatile memory instead of a persistent storage device.
-On reboot, everything stored in *tmpfs* will be lost.
+Non-persistent cache
+^^^^^^^^^^^^^^^^^^^^
+
+Knot Resolver's cache contains data clients queried for.
+By default the cache is saved on persistent storage device
+it means content in cache is persisted during power-off and reboot.
+
+If you are concerned about attackers who are able to get access to your
+computer system in power-off state and your storage device is not secured by
+encryption you can move the cache to **tmpfs**, temporary file storage.
+The cache content will be saved in memory and lost on power-off or reboot.
+In most of the Unix-like systems ``/tmp``, ``/var/lock`` and ``/var/run`` are commonly *tmpfs*.
+Directory for resolver can be configured by ``systemd-tmpfiles`` to be automatically created on boot.
+
+Copy Knot Resolver's ``tmpfiles.d`` configuration to ``/etc/tmpfiles.d``.
+
+.. code-block:: bash
+
+   $ cp /usr/lib/tmpfiles.d/knot-resolver.conf /etc/tmpfiles.d/knot-resolver.conf
+
+Add directory rules to ``knot-resolver.conf``.
+
+.. code-block:: bash
+
+   $ echo 'd /tmp/knot-resolver 0750 knot-resolver knot-resolver - -' | sudo tee -a /etc/tmpfiles.d/knot-resolver.conf
+
+The file should look like this
 
-For example, in most of the Unix-like systems ``/tmp``, ``/var/lock`` and ``/var/run`` are commonly *tmpfs*.
-You can check file system type by ``df -T /tmp`` command.
+.. code-block:: bash
+
+   $ cat /etc/tmpfiles.d/knot-resolver.conf
+   # tmpfiles.d(5) directories for knot-resolver (kresd)
+   # Type Path                     Mode UID           GID           Age Argument
+     d     /run/knot-resolver       0750 root          root          -   -
+     d     /var/cache/knot-resolver 0750 knot-resolver knot-resolver -   -
+     d     /tmp/knot-resolver       0750 knot-resolver knot-resolver -   -
 
-Move cache storage to ``/tmp/knot-resolver``
+You can reboot system to check if directory was created and then cache can be moved to ``/tmp/knot-resolver``
 
 .. code-block:: lua
 
    cache.storage = 'lmdb:///tmp/knot-resolver'
 
-Check cache storage
 
-.. code-block:: bash
+TLS server configuration
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-   > cache.current_storage
-   lmdb:///tmp/knot-resolver
+This allows clients to send queries to your resolver
+using DNS-over-TLS. It does not protect queries send out by your resolver.
+To protect queries send out by your resolver DNS forwarding over
+DNS-over-TLS needs to be configured.
 
-Example ``kresd.conf``
-^^^^^^^^^^^^^^^^^^^^^^
+Enable tls on listening interfaces.
 
 .. code-block:: lua
 
-   -- bind to interfaces
-   net = {'192.168.1.1','fc00::1:1'}
+   net.listen('192.168.1.1', 853, { kind = 'tls' })
+   net.listen('fc00::1:1', 853, { kind = 'tls' })
 
-   -- configure TLS server
-   net.tls(net.tls("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem"))
 
-   -- Move cache to '/tmp/knot-resolver' tmpfs
-   cache.storage = 'lmdb:///tmp/knot-resolver'
+.. Warning::
 
-   -- load policy module
-   modules = { 'policy' }
+    By default a self-signed certificate is generated.
+    For serious deployments it is strongly recommended to
+    configure your own TLS certificates signed by a trusted CA.
+    This can be done by using function :func:`net.tls()`.
 
-   -- forward over TLS
-   policy.add(policy.all(
-       policy.TLS_FORWARD({
-          {'2001:DB8::d0c', hostname='res.example.com', ca_file='/etc/knot-resolver/tlsca.crt'},
-          {'192.0.2.1', pin_sha256={'YQ=='}
-       })
-    ))
+.. code-block:: lua
 
-   -- forwarding to multiple targets
-   policy.add(policy.slice(
-       policy.slice_randomize_psl(),
-       policy.TLS_FORWARD({{'192.0.2.1', hostname='res.example.com'}}),
-       -- multiple servers can be specified for a single slice
-       -- the one with lowest round-trip time will be used
-       policy.TLS_FORWARD({
-          {'193.17.47.1', hostname='odvr.nic.cz'},
-          {'185.43.135.1', hostname='odvr.nic.cz'},
-       })
-    ))
+    net.tls("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
 
 .. _ispresolver:
 
-============
 ISP Resolver
 ============
 
 Limiting client access
 ^^^^^^^^^^^^^^^^^^^^^^
-More on :ref:`mod-view`
 
 The current implementation is best understood as three separate rule chains:
 vanilla :func:`policy.add()`, :func:`view:tsig()` and :func:`view:addr`.
@@ -343,13 +320,13 @@ View module allows you to combine query source information with policy rules.
 
     modules = { 'view' }
 
-    -- Block local IPv4 clients (ACL like)
+    -- block local IPv4 clients (ACL like)
     view:addr('127.0.0.1', policy.all(policy.DENY))
 
-    -- Drop queries with suffix match for remote client
+    -- brop queries with suffix match for remote client
     view:addr('10.0.0.0/8', policy.suffix(policy.TC, policy.todnames({'example.com'})))
 
-    -- Whitelist queries identified by TSIG key
+    -- whitelist queries identified by TSIG key
     view:tsig('\5mykey', policy.all(policy.PASS))
 
 
@@ -365,14 +342,6 @@ DNS Response Policy Zones Blacklist
    policy.add(policy.rpz(policy.DENY, 'blacklist.rpz'))
 
 
-Hand-made
-`````````
-Hand-made Blacklist
-
-.. code-block:: lua
-
-   --
-
 Max cache size
 ^^^^^^^^^^^^^^
 Maximal cache size can be larger than available RAM,
@@ -384,40 +353,40 @@ For large cache size we don't need to flush cache often.
    cache.size = 4 * GB
 
 
-Statistics
-^^^^^^^^^^
+..   Statistics
+    ^^^^^^^^^^
 
-Worker is a service over event loop that tracks and schedules outstanding queries,
-you can see the statistics or schedule new queries.
+    Worker is a service over event loop that tracks and schedules outstanding queries,
+    you can see the statistics or schedule new queries.
 
-.. code-block:: lua
+    .. code-block:: lua
 
-   -- return table of worker statistics
-   > worker.stats()
+       -- return table of worker statistics
+       > worker.stats()
 
-   -- return table of low-level cache statistics
-   > cache.stats()
+       -- return table of low-level cache statistics
+       > cache.stats()
 
 
-``worker.stats() cache.stats()`` commands can be executed synchronously over all forks.
-Results are returned as a table ordered as forks.
-Expression inserted to ``map ''`` can be any valid expression in Lua.
+    ``worker.stats() cache.stats()`` commands can be executed synchronously over all forks.
+    Results are returned as a table ordered as forks.
+    Expression inserted to ``map ''`` can be any valid expression in Lua.
 
-.. code-block:: lua
+    .. code-block:: lua
 
-    > map 'worker.stats()'
+        > map 'worker.stats()'
 
 
-:ref:`mod-stats` gathers various counters from the query resolution and server internals,
-and offers them as a key-value storage :func:`stats.list()`.
+    :ref:`mod-stats` gathers various counters from the query resolution and server internals,
+    and offers them as a key-value storage :func:`stats.list()`.
 
-.. code-block:: lua
+    .. code-block:: lua
 
-    -- Statistics collector is a module
-    > modules.load('stats')
+        -- statistics collector is a module
+        > modules.load('stats')
 
-    -- Enumerate metrics
-    > stats.list()
+        -- enumerate metrics
+        > stats.list()
 
 
 Monitoring/logging
@@ -435,7 +404,7 @@ Here's an example of an anonymous function with :func:`event.recurrent()`.
 .. code-block:: lua
 
     -- load module for statistics
-    modules.load('stats')
+    modules = { 'stats' }
 
     -- log statistics every second
     local stat_id = event.recurrent(1 * second, function(evid)
@@ -444,7 +413,7 @@ Here's an example of an anonymous function with :func:`event.recurrent()`.
 
     -- stop printing statistics after first minute
     event.after(1 * minute, function(evid)
-            event.cancel(stat_id)
+        event.cancel(stat_id)
     end)
 
 If you need to persist state between events, encapsulate even handle in closure
@@ -452,53 +421,8 @@ function which will provide persistent variable (called ``previous``):
 
 .. code-block:: lua
 
-    modules.load('stats')
-
-    -- make a closure, encapsulating counter
-    function speed_monitor()
-            local previous = stats.list()
-            -- monitoring function
-            return function(evid)
-                    local now = stats.list()
-                    local total_increment = now['answer.total'] - previous['answer.total']
-                    local slow_increment = now['answer.slow'] - previous['answer.slow']
-                    if slow_increment / total_increment > 0.05 then
-                            log('WARNING! More than 5 %% of queries was slow!')
-                    end
-                    previous = now  -- store current value in closure
-             end
-    end
-
-    -- speed monitor every minute
-    local monitor_id = event.recurrent(1 * minute, speed_monitor())
-
-
-Example ``kresd.conf``
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: lua
-
-    -- bind to interfaces
-    net = {'192.168.1.1','fc00::1:1'}
-
-    -- set max cache size
-    cache.size = 4 * GB
-
-    -- modules
-    modules = {
-        'view',
-        'stats'
-    }
-
-    -- log statistics every second
-    local stat_id = event.recurrent(1 * second, function(evid)
-        log(table_print(stats.list()))
-    end)
-
-    -- stop printing statistics after first minute
-    event.after(1 * minute, function(evid)
-            event.cancel(stat_id)
-    end)
+    -- load module for statistics
+    modules = { 'stats' }
 
     -- make a closure, encapsulating counter
     function speed_monitor()
@@ -518,63 +442,10 @@ Example ``kresd.conf``
     -- speed monitor every minute
     local monitor_id = event.recurrent(1 * minute, speed_monitor())
 
-    -- Apply RPZ for all clients, default rule is DENY
-    policy.add(policy.rpz(policy.DENY, 'blacklist.rpz'))
-
-    -- Block local IPv4 clients (ACL like)
-    view:addr('127.0.0.1', policy.all(policy.DENY))
-
-    -- Drop queries with suffix match for remote client
-    view:addr('10.0.0.0/8', policy.suffix(policy.TC, policy.todnames({'example.com'})))
-
-    -- Force all clients from 192.168.2.0/24 to TCP
-    view:addr('192.168.2.0/24', policy.all(policy.TC))
-
-    -- Whitelist queries identified by TSIG key
-    view:tsig('\5mykey', policy.all(policy.PASS))
-
-
-**********
-How to Run
-**********
-
-===============
-Single instance
-===============
-
-If you're using our packages, the simplest way to run **single instance** of Knot Resolver is to use provided Knot Resolver's ``systemd`` integration.
-
-For help run ``man kresd.systemd``
-
-.. code-block:: bash
-
-   ~$ systemctl start kresd@1.service
-
-See logs and status of running instance with ``systemctl status kresd@1.service`` command.
-
-.. Note:: The instance of Knot Resolver is single process incapable of multithreading.
-
-==================
-Multiple instances
-==================
-
-Knot Resolver can run in multiple independent processes, all sharing the same interface socket and cache.
-
-Because single running instance of Knot Resolver is incapable of multithreading, to use up of all resources, for instance, of 4 CPUs system, the best way is to run four instances at a time.
-
-.. code-block:: bash
-
-    ~$ systemctl start kresd@1.service
-    ~$ systemctl start kresd@2.service
-    ~$ systemctl start kresd@3.service
-    ~$ systemctl start kresd@4.service
-
-or simpler way
-
-.. code-block:: bash
-
-    ~$ systemctl start kresd@{1..4}.service
-
 
 .. _SNI: https://en.wikipedia.org/wiki/Server_Name_Indication
-.. _closures: https://www.lua.org/pil/6.1.html
\ No newline at end of file
+.. _closures: https://www.lua.org/pil/6.1.html
+.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
+.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
+.. _`DNS Privacy Test Servers`: https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Test+Servers
+.. _`/etc/config`: https://github.com/CZ-NIC/knot-resolver/tree/master/etc/config
\ No newline at end of file

diff --git a/etc/config/config.internal.in b/etc/config/config.internal.in
new file mode 100644 (file)
index 0000000..ce21a1b
--- /dev/null
+++ b/etc/config/config.internal.in
@@ -0,0 +1,10 @@
+-- vim:syntax=lua:set ts=4 sw=4:
+-- Config file example usable for multi-user ISP resolver
+-- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/startguide.html#internal-resolver
+@config_defaults@
+
+-- define list of internal-only domains
+internalDomains = policy.todnames({'company.example', 'internal.example'})
+
+-- forward all queries below 'internalDomains' to '192.168.1.2@443'
+policy.add(policy.suffix(policy.FORWARD({'192.168.1.2@443'}), internalDomains))
\ No newline at end of file

diff --git a/etc/config/config.isp-old.in b/etc/config/config.isp-old.in
new file mode 100644 (file)
index 0000000..05ea0a9
--- /dev/null
+++ b/etc/config/config.isp-old.in
@@ -0,0 +1,40 @@
+-- vim:syntax=lua:set ts=4 sw=4:
+-- Config file example usable for multi-user ISP resolver
+-- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/daemon.html#configuration
+@config_defaults@
+
+-- For DNS-over-HTTPS and web management when using http module
+-- modules.load('http')
+-- http.config({
+--     cert = '/etc/knot-resolver/mycert.crt',
+--     key = '/etc/knot-resolver/mykey.key',
+--     tls = true,
+-- })
+
+-- To disable DNSSEC validation, uncomment the following line (not recommended)
+-- trust_anchors.remove('.')
+
+-- Large cache size, so we don't need to flush often
+-- This can be larger than available RAM, least frequently accessed
+-- records will be paged out
+cache.size = 4 * GB
+
+-- Load Useful modules
+modules = {
+       'view',     -- Views for certain clients
+       'hints > iterate', -- Load /etc/hosts and allow custom root hints
+       'stats',    -- Track internal statistics
+       graphite = { -- Send statistics to local InfluxDB
+               -- `worker.id` allows us to keep per-fork statistics
+               prefix = hostname()..worker.id,
+               -- Address of the Graphite/InfluxDB server
+               host = '192.168.1.2',
+       },
+}
+
+-- Block all `site.nl` for `10.0.0.0/24` subnet
+view:addr('10.0.0.0/24', policy.suffix(policy.DROP, {todname('site.nl')}))
+-- Force all clients from `192.168.2.0/24` to TCP
+view:addr('192.168.2.0/24', policy.all(policy.TC))
+-- Apply RPZ for all clients, default rule is DENY
+policy.add(policy.rpz(policy.DENY, 'blacklist.rpz'))

diff --git a/etc/config/config.isp.in b/etc/config/config.isp.in
index fed2f0ecdf6b53913e0fe49c76ecfc37edaa119d..d7b1e09392b4307b1b37f0239170e88f1ceff78c 100644 (file)
--- a/etc/config/config.isp.in
+++ b/etc/config/config.isp.in
@@ -1,40 +1,58 @@
 -- vim:syntax=lua:set ts=4 sw=4:
--- Config file example useable for multi-user ISP resolver
--- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/daemon.html#configuration
+-- Config file example usable for ISP resolver
+-- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/startguide.html#isp-resolver
 @config_defaults@
 
--- For DNS-over-HTTPS and web management when using http module
--- modules.load('http')
--- http.config({
---     cert = '/etc/knot-resolver/mycert.crt',
---     key = '/etc/knot-resolver/mykey.key',
---     tls = true,
--- })
-
--- To disable DNSSEC validation, uncomment the following line (not recommended)
--- trust_anchors.remove('.')
-
 -- Large cache size, so we don't need to flush often
 -- This can be larger than available RAM, least frequently accessed
 -- records will be paged out
 cache.size = 4 * GB
 
--- Load Useful modules
+-- load modules
 modules = {
-       'view',     -- Views for certain clients
-       'hints > iterate', -- Load /etc/hosts and allow custom root hints
-       'stats',    -- Track internal statistics
-       graphite = { -- Send statistics to local InfluxDB
-               -- `worker.id` allows us to keep per-fork statistics
-               prefix = hostname()..worker.id,
-               -- Address of the Graphite/InfluxDB server
-               host = '192.168.1.2',
-       },
+    'view',
+    'stats'
 }
 
--- Block all `site.nl` for `10.0.0.0/24` subnet
-view:addr('10.0.0.0/24', policy.suffix(policy.DROP, {todname('site.nl')}))
--- Force all clients from `192.168.2.0/24` to TCP
-view:addr('192.168.2.0/24', policy.all(policy.TC))
--- Apply RPZ for all clients, default rule is DENY
+-- log statistics every second
+local stat_id = event.recurrent(1 * second, function(evid)
+    log(table_print(stats.list()))
+end)
+
+-- stop printing statistics after first minute
+event.after(1 * minute, function(evid)
+        event.cancel(stat_id)
+end)
+
+-- make a closure, encapsulating counter
+function speed_monitor()
+        local previous = stats.list()
+        -- monitoring function
+        return function(evid)
+                local now = stats.list()
+                local total_increment = now['answer.total'] - previous['answer.total']
+                local slow_increment = now['answer.slow'] - previous['answer.slow']
+                if slow_increment / total_increment > 0.05 then
+                        log('WARNING! More than 5 %% of queries was slow!')
+                end
+                previous = now  -- store current value in closure
+         end
+end
+
+-- speed monitor every minute
+local monitor_id = event.recurrent(1 * minute, speed_monitor())
+
+-- apply RPZ for all clients, default rule is DENY
 policy.add(policy.rpz(policy.DENY, 'blacklist.rpz'))
+
+-- block local IPv4 clients (ACL like)
+view:addr('127.0.0.1', policy.all(policy.DENY))
+
+-- drop queries with suffix match for remote client
+view:addr('10.0.0.0/8', policy.suffix(policy.TC, policy.todnames({'example.com'})))
+
+-- force all clients from 192.168.2.0/24 to TCP
+view:addr('192.168.2.0/24', policy.all(policy.TC))
+
+-- whitelist queries identified by TSIG key
+view:tsig('\5mykey', policy.all(policy.PASS))

diff --git a/etc/config/config.privacy-preserving.in b/etc/config/config.privacy-preserving.in
new file mode 100644 (file)
index 0000000..f4b476e
--- /dev/null
+++ b/etc/config/config.privacy-preserving.in
@@ -0,0 +1,27 @@
+-- vim:syntax=lua:set ts=4 sw=4:
+-- Config file example usable for privacy-preserving resolver
+-- Refer to manual: https://knot-resolver.readthedocs.io/en/stable/startguide.html#personal-privacy-preserving-resolver
+@config_defaults@
+
+-- TLS server configuration
+-- Use this to configure your TLS certificates
+-- net.tls("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
+
+-- move cache to '/tmp/knot-resolver' tmpfs
+cache.storage = 'lmdb:///tmp/knot-resolver'
+
+-- forwarding to multiple targets
+policy.add(policy.slice(
+   policy.slice_randomize_psl(),
+   -- forward over TLS
+   policy.TLS_FORWARD({
+      {'2001:DB8::d0c', hostname='res.example.com'},
+      {'192.0.2.1', pin_sha256={'YQ=='}
+   }),
+   -- multiple servers can be specified for a single slice
+   -- the one with lowest round-trip time will be used
+   policy.TLS_FORWARD({
+      {'193.17.47.1', hostname='odvr.nic.cz'},
+      {'185.43.135.1', hostname='odvr.nic.cz'},
+   })
+))
\ No newline at end of file

diff --git a/etc/config/meson.build b/etc/config/meson.build
index 7e5723d7367b406e8c34ce82a2b1c72c2ba2e4b7..7c5eb60b125de647d605ee74cd2606ff2b4be763 100644 (file)
--- a/etc/config/meson.build
+++ b/etc/config/meson.build
@@ -27,6 +27,8 @@ example_configs = [
   'config.isp',
   'config.personal',
   'config.splitview',
+  'config.internal',
+  'config.privacy-preserving',
 ]
 
 conf_config = configuration_data()

diff --git a/modules/policy/README.rst b/modules/policy/README.rst
index 36d7cf90bb53159640c3b53191bd181d0883bdf0..86f00d37fcc5cc9c3c202b37bb3c4b2d858f8048 100644 (file)
--- a/modules/policy/README.rst
+++ b/modules/policy/README.rst
@@ -317,7 +317,7 @@ Most properties (actions, filters) are described above.
   :param action: action to be performed for the slice
 
   This function splits the entire domain space into multiple slices (determined
-  by the number of provided ``action``s) A ``slice_func`` is called to determine
+  by the number of provided ``actions``). A ``slice_func`` is called to determine
   which slice a query belongs to. The corresponding ``action`` is then executed.