:depth: 1
:local:
-Easiest way to configure Knot Resolver is to paste your configuration into YAML configuration file ``/etc/knot-resolver/config.yml``.
-Complete configurations files for examples in this chapter can be found `here <https://gitlab.nic.cz/knot/knot-resolver/tree/master/etc/config>`_.
+Easiest way to configure Knot Resolver is to paste your configuration into YAML file ``/etc/knot-resolver/config.yml``.
+Complete configurations files for examples can be found `here <https://gitlab.nic.cz/knot/knot-resolver/tree/master/etc/config>`_.
The example configuration files are also installed as documentation files, typically in directory ``/usr/share/doc/knot-resolver/examples/`` (their location may be different based on your Linux distribution).
-Detailed configuration can be found in configuration section.
-Legacy Lua configuration
+==============================
+Lua configuration in YAML file
+==============================
+
+
+========================
+Lua legacy configuration
========================
Legacy way to configure Knot Resolver daemon is to paste your configuration into configuration file ``/etc/knot-resolver/kresd.conf``.
of this programming language. See article
`Learn Lua in 15 minutes`_ for a syntax overview.
+===============================
Listening on network interfaces
===============================
Knot Resolver could answer from different IP addresses if the network address ranges
overlap, and clients would refuse such a response.
-
-Scenario: Internal Resolver
-===========================
-
-This is an example of typical configuration for company-internal resolver which is not accessible from outside of company network.
-
-Internal-only domains
-^^^^^^^^^^^^^^^^^^^^^
-
-An internal-only domain is a domain not accessible from the public Internet.
-In order to resolve internal-only domains a query policy has to be added to forward queries to a correct internal server.
-This configuration will forward two listed domains to a DNS server with IP address ``192.0.2.44``.
-
-.. tabs::
-
- .. group-tab:: |yaml|
-
- .. code-block:: yaml
-
-
- .. group-tab:: |lua|
-
- .. code-block:: lua
-
- -- define list of internal-only domains
- internalDomains = policy.todnames({'company.example', 'internal.example'})
-
- -- forward all queries belonging to domains in the list above to IP address '192.0.2.44'
- policy.add(policy.suffix(policy.FLAGS({'NO_CACHE'}), internalDomains))
- policy.add(policy.suffix(policy.STUB({'192.0.2.44'}), internalDomains))
-
-
-See chapter :ref:`dns-graft` for more details.
-
-
-.. _ispresolver:
-
-Scenario: ISP Resolver
-======================
-
-The following configuration is typical for Internet Service Providers who offer DNS resolver
-service to their own clients in their own network. Please note that running a *public DNS resolver*
-is more complicated and not covered by this quick start guide.
-
-Limiting client access
-^^^^^^^^^^^^^^^^^^^^^^
-With exception of public resolvers, a DNS resolver should resolve only queries sent by clients in its own network. This restriction limits attack surface on the resolver itself and also for the rest of the Internet.
-
-In a situation where access to DNS resolver is not limited using IP firewall, you can implement access restrictions using the :ref:`view module <mod-view>` which combines query source information with :ref:`policy rules <mod-policy>`.
-Following configuration allows only queries from clients in subnet 192.0.2.0/24 and refuses all the rest.
-
-.. tabs::
-
- .. group-tab:: |yaml|
-
- .. code-block:: yaml
-
-
- .. group-tab:: |lua|
-
- .. code-block:: lua
-
- modules.load('view')
-
- -- whitelist queries identified by subnet
- view:addr('192.0.2.0/24', policy.all(policy.PASS))
-
- -- drop everything that hasn't matched
- view:addr('0.0.0.0/0', policy.all(policy.DROP))
-
-TLS server configuration
-^^^^^^^^^^^^^^^^^^^^^^^^
-Today clients are demanding secure transport for DNS queries between client machine and DNS resolver. The recommended way to achieve this is to start DNS-over-TLS server and accept also encrypted queries.
-
-First step is to enable TLS on listening interfaces:
-
-.. tabs::
-
- .. group-tab:: |yaml|
-
- .. code-block:: yaml
-
- network:
- listen:
- - interface: ['192.0.2.1', '2001::db8:1']
- kind: 'dot' # dns-over-tls, default port is 853
-
-
- .. group-tab:: |lua|
-
- .. code-block:: lua
-
- net.listen('192.0.2.1', 853, { kind = 'tls' })
- net.listen('2001::db8:1', 853, { kind = 'tls' })
-
-By default a self-signed certificate is generated.
-Second step is then obtaining and configuring your own TLS certificates signed by a trusted CA.
-
-.. tabs::
-
- .. group-tab:: |yaml|
-
- .. code-block:: yaml
-
- network:
- tls:
- cert-file: '/etc/knot-resolver/server-cert.pem'
- key-file: '/etc/knot-resolver/server-key.pem'
-
- .. group-tab:: |lua|
-
- Once the certificate was obtained a path to certificate files can be specified using function :func:`net.tls()`:
-
- .. code-block:: lua
-
- net.tls("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
-
-
-Mandatory domain blocking
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Some jurisdictions mandate blocking access to certain domains.
-
-
-.. tabs::
-
- .. group-tab:: |yaml|
-
- .. code-block:: yaml
-
-
- .. group-tab:: |lua|
-
- Blocking can be achieved using following :ref:`policy rule <mod-policy>`:
-
- .. code-block:: lua
-
- policy.add(
- policy.suffix(policy.DENY,
- policy.todnames({'example.com.', 'blocked.example.net.'})))
-
-
-.. _personalresolver:
-
-Scenario: Personal Resolver
-===========================
-
-DNS queries can be used to gather data about user behavior.
-Knot Resolver can be configured to forward DNS queries elsewhere,
-and to protect them from eavesdropping by TLS encryption.
-
-.. warning::
-
- Latest research has proven that encrypting DNS traffic is not sufficient to protect privacy of users.
- For this reason we recommend all users to use full VPN instead of encrypting *just* DNS queries.
- Following configuration is provided **only for users who cannot encrypt all their traffic**.
- For more information please see following articles:
-
- - Simran Patil and Nikita Borisov. 2019. What can you learn from an IP? (`slides <https://irtf.org/anrw/2019/slides-anrw19-final44.pdf>`_, `the article itself <https://dl.acm.org/authorize?N687437>`_)
- - `Bert Hubert. 2019. Centralised DoH is bad for Privacy, in 2019 and beyond <https://labs.ripe.net/Members/bert_hubert/centralised-doh-is-bad-for-privacy-in-2019-and-beyond>`_
-
-
-Forwarding over TLS protocol (DNS-over-TLS)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Forwarding over TLS protocol protects DNS queries sent out by resolver.
-It can be configured using :ref:`policy.TLS_FORWARD <tls-forwarding>` function which provides methods for authentication.
-See list of `DNS Privacy Test Servers`_ supporting DNS-over-TLS to test your configuration.
-
-Read more on :ref:`tls-forwarding`.
-
-
-Forwarding to multiple targets
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-With the use of :any:`policy.slice` function, it is possible to split the
-entire DNS namespace into distinct "slices". When used in conjunction with
-:ref:`policy.TLS_FORWARD <tls-forwarding>`, it's possible to forward different queries to different
-remote resolvers. As a result no single remote resolver will get complete list
-of all queries performed by this client.
-
-.. warning::
-
- Beware that this method has not been scientifically tested and there might be
- types of attacks which will allow remote resolvers to infer more information about the client.
- Again: If possible encrypt **all** your traffic and not just DNS queries!
-
-.. tabs::
-
- .. group-tab:: |yaml|
-
- .. code-block:: yaml
-
-
- .. group-tab:: |lua|
-
- .. code-block:: lua
-
- policy.add(policy.slice(
- policy.slice_randomize_psl(),
- policy.TLS_FORWARD({{'192.0.2.1', hostname='res.example.com'}}),
- policy.TLS_FORWARD({
- -- multiple servers can be specified for a single slice
- -- the one with lowest round-trip time will be used
- {'193.17.47.1', hostname='odvr.nic.cz'},
- {'185.43.135.1', hostname='odvr.nic.cz'},
- })
- ))
-
-Non-persistent cache
-^^^^^^^^^^^^^^^^^^^^
-Knot Resolver's cache contains data clients queried for.
-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_.
-See chapter :ref:`cache_persistence`.
-
-
-.. raw:: html
-
- <h2>Next steps</h2>
-
-Congratulations! Your resolver is now up and running and ready for queries. For
-serious deployments do not forget to read :ref:`configuration-chapter` and
-:ref:`operation-chapter` chapters.
-
.. _`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
-.. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs
.. SPDX-License-Identifier: GPL-3.0-or-later
-.. _quickstart-intro:
-
-Welcome to Knot Resolver Quick Start Guide! This chapter will guide you through first installation and basic setup recommended for your use-case.
-
-Before we start let us explain basic conventions used in this text:
-
-This is Linux/Unix shell command to be executed and an output from this command:
-
-.. code-block:: bash
-
- $ echo "This is output!"
- This is output!
- $ echo "We use sudo to execute commands as root:"
- We use sudo to execute commands as root:
- $ sudo id
- uid=0(root) gid=0(root) groups=0(root)
-
-Snippets from Knot Resolver's configuration file **do not start with $ sign** and look like this:
-
-.. code-block:: lua
-
- -- this is a comment
- -- following line will start listening on IP address 192.0.2.1 port 53
- net.listen('192.0.2.1')
-
-
.. _gettingstarted-install:
************
the **latest version** of Knot Resolver. Follow the instructions below for your
distribution.
-.. tabs::
-
- .. tab:: Debian/Ubuntu
+.. note:: Please note that the packages available in distribution repositories of Debian and Ubuntu are outdated. Make sure to follow these steps to use our upstream repositories.
- .. note:: Please note that the packages available in distribution repositories
- of Debian and Ubuntu are outdated. Make sure to follow these steps to use
- our upstream repositories.
-
- .. code-block:: bash
-
- $ wget https://secure.nic.cz/files/knot-resolver/knot-resolver-release.deb
- $ sudo dpkg -i knot-resolver-release.deb
- $ sudo apt update
- $ sudo apt install -y knot-resolver
-
- .. tab:: CentOS 7+
+.. tabs::
- .. code-block:: bash
+ .. code-tab:: bash Debian/Ubuntu
- $ sudo yum install -y epel-release
- $ sudo yum install -y knot-resolver
+ $ wget https://secure.nic.cz/files/knot-resolver/knot-resolver-release.deb
+ $ sudo dpkg -i knot-resolver-release.deb
+ $ sudo apt update
+ $ sudo apt install -y knot-resolver
- .. tab:: Fedora
+ .. code-tab:: bash CentOS 7+
- .. code-block:: bash
+ $ sudo yum install -y epel-release
+ $ sudo yum install -y knot-resolver
- $ sudo dnf install -y knot-resolver
+ .. code-tab:: bash Fedora
- .. tab:: Arch Linux
+ $ sudo dnf install -y knot-resolver
- .. code-block:: bash
+ .. code-tab:: bash Arch Linux
- $ sudo pacman -S knot-resolver
+ $ sudo pacman -S knot-resolver
- .. tab:: openSUSE Leap/Tumbleweed
+**openSUSE Leap/Tumbleweed**
- Add the `OBS <https://en.opensuse.org/Portal:Build_Service>`_ package repository `home:CZ-NIC:knot-resolver-latest <https://software.opensuse.org/download.html?project=home%3ACZ-NIC%3Aknot-resolver-latest&package=knot-resolver>`_ to your system.
+Add the `OBS <https://en.opensuse.org/Portal:Build_Service>`_ package repository `home:CZ-NIC:knot-resolver-latest <https://software.opensuse.org/download.html?project=home%3ACZ-NIC%3Aknot-resolver-latest&package=knot-resolver>`_ to your system.
projects / thirdparty / knot-resolver.git / commitdiff
