.. _daemon:
-Daemon
-======
-
-The server is in the `daemon` directory, it works out of the box without any configuration.
-
-.. code-block:: bash
-
- $ kresd -v # run with defaults in verbose mode
- $ kresd -h # Get help
-
-If you're using our packages, they also provide systemd integration. To start the resolver under systemd, you can use the ``kresd@1.service`` service. By default, the resolver only binds to local interfaces.
-
-.. code-block:: bash
-
- $ man kresd.systemd # Help for systemd integration configuration
- $ systemctl start kresd@1.service
-
-
-Configuration
--------------
-
-.. contents::
- :depth: 2
- :local:
-
-In its simplest form the server requires just a working directory in which it can set up persistent files like
-cache and the process state. If you don't provide the working directory by parameter, it is going to make itself
-comfortable in the current working directory.
-
-.. code-block:: sh
-
- $ kresd /var/cache/knot-resolver
-
-And you're good to go for most use cases! If you want to use modules or configure daemon behavior, read on.
-
-There are several choices on how you can configure the daemon, a RPC interface, a CLI, and a configuration file.
-Fortunately all share common syntax and are transparent to each other.
-
-
-Configuration reference
------------------------
-
-This is a reference for variables and functions available to both configuration file and CLI.
-
-.. contents::
- :depth: 1
- :local:
-
-Environment
-^^^^^^^^^^^
-
-.. envvar:: env (table)
-
- Return environment variable.
-
- .. code-block:: lua
-
- env.USER -- equivalent to $USER in shell
-
-.. function:: hostname([fqdn])
-
- :return: Machine hostname.
-
- If called with a parameter, it will set kresd's internal
- hostname. If called without a parameter, it will return kresd's
- internal hostname, or the system's POSIX hostname (see
- gethostname(2)) if kresd's internal hostname is unset.
-
- This affects ephemeral certificates for kresd serving DNS over TLS.
+TODO: Environment
+=================
.. function:: verbose(true | false)
> user('root')
Operation not permitted
-.. function:: resolve(name, type[, class = kres.class.IN, options = {}, finish = nil, init = nil])
-
- :param string name: Query name (e.g. 'com.')
- :param number type: Query type (e.g. ``kres.type.NS``)
- :param number class: Query class *(optional)* (e.g. ``kres.class.IN``)
- :param strings options: Resolution options (see :c:type:`kr_qflags`)
- :param function finish: Callback to be executed when resolution completes (e.g. `function cb (pkt, req) end`). The callback gets a packet containing the final answer and doesn't have to return anything.
- :param function init: Callback to be executed with the :c:type:`kr_request` before resolution starts.
- :return: boolean
-
- The function can also be executed with a table of arguments instead. This is useful if you'd like to skip some arguments, for example:
-
- .. code-block:: lua
-
- resolve {
- name = 'example.com',
- type = kres.type.AAAA,
- init = function (req)
- end,
- }
-
- Example:
-
- .. code-block:: lua
-
- -- Send query for root DNSKEY, ignore cache
- resolve('.', kres.type.DNSKEY, kres.class.IN, 'NO_CACHE')
-
- -- Query for AAAA record
- resolve('example.com', kres.type.AAAA, kres.class.IN, 0,
- function (pkt, req)
- -- Check answer RCODE
- if pkt:rcode() == kres.rcode.NOERROR then
- -- Print matching records
- local records = pkt:section(kres.section.ANSWER)
- for i = 1, #records do
- local rr = records[i]
- if rr.type == kres.type.AAAA then
- print ('record:', kres.rr2str(rr))
- end
- end
- else
- print ('rcode: ', pkt:rcode())
- end
- end)
-
-.. function:: package_version()
-
- :return: Current package version.
-
- This returns current package version (the version of the binary) as a string.
-
- .. code-block:: lua
-
- > package_version()
- 2.1.1
-
-
-.. include:: ../daemon/bindings/modules.rst
-
-CLI interface
-=============
-
-The daemon features a CLI interface, type ``help()`` to see the list of available commands.
-
-.. code-block:: bash
-
- $ kresd /var/cache/knot-resolver
- [system] started in interactive mode, type 'help()'
- > cache.count()
- 53
-
-.. role:: lua(code)
- :language: lua
-
-Verbose output
---------------
-
-If the verbose logging is compiled in, i.e. not turned off by
-``verbose_log=disabled``, you can turn on verbose tracing of server operation
-with the ``-v`` option. You can also toggle it on runtime with
-``verbose(true|false)`` command.
-
-.. code-block:: bash
-
- $ kresd -v
-
-To run the daemon by hand, such as under ``nohup``, use ``-f 1`` to start a single fork. For example:
-
-.. code-block:: bash
- $ nohup ./daemon/kresd -a 127.0.0.1 -f 1 -v &
.. _`JSON-encoded`: http://json.org/example
.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
.. _`real process managers`: http://blog.crocodoc.com/post/48703468992/process-managers-the-good-the-bad-and-the-ugly
.. _`socket activation`: http://0pointer.de/blog/projects/socket-activation.html
.. _`dnsproxy module`: https://www.knot-dns.cz/docs/2.7/html/modules.html#dnsproxy-tiny-dns-proxy
-.. _`lua-http`: https://luarocks.org/modules/daurnimator/http
-Modules configuration
-^^^^^^^^^^^^^^^^^^^^^
+TODO: Modules configuration
+===========================
-The daemon provides an interface for dynamic loading of :ref:`daemon modules <modules-implemented>`.
+The daemon provides an interface for dynamic loading of daemon modules.
.. tip:: Use declarative interface for module loading.
In practice this means that you can forget about it and your favorite Linux
distribution will take care of it for you.
+Following functions allow to modify DNSSEC configuration *if you really have to*:
+
.. function:: trust_anchors.add_file(keyfile[, readonly = false])
Knot Resolver offers several ways to modify its configuration at run-time:
- Using control socket driven by an external system
- - Using Lua script embeded in Resolver's configuration file
+ - Using Lua program embeded in Resolver's configuration file
+
+Both ways can also be combined: For example the configuration file can contain a little Lua function which gathers statistics and returns them in JSON string. This can be used by an external system which uses control socket to call this user-defined function and to retrieve its results.
Control sockets
---------------
-Control socket acts like "an interactive configuration file" so all actions available in configuration file can be executed interactively using the control socket. One possible use-case is reconfiguring Resolver instances from another program, e.g. your maintenance script.
+Control socket acts like "an interactive configuration file" so all actions available in configuration file can be executed interactively using the control socket. One possible use-case is reconfiguring Resolver instances from another program, e.g. a maintenance script.
.. note::
> net.list() -- lists running network services
-The *direct output* of the CLI command is captured and sent over the socket, while also printed to the daemon standard outputs (for accountability). This gives you an immediate response on the outcome of your command.
+The *direct output* of commands sent over socket is captured and sent back, while also printed to the daemon standard outputs (in :func:`verbose` mode). This gives you an immediate response on the outcome of your command.
Error or debug logs aren't captured, but you can find them in the daemon standard outputs.
Control sockets are also a way to enumerate and test running instances, the list of sockets corresponds to the list
Lua scripts
-----------
-As it was mentioned in section :ref:`config-syntax`, Resolver's configuration file contains program in Lua programming language. This allows you to write dynamic rules and helps you to avoid repetitive templating that is unavoidable with static configuration. For example parts of configuration can depend on hostname of the machine:
+As it was mentioned in section :ref:`config-syntax`, Resolver's configuration file contains program in Lua programming language. This allows you to write dynamic rules and helps you to avoid repetitive templating that is unavoidable with static configuration. For example parts of configuration can depend on :func:`hostname` of the machine:
.. code-block:: lua
cache.open(cache_size, 'lmdb://' .. cache_path)
end
+Helper functions
+^^^^^^^^^^^^^^^^
+Following built-in functions are useful for scripting:
+
+.. envvar:: env (table)
+
+ Retrieve environment variables.
+
+ Example:
+
+ .. code-block:: lua
+
+ env.USER -- equivalent to $USER in shell
+
+.. function:: fromjson(JSONstring)
+
+ :return: Lua representation of data in JSON string.
+
+ Example:
+
+ .. code-block:: lua
+
+ > fromjson('{"key1": "value1", "key2": {"subkey1": 1, "subkey2": 2}}')
+ [key1] => value1
+ [key2] => {
+ [subkey1] => 1
+ [subkey2] => 2
+ }
+
+
+.. function:: hostname([fqdn])
+
+ :return: Machine hostname.
+
+ If called with a parameter, it will set kresd's internal
+ hostname. If called without a parameter, it will return kresd's
+ internal hostname, or the system's POSIX hostname (see
+ gethostname(2)) if kresd's internal hostname is unset.
+
+ This also affects ephemeral (self-signed) certificates generated by kresd
+ for DNS over TLS.
+
+.. function:: package_version()
+
+ :return: Current package version as string.
+
+ Example:
+
+ .. code-block:: lua
+
+ > package_version()
+ 2.1.1
+
+.. function:: resolve(name, type[, class = kres.class.IN, options = {}, finish = nil, init = nil])
+
+ :param string name: Query name (e.g. 'com.')
+ :param number type: Query type (e.g. ``kres.type.NS``)
+ :param number class: Query class *(optional)* (e.g. ``kres.class.IN``)
+ :param strings options: Resolution options (see :c:type:`kr_qflags`)
+ :param function finish: Callback to be executed when resolution completes (e.g. `function cb (pkt, req) end`). The callback gets a packet containing the final answer and doesn't have to return anything.
+ :param function init: Callback to be executed with the :c:type:`kr_request` before resolution starts.
+ :return: boolean, ``true`` if resolution was started
+
+ The function can also be executed with a table of arguments instead. This is useful if you'd like to skip some arguments, for example:
+
+ .. code-block:: lua
+
+ resolve {
+ name = 'example.com',
+ type = kres.type.AAAA,
+ init = function (req)
+ end,
+ }
+
+ Example:
+
+ .. code-block:: lua
+
+ -- Send query for root DNSKEY, ignore cache
+ resolve('.', kres.type.DNSKEY, kres.class.IN, 'NO_CACHE')
+
+ -- Query for AAAA record
+ resolve('example.com', kres.type.AAAA, kres.class.IN, 0,
+ function (pkt, req)
+ -- Check answer RCODE
+ if pkt:rcode() == kres.rcode.NOERROR then
+ -- Print matching records
+ local records = pkt:section(kres.section.ANSWER)
+ for i = 1, #records do
+ local rr = records[i]
+ if rr.type == kres.type.AAAA then
+ print ('record:', kres.rr2str(rr))
+ end
+ end
+ else
+ print ('rcode: ', pkt:rcode())
+ end
+ end)
+
+
+.. function:: tojson(object)
+
+ :return: JSON text representation of `object`.
+
+ Example:
+
+ .. code-block:: lua
+
+ > testtable = { key1 = "value1", "key2" = { subkey1 = 1, subkey2 = 2 } }
+ > tojson(testtable)
+ {"key1":"value1","key2":{"subkey1":1,"subkey2":2}}
+
+
.. _async-events:
Asynchronous events
.. include:: ../daemon/bindings/cache.rst
.. include:: ../daemon/lua/trust_anchors.rst
-.. include:: ../daemon/README.rst
-.. include:: ../daemon/scripting.rst
-
Multiple instances
==================
panic("Use kresd@dns*, kresd@tls* or kresd@doh* instance names")
end
+.. include:: ../daemon/README.rst
+.. include:: ../daemon/bindings/modules.rst
+
+Monitoring and diagnostics
+==========================
+.. contents::
+ :depth: 1
+ :local:
+.. include:: ../modules/nsid/README.rst
+.. include:: ../modules/graphite/README.rst
+.. include:: ../modules/dnstap/README.rst
+.. include:: ../modules/watchdog/README.rst
+.. include:: ../modules/bogus_log/README.rst
+.. include:: ../modules/ta_sentinel/README.rst
+.. include:: ../modules/ta_signal_query/README.rst
+.. include:: ../modules/detect_time_skew/README.rst
+.. include:: ../modules/detect_time_jump/README.rst
+
+Policy, access control, data manipulation
+=========================================
+.. include:: ../modules/hints/README.rst
+.. include:: ../modules/stats/README.rst
+.. include:: ../modules/policy/README.rst
+.. include:: ../modules/view/README.rst
+.. include:: ../modules/rebinding/README.rst
+.. include:: ../modules/refuse_nord/README.rst
+.. include:: ../modules/dns64/README.rst
+.. include:: ../modules/renumber/README.rst
+
+
+Performance and resiliency
+==========================
+.. include:: ../modules/predict/README.rst
+.. include:: ../modules/priming/README.rst
+.. include:: ../modules/rfc7706.rst
+.. include:: ../modules/prefill/README.rst
+.. include:: ../modules/serve_stale/README.rst
+.. include:: ../modules/workarounds/README.rst
+.. include:: ../modules/edns_keepalive/README.rst
+
+
+Other
+=====
+.. include:: ../modules/http/README.rst
+.. include:: ../modules/http/README.doh.rst
+.. include:: ../modules/daf/README.rst
+.. include:: ../modules/etcd/README.rst
+
+Experimental features
+=====================
+.. include:: ../modules/experimental_dot_auth/README.rst
+
+.. include:: ../daemon/scripting.rst
+
:maxdepth: 2
config
- modules
.. _operation:
+++ /dev/null
-.. _modules-implemented:
-
-*******
-Modules
-*******
-
-.. contents::
- :depth: 1
- :local:
-
-.. include:: ../modules/hints/README.rst
-.. include:: ../modules/stats/README.rst
-.. include:: ../modules/policy/README.rst
-.. include:: ../modules/view/README.rst
-.. include:: ../modules/predict/README.rst
-.. include:: ../modules/http/README.rst
-.. include:: ../modules/http/README.doh.rst
-.. include:: ../modules/daf/README.rst
-.. include:: ../modules/rebinding/README.rst
-.. include:: ../modules/graphite/README.rst
-.. include:: ../modules/etcd/README.rst
-.. include:: ../modules/dns64/README.rst
-.. include:: ../modules/renumber/README.rst
-.. .. include:: ../modules/cookies/README.rst
-.. include:: ../modules/bogus_log/README.rst
-.. include:: ../modules/nsid/README.rst
-.. include:: ../modules/workarounds/README.rst
-.. include:: ../modules/dnstap/README.rst
-.. include:: ../modules/ta_signal_query/README.rst
-.. include:: ../modules/ta_sentinel/README.rst
-.. include:: ../modules/priming/README.rst
-.. include:: ../modules/detect_time_skew/README.rst
-.. include:: ../modules/detect_time_jump/README.rst
-.. include:: ../modules/rfc7706.rst
-.. include:: ../modules/prefill/README.rst
-.. include:: ../modules/serve_stale/README.rst
-.. include:: ../modules/edns_keepalive/README.rst
-.. include:: ../modules/experimental_dot_auth/README.rst
-.. include:: ../modules/refuse_nord/README.rst
-.. include:: ../modules/watchdog/README.rst
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:
-- :ref:`Daemon configuration <daemon>`
-- :ref:`Modules configuration <modules-implemented>`
-
-
Listening on network interfaces
===============================
projects / thirdparty / knot-resolver.git / commitdiff
