README.rst 30.8 KB
Newer Older
1

2 3 4 5
************************
Knot DNS Resolver daemon 
************************

6
The server is in the `daemon` directory, it works out of the box without any configuration.
7

8
.. code-block:: bash
9

10 11
   $ kresd -h # Get help
   $ kresd -a ::1
12

13 14 15 16
Enabling DNSSEC
===============

The resolver supports DNSSEC including :rfc:`5011` automated DNSSEC TA updates and :rfc:`7646` negative trust anchors.
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
To enable it, you need to provide trusted root keys. Bootstrapping of the keys is automated, and kresd fetches root trust anchors set `over a secure channel <http://jpmens.net/2015/01/21/opendnssec-rfc-5011-bind-and-unbound/>`_ from IANA. From there, it can perform :rfc:`5011` automatic updates for you.

.. note:: Automatic bootstrap requires luasocket_ and luasec_ installed.

.. code-block:: bash

   $ kresd -k root.keys # File for root keys
   [ ta ] bootstrapped root anchor "19036 8 2 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5"
   [ ta ] warning: you SHOULD check the key manually, see: https://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html#sigs
   [ ta ] key: 19036 state: Valid
   [ ta ] next refresh: 86400000

Alternatively, you can set it in configuration file with ``trust_anchors.file = 'root.keys'``. If the file doesn't exist, it will be automatically populated with root keys validated using root anchors retrieved over HTTPS.

This is equivalent to `using unbound-anchor <https://www.unbound.net/documentation/howto_anchor.html>`_:

.. code-block:: bash

   $ unbound-anchor -a "root.keys" || echo "warning: check the key at this point"
   $ echo "auto-trust-anchor-file: \"root.keys\"" >> unbound.conf
   $ unbound -c unbound.conf

.. warning:: Bootstrapping of the root trust anchors is automatic, you are however **encouraged to check** the key over **secure channel**, as specified in `DNSSEC Trust Anchor Publication for the Root Zone <https://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html#sigs>`_. This is a critical step where the whole infrastructure may be compromised, you will be warned in the server log.

Manually providing root anchors
-------------------------------

Marek Vavrusa's avatar
Marek Vavrusa committed
44
The root anchors bootstrap may fail for various reasons, in this case you need to provide IANA or alternative root anchors. The format of the keyfile is the same as for Unbound or BIND and contains DS/DNSKEY records.
45 46

1. Check the current TA published on `IANA website <https://data.iana.org/root-anchors/root-anchors.xml>`_
Marek Vavruša's avatar
Marek Vavruša committed
47
2. Fetch current keys (DNSKEY), verify digests
48
3. Deploy them
49 50 51

.. code-block:: bash

Marek Vavrusa's avatar
Marek Vavrusa committed
52
   $ kdig DNSKEY . @k.root-servers.net +noall +answer | grep "DNSKEY[[:space:]]257" > root.keys
Marek Vavruša's avatar
Marek Vavruša committed
53
   $ ldns-key2ds -n root.keys # Only print to stdout
54 55 56 57
   ... verify that digest matches TA published by IANA ...
   $ kresd -k root.keys

You've just enabled DNSSEC!
58

59 60
CLI interface
=============
61

62
The daemon features a CLI interface, type ``help`` to see the list of available commands.
63 64 65

.. code-block:: bash

66 67 68 69
   $ kresd /var/run/knot-resolver
   [system] started in interactive mode, type 'help()'
   > cache.count()
   53
70 71 72 73

.. role:: lua(code)
   :language: lua

74 75 76 77 78 79 80 81 82 83 84 85
Verbose output
--------------

If the debug logging is compiled in, 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

Scaling out
===========
86 87

The server can clone itself into multiple processes upon startup, this enables you to scale it on multiple cores.
88 89
Multiple processes can serve different addresses, but still share the same working directory and cache.
You can add start and stop processes on runtime based on the load.
90 91 92

.. code-block:: bash

93
   $ kresd -f 4 rundir > kresd.log &
