From: Aleš Mrázek <ales.mrazek@nic.cz>
Date: Tue, 31 Jan 2023 14:04:54 +0000 (+0100)
Subject: doc: legacy chapter created
X-Git-Tag: v6.0.1~11^2~1^2~15
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=9ee51f3206b232f8407d5d68ed03e7572ad92c42;p=thirdparty%2Fknot-resolver.git

doc: legacy chapter created
---

diff --git a/doc/index.rst b/doc/index.rst
index 532f76f93..925f791d6 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,6 +19,12 @@ and it provides a state-machine like API for extensions.
    gettingstarted-startup
    gettingstarted-config
 
+.. toctree::
+   :caption: Legacy
+   :name: legacy-chapter
+   :maxdepth: 1
+
+   legacy
 
 .. toctree::
    :caption: Common Use Cases
diff --git a/doc/legacy.rst b/doc/legacy.rst
index cf2c6aa70..e6f31bfcc 100644
--- a/doc/legacy.rst
+++ b/doc/legacy.rst
@@ -1,26 +1,71 @@
-=====================
-Legacy daemon startup
-=====================
+.. SPDX-License-Identifier: GPL-3.0-or-later
 
-Legacy way to run single instance of Knot Resolver daemon is to use ``kresd@`` systemd integration:
+.. _legacy-approach:
+
+***************
+Legacy approach
+***************
+
+If you want to continue using Knot Resolver as before version ``6.0.0`` this is chapter for you.
+For new and less experienced users, we recommend using the newer approach starting in :ref:`Getting Started <gettingstarted-intro>` chapter.
+
+There are a few downsides to using the legacy approach that need to be mentioned.
+
+* configuration in Lua script
+* manual process management
+
+
+.. _legacy-startup:
+
+**************
+Daemon startup
+**************
+
+The legacy way to start Knot Resolver is to run single instance of its resolving daemon manualy using ``kresd@`` systemd integration.
+The daemon is single thread process.
 
 .. code-block:: bash
 
-   $ sudo systemctl start kresd@1.service
+    $ sudo systemctl start kresd@1.service
 
+.. tip::
 
-========================
-Legacy Lua configuration
-========================
+    For more information about Systemd integration see man kresd.systemd.
 
-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@``.
 
-.. note::
+.. _legacy-config:
+
+*****************
+Lua configuration
+*****************
+
+Legacy way to configure Knot Resolver is to paste your Lua code typically into ``/etc/knot-resolver/kresd.conf`` configuration script.
+The resolver's daemon is preconfigure to load this script when using ``kresd@`` systemd integration.
 
-    When copy&pasting examples from this manual please pay close
-    attention to brackets and also line ordering - order of lines matters.
+.. note::
 
     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 <http://tylerneylon.com/a/learn-lua/>`_ for a syntax overview.
\ No newline at end of file
+    `Learn Lua in 15 minutes <http://tylerneylon.com/a/learn-lua/>`_ for a syntax overview.
+
+The first thing you need to configure are the network interfaces to listen to.
+
+The following example instructs the 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``.
+
+.. code-block:: lua
+
+    -- unencrypted DNS on port 53 is default
+    net.listen('192.0.2.1')
+    net.listen('2001:db8::1')
+
+    net.listen(net.eth0, 853, { kind = 'tls' })
+
+
+Complete configurations files 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).
+
+.. note::
+
+    When copy&pasting examples please pay close
+    attention to brackets and also line ordering - order of lines matters.
\ No newline at end of file