:ref:`systemd-multiple-instances`.
When Knot Resolver is started using Systemd (see section
-:ref:`quickstart-startup`) it creates a control socket in path
+:ref:`gettingstarted-startup`) it creates a control socket in path
``/run/knot-resolver/control/$ID``. Connection to the socket can
be made from command line using e.g. ``socat``:
Configuration file is named ``/etc/knot-resolver/kresd.conf`` and is read when
you execute Knot Resolver using systemd commands described in section
-:ref:`quickstart-startup`. [#]_
+:ref:`gettingstarted-startup`. [#]_
.. _config-syntax:
.. SPDX-License-Identifier: GPL-3.0-or-later
-.. _quickstart-config:
+.. _gettingstarted-config:
*************
Configuration
:depth: 1
:local:
-.. note::
+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>`_.
+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.
- When copy&pasting examples from this manual please pay close
- attention to brackets and also line ordering - order of lines matters.
+Legacy Lua configuration
+========================
- The configuration language is in fact Lua script, so you can use full power
- of this programming language. See article
- `Learn Lua in 15 minutes`_ for a syntax overview.
+Legacy way to configure Knot Resolver daemon is to paste your configuration into configuration file ``/etc/knot-resolver/kresd.conf``.
+When using this configuration approach, the daemon must be started using legacy systemd service ``kresd@``.
-Easiest way to configure Knot Resolver is to paste your configuration into
-configuration file ``/etc/knot-resolver/kresd.conf``.
-Complete configurations files for examples in this chapter
-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 of daemon and implemented modules can be found in configuration reference:
+.. note::
+
+ When copy&pasting examples from this manual please pay close
+ attention to brackets and also line ordering - order of lines matters.
+ The configuration language is in fact Lua script, so you can use full power
+ of this programming language. See article
+ `Learn Lua in 15 minutes`_ for a syntax overview.
Listening on network interfaces
===============================
-The following configuration instructs Knot Resolver to receive standard unencrypted DNS queries on IP addresses `192.0.2.1` and `2001:db8::1`. Encrypted DNS queries are accepted using DNS-over-TLS protocol on all IP addresses configured on network interface `eth0`, TCP port 853.
+The following configuration instructs Knot Resolver to receive standard unencrypted DNS queries on IP addresses `192.0.2.1` and `2001:db8::1`.
+Encrypted DNS queries are accepted using DNS-over-TLS protocol on all IP addresses configured on network interface `eth0`, TCP port 853.
.. tabs::
.. 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|
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. Once the certificate was obtained a path to certificate files can be specified using function :func:`net.tls()`:
+Second step is then obtaining and configuring your own TLS certificates signed by a trusted CA.
.. tabs::
.. 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. This can be achieved using following :ref:`policy rule <mod-policy>`:
+Some jurisdictions mandate blocking access to certain domains.
.. tabs::
.. 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.'})))
+ policy.suffix(policy.DENY,
+ policy.todnames({'example.com.', 'blocked.example.net.'})))
.. _personalresolver:
--- /dev/null
+.. 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:
+
+************
+Installation
+************
+
+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.
+
+ .. 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+
+
+ .. code-block:: bash
+
+ $ sudo yum install -y epel-release
+ $ sudo yum install -y knot-resolver
+
+ .. tab:: Fedora
+
+ .. code-block:: bash
+
+ $ sudo dnf install -y knot-resolver
+
+ .. tab:: Arch Linux
+
+ .. code-block:: bash
+
+ $ sudo pacman -S knot-resolver
+
+ .. tab:: 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.
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _gettingstarted-intro:
+
+************
+Introduction
+************
.. SPDX-License-Identifier: GPL-3.0-or-later
-.. _quickstart-startup:
+.. _gettingstarted-startup:
*******
Startup
*******
-The simplest way to run single instance of
-Knot Resolver is to use provided Knot Resolver's Systemd integration:
+The simplest way to run Knot Resolver is to use provided Knot Resolver's systemd integration:
.. code-block:: bash
- $ sudo systemctl start kresd@1.service
+ $ sudo systemctl start knot-resolver.service
-See logs and status of running instance with ``systemctl status kresd@1.service`` command. For more information about Systemd integration see ``man kresd.systemd``.
+See logs and status of running instance with ``systemctl status knot-resolver.service`` command. For more information about systemd integration see ``man knot-resolver.systemd``.
.. warning::
- ``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``
+ ``knot-resolver.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 knot-resolver.service``
+
+Legacy daemon startup
+=====================
+
+Legacy way to run single instance of Knot Resolver daemon is to use ``kresd@`` systemd integration:
+
+.. code-block:: bash
+
+ $ sudo systemctl start kresd@1.service
First DNS query
===============
and it provides a state-machine like API for extensions.
.. toctree::
- :caption: Quick Start
- :name: quickstart
+ :caption: Getting Started
+ :name: gettingstarted
:maxdepth: 1
- quickstart-install
- quickstart-startup
- quickstart-config
+ gettingstarted-intro
+ gettingstarted-install
+ gettingstarted-startup
+ gettingstarted-config
.. _configuration-chapter:
+++ /dev/null
-.. 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')
-
-
-.. _quickstart-install:
-
-************
-Installation
-************
-
-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.
-
-**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.
-
-.. 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
-
-**CentOS 7+**
-
-.. code-block:: bash
-
- $ sudo yum install -y epel-release
- $ sudo yum install -y knot-resolver
-
-**Fedora**
-
-.. code-block:: bash
-
- $ sudo dnf install -y knot-resolver
-
-**Arch Linux**
-
-.. code-block:: bash
-
- $ sudo pacman -S knot-resolver
-
-
-**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.
projects / thirdparty / knot-resolver.git / commitdiff