94 95 96 97 98 99 100 101 102 103 104 105
   $ kresd -f 2 rundir > kresd_2.log & # Extra instances
   $ pstree $$ -g
   bash(3533)─┬─kresd(19212)─┬─kresd(19212)
              │              ├─kresd(19212)
              │              └─kresd(19212)
              ├─kresd(19399)───kresd(19399)
              └─pstree(19411)
   $ kill 19399 # Kill group 2, former will continue to run
   bash(3533)─┬─kresd(19212)─┬─kresd(19212)
              │              ├─kresd(19212)
              │              └─kresd(19212)
              └─pstree(19460)  
106

107 108
.. _daemon-reuseport:

109 110
.. note:: On recent Linux supporting ``SO_REUSEPORT`` (since 3.9, backported to RHEL 2.6.32) it is also able to bind to the same endpoint and distribute the load between the forked processes. If the kernel doesn't support it, you can still fork multiple processes on different ports, and do load balancing externally (on firewall or with `dnsdist <http://dnsdist.org/>`_).

111
Notice the absence of an interactive CLI. You can attach to the the consoles for each process, they are in ``rundir/tty/PID``.
112 113 114 115 116 117 118

.. code-block:: bash

	$ nc -U rundir/tty/3008 # or socat - UNIX-CONNECT:rundir/tty/3008
	> cache.count()
	53

119 120 121
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.
Error or debug logs aren't captured, but you can find them in the daemon standard outputs.

122 123 124 125 126
This is also a way to enumerate and test running instances, the list of files int ``tty`` correspond to list
of running processes, and you can test the process for liveliness by connecting to the UNIX socket.

.. warning:: This is very basic way to orchestrate multi-core deployments and doesn't scale in multi-node clusters. Keep an eye on the prepared ``hive`` module that is going to automate everything from service discovery to deployment and consistent configuration.

127 128 129 130 131
Running supervised
==================

Knot Resolver can run under a supervisor to allow for graceful restarts, watchdog process and socket activation. This way the supervisor binds to sockets and lends them to resolver daemon. Thus if the resolver terminates or is killed, the sockets are still active and no queries are dropped.

Marek Vavrusa's avatar
Marek Vavrusa committed
132
The watchdog process must notify kresd about active file descriptors, and kresd will automatically determine the socket type and bound address, thus it will appear as any other address. There's a tiny supervisor script for convenience, but you should have a look at `real process managers`_.
133 134 135 136 137 138 139 140 141 142

.. code-block:: bash

   $ python scripts/supervisor.py ./daemon/kresd 127.0.0.1@53
   $ [system] interactive mode
   > quit()
   > [2016-03-28 16:06:36.795879] process finished, pid = 99342, status = 0, uptime = 0:00:01.720612
   [system] interactive mode
   >

Marek Vavrusa's avatar
Marek Vavrusa committed
143
The daemon also supports `systemd socket activation`_, it is automatically detected and requires no configuration on users's side.
144

145 146 147 148 149 150 151 152 153 154 155 156 157
Configuration
=============

.. contents::
   :depth: 2
   :local:

In it's simplest form it 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

158
	$ kresd /var/run/kresd
159 160 161

And you're good to go for most use cases! If you want to use modules or configure daemon behavior, read on.

162 163
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.
164 165 166 167 168

Configuration example
---------------------
.. code-block:: lua

169 170 171
   -- interfaces
   net = { '127.0.0.1', '::1' }
   -- load some modules
172
   modules = { 'policy' }
173 174
   -- 10MB cache
   cache.size = 10*MB
175

176 177
.. tip:: There are more configuration examples in `etc/` directory for personal, ISP, company internal and resolver cluster use cases.

178 179 180 181 182 183 184 185 186 187 188 189 190
Configuration syntax
--------------------

The configuration is kept in the ``config`` file in the daemon working directory, and it's going to get loaded automatically.
If there isn't one, the daemon is going to start with sane defaults, listening on `localhost`.
The syntax for options is like follows: ``group.option = value`` or ``group.action(parameters)``.
You can also comment using a ``--`` prefix.

A simple example would be to load static hints.

.. code-block:: lua

	modules = {
Marek Vavruša's avatar
Marek Vavruša committed
191
		'hints' -- no configuration
192 193
	}

