From: Aleš Mrázek Date: Tue, 9 Aug 2022 08:36:41 +0000 (+0200) Subject: doc: gettingstarted update X-Git-Tag: v6.0.0a1~26^2~5 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=70595b7d971be50c35359a2a127853aca460d00f;p=thirdparty%2Fknot-resolver.git doc: gettingstarted update --- diff --git a/doc/gettingstarted-config.rst b/doc/gettingstarted-config.rst index 47cceecb2..4a6312336 100644 --- a/doc/gettingstarted-config.rst +++ b/doc/gettingstarted-config.rst @@ -10,12 +10,17 @@ Configuration :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 `_. +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 `_. 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``. @@ -30,6 +35,7 @@ When using this configuration approach, the daemon must be started using legacy of this programming language. See article `Learn Lua in 15 minutes`_ for a syntax overview. +=============================== Listening on network interfaces =============================== @@ -66,230 +72,4 @@ Encrypted DNS queries are accepted using DNS-over-TLS protocol on all IP address 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 ` which combines query source information with :ref:`policy rules `. -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 `: - - .. 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 `_, `the article itself `_) - - `Bert Hubert. 2019. 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 ` 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 `, 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 - -

Next steps

- -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 diff --git a/doc/gettingstarted-install.rst b/doc/gettingstarted-install.rst index fdd70e049..7d64b3fe8 100644 --- a/doc/gettingstarted-install.rst +++ b/doc/gettingstarted-install.rst @@ -1,31 +1,5 @@ .. 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: ************ @@ -36,40 +10,30 @@ As a first step, configure your system to use upstream repositories which have 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 `_ package repository `home:CZ-NIC:knot-resolver-latest `_ to your system. +Add the `OBS `_ package repository `home:CZ-NIC:knot-resolver-latest `_ to your system. diff --git a/doc/gettingstarted-intro.rst b/doc/gettingstarted-intro.rst index c730755c2..d3a5dcf30 100644 --- a/doc/gettingstarted-intro.rst +++ b/doc/gettingstarted-intro.rst @@ -1,5 +1,9 @@ .. SPDX-License-Identifier: GPL-3.0-or-later +.. _gettingstarted: + +Getting Started chapter introduces Knot Resolver and guide you through installation and basic setup recommended for your use-case. + .. _gettingstarted-intro: ************