1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
.. SPDX-License-Identifier: GPL-3.0-or-later
**********************
Configuration Overview
**********************
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`. [#]_
.. _config-syntax:
Syntax
======
The configuration file syntax allows you to specify different kinds of data:
- ``group.option = 123456``
- ``group.option = "string value"``
- ``group.command(123456, "string value")``
- ``group.command({ key1 = "value1", key2 = 222, key3 = "third value" })``
- ``globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)``
- ``-- any text after -- sign is ignored till end of line``
Following **configuration file snippet** starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.
.. code-block:: lua
-- this is a comment: listen for unencrypted queries
net.listen('192.0.2.1')
-- another comment: listen for queries encrypted using TLS on port 853
net.listen('192.0.2.1', 853, { kind = 'tls' })
-- 10 MB cache is suitable for a very small deployment
cache.size = 10 * MB
.. tip::
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.
When you modify configuration file on disk restart resolver process to get
changes into effect. See chapter :ref:`systemd-zero-downtime-restarts` if even short
outages are not acceptable for your deployment.
.. [#] If you decide to run binary ``/usr/sbin/kresd`` manually (instead of
using systemd) do not forget to specify ``-c`` option with path to
configuration file, otherwise ``kresd`` will read file named ``config`` from
its current working directory.
Documentation Conventions
=========================
Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter :ref:`runtime-cfg`. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.
The **interactive prompt** is denoted by ``>``, so all examples starting with ``>`` character are transcripts of user (or script) interaction with Knot Resolver and resolver's responses. For example:
.. code-block:: lua
> -- this is a comment entered into interactive prompt
> -- comments have no effect here
> -- the next line shows a command entered interactivelly and its output
> verbose()
false
> -- the previous line without > character is output from verbose() command
Following example demontrates how to interactivelly list all currently loaded modules, and includes multi-line output:
.. code-block:: lua
> modules.list()
[1] => iterate
[2] => validate
[3] => cache
Before we dive into configuring features, let us explain modularization basics.
.. include:: ../daemon/bindings/modules.rst
Now you know what configuration file to modify, how to read examples and what modules are so you are ready for a real configuration work!
.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
|