194
If the module accepts configuration, you can call the ``module.config({...})`` or provide options table.
195 196 197 198 199 200
The syntax for table is ``{ key1 = value, key2 = value }``, and it represents the unpacked `JSON-encoded`_ string, that
the modules use as the :ref:`input configuration <mod-properties>`.

.. code-block:: lua

	modules = {
201
		hints = '/etc/hosts'
202 203
	}

204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
.. warning:: Modules specified including their configuration may not load exactly in the same order as specified.

Modules are inherently ordered by their declaration. Some modules are built-in, so it would be normally impossible to place for example *hints* before *rrcache*. You can enforce specific order by precedence operators **>** and **<**.

.. code-block:: lua

   modules = {
      'hints  > iterate', -- Hints AFTER iterate
      'policy > hints',   -- Policy AFTER hints
      'view   < rrcache'  -- View BEFORE rrcache
   }
   modules.list() -- Check module call order

This is useful if you're writing a module with a layer, that evaluates an answer before writing it into cache for example.

219 220 221 222 223 224 225 226 227 228
.. tip:: The configuration and CLI syntax is Lua language, with which you may already be familiar with.
         If not, you can read the `Learn Lua in 15 minutes`_ for a syntax overview. Spending just a few minutes
         will allow you to break from static configuration, write more efficient configuration with iteration, and
         leverage events and hooks. Lua is heavily used for scripting in applications ranging from embedded to game engines,
         but in DNS world notably in `PowerDNS Recursor`_. Knot DNS Resolver does not simply use Lua modules, but it is
         the heart of the daemon for everything from configuration, internal events and user interaction.

Dynamic configuration
^^^^^^^^^^^^^^^^^^^^^

229
Knowing that the the configuration is a Lua in disguise enables you to write dynamic rules. It also helps you to avoid repetitive templating that is unavoidable with static configuration.
230 231 232 233

.. code-block:: lua

	if hostname() == 'hidden' then
234
		net.listen(net.eth0, 5353)
235
	else
236
		net = { '127.0.0.1', net.eth1.addr[1] }
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261
	end

Another example would show how it is possible to bind to all interfaces, using iteration.

.. code-block:: lua

	for name, addr_list in pairs(net.interfaces()) do
		net.listen(addr_list)
	end

You can also use third-party packages (available for example through LuaRocks_) as on this example
to download cache from parent, to avoid cold-cache start.

.. code-block:: lua

	local http = require('socket.http')
	local ltn12 = require('ltn12')

	if cache.count() == 0 then
		-- download cache from parent
		http.request { 
			url = 'http://parent/cache.mdb',
			sink = ltn12.sink.file(io.open('cache.mdb', 'w'))
		}
		-- reopen cache with 100M limit
262
		cache.size = 100*MB
263 264 265 266 267
	end

Events and services
^^^^^^^^^^^^^^^^^^^

268 269 270
The Lua supports a concept called closures_, this is extremely useful for scripting actions upon various events,
say for example - prune the cache within minute after loading, publish statistics each 5 minutes and so on.
Here's an example of an anonymous function with :func:`event.recurrent()`:
271

272 273 274 275
.. code-block:: lua

	-- every 5 minutes
	event.recurrent(5 * minute, function()
276
		cache.prune()
277 278 279 280 281 282 283 284 285 286 287 288 289
	end)

Note that each scheduled event is identified by a number valid for the duration of the event,
you may cancel it at any time. You can do this with anonymous functions, if you accept the event
as a parameter, but it's not very useful as you don't have any *non-global* way to keep persistent variables.

.. code-block:: lua

	-- make a closure, encapsulating counter
	function pruner()
		local i = 0
		-- pruning function
		return function(e)
290
			cache.prune()
291 292 293 294 295 296 297 298 299 300
			-- cancel event on 5th attempt
			i = i + 1
			if i == 5 then
				event.cancel(e)
			fi
		end
	end

	-- make recurrent event that will cancel after 5 times
	event.recurrent(5 * minute, pruner())
301

302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
Another type of actionable event is activity on a file descriptor. This allows you to embed other
event loops or monitor open files and then fire a callback when an activity is detected.
This allows you to build persistent services like HTTP servers or monitoring probes that cooperate
well with the daemon internal operations.

For example a simple web server that doesn't block:

