Lua Scripting¶

Knot Resolver can be configured declaratively by using YAML configuration file. The actual worker processes (the kresd executable) speaks a different configuration language, it internally uses the Lua runtime.

Essentially, the declarative configuration is only used for validation and as an external interface. After validation, a Lua configuration is generated and passed into individual kresd workers.

You can see the generated configuration files within the resolver’s working directory or you can manualy run the conversion of declarative configuration with the kresctl convert command. In the declarative configuration there is a lua section where you can insert your own Lua configuration scripts.

Warning

While there are no plans of ever removing the Lua configuration, we do not guarantee absence of backwards incompatible changes. Starting with Knot Resolver version 6 and later, we consider the Lua interface internal and a subject to change. While we don’t have any breaking changes planned for the foreseeable future, they might come.

Therefore, use this only when you don’t have any other option. And please let us know about it and we might try to accomodate your usecase in the declarative configuration.

lua/script-only: true|false¶

Default: false

Ignore declarative configuration for kresd workers and use only Lua script or script file configured in this section.

lua/script: <script string>¶

Custom Lua configuration script.

lua:
  script: |
    -- Network interface configuration
    net.listen('127.0.0.1', 53, { kind = 'dns' })
    net.listen('::1', 53, { kind = 'dns', freebind = true })

    -- Load useful modules
    modules = {
        'hints > iterate',  -- Allow loading /etc/hosts or custom root hints
        'stats',            -- Track internal statistics
        'predict',          -- Prefetch expiring/frequent records
    }

    -- Cache size
    cache.size = 100 * MB

lua/script-file: <path>¶: Path to the file that contains Lua configuration script.

Note

The script is applied after the declarative configuration, so it can change the configuration defined in it.