.. code-block:: lua

   local server, headers = require 'http.server', require 'http.headers'
   local cqueues = require 'cqueues'
   -- Start socket server
   local s = server.listen { host = 'localhost', port = 8080 }
   assert(s:listen())
   -- Compose per-request coroutine
   local cq = cqueues.new()
   cq:wrap(function()
      s:run(function(stream)
         -- Create response headers
         local headers = headers.new()
         headers:append(':status', '200')
         headers:append('connection', 'close')
         -- Send response and close connection
         assert(stream:write_headers(headers, false))
         assert(stream:write_chunk('OK', true))
         stream:shutdown()
         stream.connection:shutdown()
      end)
      s:close()
   end)
   -- Hook to socket watcher
   event.socket(cq:pollfd(), function (ev, status, events)
      cq:step(0)
   end)

337 338
* File watchers

339 340 341
.. note:: Work in progress, come back later!

.. _closures: http://www.lua.org/pil/6.1.html
342 343 344 345 346 347

Configuration reference
-----------------------

This is a reference for variables and functions available to both configuration file and CLI.

348 349 350 351
.. contents::
   :depth: 1
   :local:

352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
Environment
^^^^^^^^^^^

.. envvar:: env (table)

   Return environment variable.

   .. code-block:: lua

	env.USER -- equivalent to $USER in shell

.. function:: hostname()

   :return: Machine hostname.

367 368 369 370
.. function:: verbose(true | false)

   :return: Toggle verbose logging.

371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387
.. function:: mode('strict' | 'normal' | 'permissive')

   :return: Change resolver strictness checking level.

   By default, resolver runs in *normal* mode. There are possibly many small adjustments
   hidden behind the mode settings, but the main idea is that in *permissive* mode, the resolver
   tries to resolve a name with as few lookups as possible, while in *strict* mode it spends much
   more effort resolving and checking referral path. However, if majority of the traffic is covered
   by DNSSEC, some of the strict checking actions are counter-productive.

   .. csv-table::
    :header: "Action", "Modes"

    "Use mandatory glue", "strict, normal, permissive"
    "Use in-bailiwick glue", "normal, permissive"
    "Use any glue records", "permissive"

388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416
.. function:: user(name, [group])

   :param string name: user name
   :param string group: group name (optional)
   :return: boolean

   Drop privileges and run as given user (and group, if provided).

   .. tip:: Note that you should bind to required network addresses before changing user. At the same time, you should open the cache **AFTER** you change the user (so it remains accessible). A good practice is to divide configuration in two parts:

      .. code-block:: lua

         -- privileged
         net = { '127.0.0.1', '::1' }
         -- unprivileged
         cache.size = 100*MB
         trust_anchors.file = 'root.key'

   Example output:

   .. code-block:: lua

      > user('baduser')
      invalid user name
      > user('kresd', 'netgrp')
      true
      > user('root')
      Operation not permitted

417 418 419 420 421 422
.. function:: resolve(qname, qtype[, qclass = kres.class.IN, options = 0, callback = nil])

   :param string qname: Query name (e.g. 'com.')
   :param number qtype: Query type (e.g. ``kres.type.NS``)
   :param number qclass: Query class *(optional)* (e.g. ``kres.class.IN``)
   :param number options: Resolution options (see query flags)
423
   :param function callback: 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.
424 425 426 427 428 429 430 431 432 433 434
   :return: boolean

   Example:

   .. code-block:: lua

      -- Send query for root DNSKEY, ignore cache
      resolve('.', kres.type.DNSKEY, kres.class.IN, kres.query.NO_CACHE)

      -- Query for AAAA record
      resolve('example.com', kres.type.AAAA, kres.class.IN, 0,
435
      function (answer, req)
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450
         -- Check answer RCODE
         local pkt = kres.pkt_t(answer)
         if pkt:rcode() == kres.rcode.NOERROR then
            -- Print matching records
            local records = pkt:section(kres.section.ANSWER)
            for i = 1, #records do
               if rr.type == kres.type.AAAA then
                  print ('record:', kres.rr2str(rr))
               end
            end
         else
            print ('rcode: ', pkt:rcode())
         end
      end)

451 452 453
Network configuration
^^^^^^^^^^^^^^^^^^^^^

454 455 456 457 458 459
For when listening on ``localhost`` just doesn't cut it.

.. tip:: Use declarative interface for network.

         .. code-block:: lua

Marek Vavruša's avatar
Marek Vavruša committed
460
            net = { '127.0.0.1', net.eth0, net.eth1.addr[1] }
461 462
            net.ipv4 = false

Marek Vavruša's avatar
Marek Vavruša committed
463
.. envvar:: net.ipv6 = true|false
464 465 466 467 468

   :return: boolean (default: true)

   Enable/disable using IPv6 for recursion.

Marek Vavruša's avatar
Marek Vavruša committed
469
.. envvar:: net.ipv4 = true|false
470 471 472 473

   :return: boolean (default: true)

   Enable/disable using IPv4 for recursion.
474

475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542
.. function:: net.listen(address, [port = 53])

   :return: boolean

   Listen on address, port is optional.

.. function:: net.listen({address1, ...}, [port = 53])

   :return: boolean

   Listen on list of addresses.

.. function:: net.listen(interface, [port = 53])

   :return: boolean

   Listen on all addresses belonging to an interface.

   Example:

   .. code-block:: lua

	net.listen(net.eth0) -- listen on eth0

.. function:: net.close(address, [port = 53])

   :return: boolean

   Close opened address/port pair, noop if not listening.

.. function:: net.list()

   :return: Table of bound interfaces.

   Example output:

   .. code-block:: lua

	[127.0.0.1] => {
	    [port] => 53
	    [tcp] => true
	    [udp] => true
	}

.. function:: net.interfaces()

   :return: Table of available interfaces and their addresses.

   Example output:

   .. code-block:: lua

	[lo0] => {
	    [addr] => {
	        [1] => ::1
	        [2] => 127.0.0.1
	    }
	    [mac] => 00:00:00:00:00:00
	}
	[eth0] => {
	    [addr] => {
	        [1] => 192.168.0.1
	    }
	    [mac] => de:ad:be:ef:aa:bb
	}

   .. tip:: You can use ``net.<iface>`` as a shortcut for specific interface, e.g. ``net.eth0``

543 544 545 546 547 548 549 550 551 552 553 554 555
.. function:: net.bufsize([udp_bufsize])

   Get/set maximum EDNS payload available. Default is 1452 (the maximum unfragmented datagram size).
   You cannot set less than 1220 (minimum size for DNSSEC) or more than 65535 octets.

   Example output:

   .. code-block:: lua

	> net.bufsize(4096)
	> net.bufsize()
	4096

556 557 558 559 560 561 562 563 564 565 566 567
.. function:: net.tcp_pipeline([len])

   Get/set per-client TCP pipeline limit (number of outstanding queries that a single client connection can make in parallel). Default is 50.

   Example output:

   .. code-block:: lua

   > net.tcp_pipeline()
   50
   > net.tcp_pipeline(100)

568 569 570
Trust anchors and DNSSEC
^^^^^^^^^^^^^^^^^^^^^^^^

571 572 573 574
.. envvar:: trust_anchors.hold_down_time = 30 * day

   :return: int (default: 30 * day)

575
   Modify RFC5011 hold-down timer to given value. Example: ``30 * sec``
576 577 578 579 580 581 582

.. envvar:: trust_anchors.refresh_time = nil

   :return: int (default: nil)

   Modify RFC5011 refresh timer to given value (not set by default), this will force trust anchors
   to be updated every N seconds periodically instead of relying on RFC5011 logic and TTLs.
583
   Example: ``10 * sec``
584 585 586

.. envvar:: trust_anchors.keep_removed = 0

587
   :return: int (default: 0)
588 589 590 591

   How many ``Removed`` keys should be held in history (and key file) before being purged.
   Note: all ``Removed`` keys will be purged from key file after restarting the process.

592 593 594 595
.. function:: trust_anchors.config(keyfile)

   :param string keyfile: File containing DNSKEY records, should be writeable.

Marek Vavruša's avatar
Marek Vavruša committed
596
   You can use only DNSKEY records in managed mode. It is equivalent to CLI parameter ``-k <keyfile>`` or ``trust_anchors.file = keyfile``.
597 598 599 600 601

   Example output:

   .. code-block:: lua

Marek Vavruša's avatar
Marek Vavruša committed
602 603
      > trust_anchors.config('root.keys')
      [trust_anchors] key: 19036 state: Valid
604 605 606 607 608 609

.. function:: trust_anchors.set_insecure(nta_set)

   :param table nta_list: List of domain names (text format) representing NTAs.

   When you use a domain name as an NTA, DNSSEC validation will be turned off at/below these names.
Marek Vavruša's avatar
Marek Vavruša committed
610
   Each function call replaces the previous NTA set. You can find the current active set in ``trust_anchors.insecure`` variable.
611 612 613 614 615 616 617

   .. tip:: Use the `trust_anchors.negative = {}` alias for easier configuration.

   Example output:

   .. code-block:: lua

Marek Vavruša's avatar
Marek Vavruša committed
618 619 620 621
      > trust_anchors.negative = { 'bad.boy', 'example.com' }
      > trust_anchors.insecure
      [1] => bad.boy
      [2] => example.com
622

623 624
.. function:: trust_anchors.add(rr_string)

Marek Vavruša's avatar
Marek Vavruša committed
625
   :param string rr_string: DS/DNSKEY records in presentation format (e.g. ``. 3600 IN DS 19036 8 2 49AAC11...``)
626

Marek Vavruša's avatar
Marek Vavruša committed
627 628
   Inserts DS/DNSKEY record(s) into current keyset. These will not be managed or updated, use it only for testing
   or if you have a specific use case for not using a keyfile.
629 630 631 632 633

   Example output:

   .. code-block:: lua

Marek Vavruša's avatar
Marek Vavruša committed
634
      > trust_anchors.add('. 3600 IN DS 19036 8 2 49AAC11...')
635

636 637 638 639 640
Modules configuration
^^^^^^^^^^^^^^^^^^^^^

The daemon provides an interface for dynamic loading of :ref:`daemon modules <modules-implemented>`.

641
.. tip:: Use declarative interface for module loading.
642 643 644

         .. code-block:: lua

645 646 647
		modules = {
			hints = {file = '/etc/hosts'}
		}
648 649 650 651 652

         Equals to:

         .. code-block:: lua

Marek Vavruša's avatar
Marek Vavruša committed
653 654
		modules.load('hints')
		hints.config({file = '/etc/hosts'})
655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678


.. function:: modules.list()

   :return: List of loaded modules.

.. function:: modules.load(name)

   :param string name: Module name, e.g. "hints"
   :return: boolean

   Load a module by name.

.. function:: modules.unload(name)

   :param string name: Module name
   :return: boolean

   Unload a module by name.

Cache configuration
^^^^^^^^^^^^^^^^^^^

The cache in Knot DNS Resolver is persistent with LMDB backend, this means that the daemon doesn't lose
679 680
the cached data on restart or crash to avoid cold-starts. The cache may be reused between cache
daemons or manipulated from other processes, making for example synchronised load-balanced recursors possible.
681

682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701
.. envvar:: cache.size (number)

   Get/set the cache maximum size in bytes. Note that this is only a hint to the backend,
   which may or may not respect it. See :func:`cache.open()`.

   .. code-block:: lua

	print(cache.size)
	cache.size = 100 * MB -- equivalent to `cache.open(100 * MB)`

.. envvar:: cache.storage (string)

   Get or change the cache storage backend configuration, see :func:`cache.backends()` for
   more information. If the new storage configuration is invalid, it is not set.

   .. code-block:: lua

	print(cache.storage)
	cache.storage = 'lmdb://.'

702 703 704 705 706 707 708 709 710 711 712 713 714 715
.. function:: cache.backends()

   :return: map of backends

   The cache supports runtime-changeable backends, using the optional :rfc:`3986` URI, where the scheme
   represents backend protocol and the rest of the URI backend-specific configuration. By default, it
   is a ``lmdb`` backend in working directory, i.e. ``lmdb://``.

   Example output:

   .. code-block:: lua

   	[lmdb://] => true

716 717 718 719 720 721 722
.. function:: cache.stats()

   :return: table of cache counters

  The cache collects counters on various operations (hits, misses, transactions, ...). This function call returns a table of
  cache counters that can be used for calculating statistics.

723
.. function:: cache.open(max_size[, config_uri])
724 725 726 727 728 729 730 731 732

   :param number max_size: Maximum cache size in bytes.
   :return: boolean

   Open cache with size limit. The cache will be reopened if already open.
   Note that the max_size cannot be lowered, only increased due to how cache is implemented.

   .. tip:: Use ``kB, MB, GB`` constants as a multiplier, e.g. ``100*MB``.

733 734 735 736 737 738 739
   The cache supports runtime-changeable backends, see :func:`cache.backends()` for mor information and
   default. Refer to specific documentation of specific backends for configuration string syntax.

   - ``lmdb://``

   As of now it only allows you to change the cache directory, e.g. ``lmdb:///tmp/cachedir``.

740 741 742 743 744 745 746 747 748 749
.. function:: cache.count()

   :return: Number of entries in the cache.

.. function:: cache.close()

   :return: boolean

   Close the cache.

750
   .. note:: This may or may not clear the cache, depending on the used backend. See :func:`cache.clear()`. 
751

752 753 754 755 756 757 758 759 760 761 762
.. function:: cache.stats()

   Return table of statistics, note that this tracks all operations over cache, not just which
   queries were answered from cache or not.

   Example:

   .. code-block:: lua

	print('Insertions:', cache.stats().insert)

763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812

.. function:: cache.prune([max_count])

  :param number max_count:  maximum number of items to be pruned at once (default: 65536)
  :return: ``{ pruned: int }``

  Prune expired/invalid records.

.. function:: cache.get([domain])

  :return: list of matching records in cache

  Fetches matching records from cache. The **domain** can either be:

  - a domain name (e.g. ``"domain.cz"``)
  - a wildcard (e.g. ``"*.domain.cz"``)

  The domain name fetches all records matching this name, while the wildcard matches all records at or below that name.

  You can also use a special namespace ``"P"`` to purge NODATA/NXDOMAIN matching this name (e.g. ``"domain.cz P"``).

  .. note:: This is equivalent to ``cache['domain']`` getter.

  Examples:

  .. code-block:: lua

     -- Query cache for 'domain.cz'
     cache['domain.cz']
     -- Query cache for all records at/below 'insecure.net'
     cache['*.insecure.net']

.. function:: cache.clear([domain])

  :return: ``bool``

  Purge cache records. If the domain isn't provided, whole cache is purged. See *cache.get()* documentation for subtree matching policy.

  Examples:

  .. code-block:: lua

   -- Clear records at/below 'bad.cz'
   cache.clear('*.bad.cz')
   -- Clear packet cache
   cache.clear('*. P')
   -- Clear whole cache
   cache.clear()


813 814 815
Timers and events
^^^^^^^^^^^^^^^^^

816 817 818 819
The timer represents exactly the thing described in the examples - it allows you to execute closures 
after specified time, or event recurrent events. Time is always described in milliseconds,
but there are convenient variables that you can use - ``sec, minute, hour``.
For example, ``5 * hour`` represents five hours, or 5*60*60*100 milliseconds.
820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849

.. function:: event.after(time, function)

   :return: event id

   Execute function after the specified time has passed.
   The first parameter of the callback is the event itself.

   Example:

   .. code-block:: lua

	event.after(1 * minute, function() print('Hi!') end)

.. function:: event.recurrent(interval, function)

   :return: event id

   Similar to :func:`event.after()`, periodically execute function after ``interval`` passes. 

   Example:

   .. code-block:: lua

	msg_count = 0
	event.recurrent(5 * sec, function(e) 
		msg_count = msg_count + 1
		print('Hi #'..msg_count)
	end)

850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867
.. function:: event.reschedule(event_id, timeout)

   Reschedule a running event, it has no effect on canceled events.
   New events may reuse the event_id, so the behaviour is undefined if the function
   is called after another event is started.

   Example:

   .. code-block:: lua

   local interval = 1 * minute
   event.after(1 * minute, function (ev)
      print('Good morning!')
      -- Halven the interval for each iteration
      interval = interval / 2
      event.reschedule(ev, interval)
   end)

868 869 870 871 872 873 874 875 876 877 878 879 880
.. function:: event.cancel(event_id)

   Cancel running event, it has no effect on already canceled events.
   New events may reuse the event_id, so the behaviour is undefined if the function
   is called after another event is started.

   Example:

   .. code-block:: lua

	e = event.after(1 * minute, function() print('Hi!') end)
	event.cancel(e)

881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902
Watch for file descriptor activity. This allows embedding other event loops or simply
firing events when a pipe endpoint becomes active. In another words, asynchronous
notifications for daemon.

.. function:: event.socket(fd, cb)

   :param number fd: file descriptor to watch
   :param cb: closure or callback to execute when fd becomes active
   :return: event id

   Execute function when there is activity on the file descriptor and calls a closure
   with event id as the first parameter, status as second and number of events as third.

   Example:

   .. code-block:: lua

   e = event.socket(0, function(e, status, nevents)
      print('activity detected')
   end)
   e.cancel(e)

903 904 905 906
Scripting worker
^^^^^^^^^^^^^^^^

Worker is a service over event loop that tracks and schedules outstanding queries,
907 908 909 910 911 912 913 914 915 916
you can see the statistics or schedule new queries. It also contains information about
specified worker count and process rank.

.. envvar:: worker.count

   Return current total worker count (e.g. `1` for single-process)

.. envvar:: worker.id

   Return current worker ID (starting from `0` up to `worker.count - 1`)
917 918 919 920 921

.. function:: worker.stats()

   Return table of statistics.

922 923
   * ``udp`` - number of outbound queries over UDP
   * ``tcp`` - number of outbound queries over TCP
924 925
   * ``ipv6`` - number of outbound queries over IPv6
   * ``ipv4`` - number of outbound queries over IPv4
926
   * ``timeout`` - number of timeouted outbound queries
927
   * ``concurrent`` - number of concurrent queries at the moment
928 929
   * ``queries`` - number of inbound queries
   * ``dropped`` - number of dropped inbound queries
930

931 932 933 934 935 936
   Example:

   .. code-block:: lua

	print(worker.stats().concurrent)

937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970
Using CLI tools
===============

* ``kresd-host.lua`` - a drop-in replacement for *host(1)* utility

Queries the DNS for information.
The hostname is looked up for IP4, IP6 and mail.

Example:

.. code-block:: bash

	$ kresd-host.lua -f root.key -v nic.cz
	nic.cz. has address 217.31.205.50 (secure)
	nic.cz. has IPv6 address 2001:1488:0:3::2 (secure)
	nic.cz. mail is handled by 10 mail.nic.cz. (secure)
	nic.cz. mail is handled by 20 mx.nic.cz. (secure)
	nic.cz. mail is handled by 30 bh.nic.cz. (secure)

* ``kresd-query.lua`` - run the daemon in zero-configuration mode, perform a query and execute given callback.

This is useful for executing one-shot queries and hooking into the processing of the result,
for example to check if a domain is managed by a certain registrar or if it's signed.

Example:

.. code-block:: bash

	$ kresd-query.lua www.sub.nic.cz 'assert(kres.dname2str(req:resolved().zone_cut.name) == "nic.cz.")' && echo "yes"
	yes
	$ kresd-query.lua -C 'trust_anchors.config("root.keys")' nic.cz 'assert(req:resolved():hasflag(kres.query.DNSSEC_WANT))'
	$ echo $?
	0

971 972 973 974 975 976
.. _`JSON-encoded`: http://json.org/example
.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/scripting/
.. _LuaRocks: https://rocks.moonscript.org/
.. _libuv: https://github.com/libuv/libuv
.. _Lua: http://www.lua.org/about.html
977 978
.. _LuaJIT: http://luajit.org/luajit.html
.. _luasec: https://luarocks.org/modules/luarocks/luasec
Marek Vavrusa's avatar
Marek Vavrusa committed
979
.. _luasocket: https://luarocks.org/modules/luarocks/luasocket
Marek Vavrusa's avatar
Marek Vavrusa committed
980 981
.. _`real process managers`: http://blog.crocodoc.com/post/48703468992/process-managers-the-good-the-bad-and-the-ugly
.. _`systemd socket activation`: http://0pointer.de/blog/projects/socket-activation.html