Commit b2aa4558 authored by Daniel Salzman's avatar Daniel Salzman

Merge branch 'dynamic_modules'

parents 4eec99df 0cfeb435
Pipeline #4285 passed with stages
in 10 minutes and 29 seconds
......@@ -53,8 +53,10 @@
/m4/ltversion.m4
/m4/lt~obsolete.m4
/src/dnssec/libdnssec.pc
/src/knotd.pc
/src/libknot.pc
/src/libknot/version.h
/src/knot/modules/static_modules.h
# dnstap
/src/contrib/dnstap/Makefile
......
......@@ -177,6 +177,8 @@ src/knot/conf/confio.c
src/knot/conf/confio.h
src/knot/conf/migration.c
src/knot/conf/migration.h
src/knot/conf/module.c
src/knot/conf/module.h
src/knot/conf/scheme.c
src/knot/conf/scheme.h
src/knot/conf/tools.c
......@@ -231,6 +233,7 @@ src/knot/events/log.c
src/knot/events/log.h
src/knot/events/replan.c
src/knot/events/replan.h
src/knot/include/module.h
src/knot/journal/journal.c
src/knot/journal/journal.h
src/knot/journal/old_journal.c
......@@ -238,28 +241,19 @@ src/knot/journal/old_journal.h
src/knot/journal/serialization.c
src/knot/journal/serialization.h
src/knot/modules/dnsproxy/dnsproxy.c
src/knot/modules/dnsproxy/dnsproxy.h
src/knot/modules/dnstap/dnstap.c
src/knot/modules/dnstap/dnstap.h
src/knot/modules/noudp/noudp.c
src/knot/modules/noudp/noudp.h
src/knot/modules/online_sign/nsec_next.c
src/knot/modules/online_sign/nsec_next.h
src/knot/modules/online_sign/online_sign.c
src/knot/modules/online_sign/online_sign.h
src/knot/modules/onlinesign/nsec_next.c
src/knot/modules/onlinesign/nsec_next.h
src/knot/modules/onlinesign/onlinesign.c
src/knot/modules/rosedb/rosedb.c
src/knot/modules/rosedb/rosedb.h
src/knot/modules/rosedb/rosedb_tool.c
src/knot/modules/rrl/functions.c
src/knot/modules/rrl/functions.h
src/knot/modules/rrl/rrl.c
src/knot/modules/rrl/rrl.h
src/knot/modules/stats/stats.c
src/knot/modules/stats/stats.h
src/knot/modules/synth_record/synth_record.c
src/knot/modules/synth_record/synth_record.h
src/knot/modules/synthrecord/synthrecord.c
src/knot/modules/whoami/whoami.c
src/knot/modules/whoami/whoami.h
src/knot/nameserver/axfr.c
src/knot/nameserver/axfr.h
src/knot/nameserver/chaos.c
......@@ -530,7 +524,7 @@ tests/libknot/test_tsig.c
tests/libknot/test_yparser.c
tests/libknot/test_ypscheme.c
tests/libknot/test_yptrafo.c
tests/modules/test_online_sign.c
tests/modules/test_onlinesign.c
tests/modules/test_rrl.c
tests/test_acl.c
tests/test_changeset.c
......
......@@ -59,7 +59,8 @@ LT_INIT
# Use pkg-config
PKG_PROG_PKG_CONFIG
m4_ifdef([PKG_INSTALLDIR], [PKG_INSTALLDIR], [AC_SUBST([pkgconfigdir], ['${libdir}/pkgconfig'])])
AC_CONFIG_FILES([src/libknot.pc
AC_CONFIG_FILES([src/knotd.pc
src/libknot.pc
src/dnssec/libdnssec.pc
src/zscanner/libzscanner.pc
])
......@@ -196,6 +197,14 @@ AC_ARG_WITH([configdir],
[config_dir=$withval])
AC_SUBST(config_dir)
module_dir=
module_instdir="${libdir}/knot/modules-${KNOT_VERSION_MAJOR}.${KNOT_VERSION_MINOR}"
AC_ARG_WITH([moduledir],
AC_HELP_STRING([--with-moduledir=path], [Path to auto-loaded dynamic modules. [default not set]]),
[module_dir=$withval module_instdir=$module_dir])
AC_SUBST(module_instdir)
AC_SUBST(module_dir)
#########################################
# Dependencies needed for Knot DNS daemon
#########################################
......@@ -275,6 +284,31 @@ AS_IF([test "$with_urcu" != "no"], [
AC_SEARCH_LIBS([urcu_init], [urcu], [AC_MSG_ERROR([liburcu is too old (< 0.4.0), urcu_init symbol found])])
])
static_modules=""
shared_modules=""
AS_IF([test "$enable_daemon" = "yes"],[
static_modules_declars=""
static_modules_init=""
doc_modules=""
KNOT_MODULE([dnsproxy], "yes", "non-shareable")
KNOT_MODULE([dnstap], "no")
KNOT_MODULE([noudp], "yes")
KNOT_MODULE([onlinesign], "yes", "non-shareable")
KNOT_MODULE([rosedb], "no")
KNOT_MODULE([rrl], "yes")
KNOT_MODULE([stats], "yes")
KNOT_MODULE([synthrecord], "yes")
KNOT_MODULE([whoami], "yes")
AC_SUBST([STATIC_MODULES_DECLARS], [$(printf "$static_modules_declars")])
AM_SUBST_NOTMAKE([STATIC_MODULES_DECLARS])
AC_SUBST([STATIC_MODULES_INIT], [$(printf "$static_modules_init")])
AM_SUBST_NOTMAKE([STATIC_MODULES_INIT])
AC_SUBST([DOC_MODULES], [$(printf "$doc_modules")])
AM_SUBST_NOTMAKE([DOC_MODULES])
])
opt_dnstap=no
AS_IF([test "$enable_daemon" = "yes" -o "$enable_utilities" = "yes"],[
dnl Check for dnstap.
......@@ -385,17 +419,6 @@ AS_CASE([$timer_mapsize],
[AC_ERROR([timer_mapsize must be an integer number])])])
AC_DEFINE_UNQUOTED([TIMER_MAPSIZE], [$timer_mapsize], [Timer DB mapsize.])
AS_IF([test "$enable_daemon" = "yes"],[
dnl Check for rosedb module
AC_ARG_ENABLE([rosedb],
AS_HELP_STRING([--enable-rosedb], [Enable static RR query module.]),
[], [enable_rosedb=no])
]) # Knot DNS daemon dependencies
AS_IF([test "$enable_rosedb" = yes], [AC_DEFINE([HAVE_ROSEDB], [1], [Define to 1 to enable static RR query module.])])
AM_CONDITIONAL([HAVE_ROSEDB], [test "$enable_rosedb" = yes])
# libedit
AS_IF([test "$enable_daemon" = "yes" -o "$enable_utilities" = "yes"], [
PKG_CHECK_MODULES([libedit], [libedit], [with_libedit=yes], [
......@@ -534,6 +557,7 @@ result_msg_base=" $PACKAGE $VERSION
Run dir: ${run_dir}
Storage dir: ${storage_dir}
Config dir: ${config_dir}
Module dir: ${module_dir}
Configuration DB mapsize: ${conf_mapsize} MiB
Timers DB mapsize: ${timer_mapsize} MiB
......@@ -543,14 +567,17 @@ result_msg_base=" $PACKAGE $VERSION
Knot DNS utils: ${enable_utilities}
Knot DNS documentation: ${enable_documentation}
Use recvmmsg: ${enable_recvmmsg}
Use SO_REUSEPORT: ${enable_reuseport}
Fast zone parser: ${enable_fastparser}
Utilities with IDN: ${with_libidn}
Systemd integration: ${enable_systemd}
Dnstap support: ${opt_dnstap}
Code coverage: ${enable_code_coverage}
PKCS #11 support: ${enable_pkcs11}"
Static modules: ${static_modules}
Shared modules: ${shared_modules}
Use recvmmsg: ${enable_recvmmsg}
Use SO_REUSEPORT: ${enable_reuseport}
Fast zone parser: ${enable_fastparser}
Utilities with IDN: ${with_libidn}
Utilities with Dnstap: ${opt_dnstap}
Systemd integration: ${enable_systemd}
Code coverage: ${enable_code_coverage}
PKCS #11 support: ${enable_pkcs11}"
result_msg_esc=$(echo -n "$result_msg_base" | sed '$!s/$/\\n/' | tr -d '\n')
result_msg_add="
......@@ -563,6 +590,7 @@ AC_DEFINE_UNQUOTED([CONFIGURE_SUMMARY],["$result_msg_esc"],[Configure summary])
AC_CONFIG_FILES([Makefile
doc/Makefile
doc/modules.rst
libtap/Makefile
tests/Makefile
tests-fuzz/Makefile
......@@ -572,6 +600,7 @@ AC_CONFIG_FILES([Makefile
src/contrib/dnstap/Makefile
src/dnssec/Makefile
src/dnssec/tests/Makefile
src/knot/modules/static_modules.h
src/zscanner/Makefile
])
......
/_build
/modules.rst
# sphinx-build manpages
/man/knot.conf.5
......
......@@ -457,6 +457,40 @@ of the limitations will be hopefully removed in the near future.
- Legacy key export is not implemented.
- DS record export is not implemented.
.. _query-modules:
Query modules
=============
Knot DNS supports configurable query modules that can alter the way
queries are processed. Each query requires a finite number of steps to
be resolved. We call this set of steps a *query plan*, an abstraction
that groups these steps into several stages.
* Before-query processing
* Answer, Authority, Additional records packet sections processing
* After-query processing
For example, processing an Internet-class query needs to find an
answer. Then based on the previous state, it may also append an
authority SOA or provide additional records. Each of these actions
represents a 'processing step'. Now, if a query module is loaded for a
zone, it is provided with an implicit query plan which can be extended
by the module or even changed altogether.
A module is active if its name, which includes the ``mod-`` prefix, is assigned
to the zone/template :ref:`zone_module` option or to the *default* template
:ref:`template_global-module` option if activating for all queries.
If the module is configurable, a corresponding module section with
an identifier must be created and then referenced in the form of
``module_name/module_id``. See :ref:`Modules` for the list of available modules.
.. NOTE::
Query modules are processed in the order they are specified in the
zone/template configuration. In most cases, the recommended order is::
mod-synthrecord, mod-onlinesign, mod-rrl, mod-dnstap, mod-stats
Performance Tuning
==================
......
......@@ -10,10 +10,10 @@ Welcome to Knot DNS's documentation!
requirements
installation
configuration
modules
operation
troubleshooting
reference
modules
utilities
migration
appendices
......@@ -66,11 +66,11 @@ the following symbols:
| – Choice
.UNINDENT
.sp
There are 11 main sections (\fBserver\fP, \fBcontrol\fP, \fBlog\fP, \fBstatistics\fP,
\fBkeystore\fP, \fBpolicy\fP, \fBkey\fP, \fBacl\fP, \fBremote\fP, \fBtemplate\fP, and
\fBzone\fP) and module sections with the \fBmod\-\fP prefix. Most of the sections
(excluding \fBserver\fP, \fBcontrol\fP, and \fBstatistics\fP) are sequences of
settings blocks. Each settings block begins with a unique identifier,
There are 12 main sections (\fBmodule\fP, \fBserver\fP, \fBcontrol\fP, \fBlog\fP,
\fBstatistics\fP, \fBkeystore\fP, \fBpolicy\fP, \fBkey\fP, \fBacl\fP, \fBremote\fP,
\fBtemplate\fP, and \fBzone\fP) and module sections with the \fBmod\-\fP prefix.
Most of the sections (excluding \fBserver\fP, \fBcontrol\fP, and \fBstatistics\fP)
are sequences of settings blocks. Each settings block begins with a unique identifier,
which can be used as a reference from other sections (such identifier
must be defined in advance).
.sp
......@@ -124,6 +124,46 @@ include: STR
.fi
.UNINDENT
.UNINDENT
.SH MODULE SECTION
.sp
Dynamic modules loading configuration.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If configured with non\-empty \fB\(ga\-\-with\-moduledir=path\(ga\fP parameter, all
shared modules in this directory will be automatically loaded.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
module:
\- id: STR
file: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier in the form of the \fBmod\-\fP prefix and module name suffix.
.SS file
.sp
A path to a shared library file with the module implementation.
.sp
\fIDefault:\fP \fB${libdir}/knot/modules\-${version}\fP/module_name.so
(or \fB${path}\fP/module_name.so if configured with \fB\-\-with\-moduledir=path\fP)
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
If the path is not absolute, the library is searched in the set of
system directories. See \fBman dlopen\fP for more details.
.UNINDENT
.UNINDENT
.SH SERVER SECTION
.sp
General options related to the server.
......@@ -1110,545 +1150,6 @@ Minimum severity level for messages related to zones that are logged.
Minimum severity level for all message types that are logged.
.sp
\fIDefault:\fP not set
.SH MODULE RRL
.sp
A response rate limiting module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-rrl:
\- id: STR
rate\-limit: INT
slip: INT
table\-size: INT
whitelist: ADDR[/INT] | ADDR\-ADDR ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS rate\-limit
.sp
Rate limiting is based on the token bucket scheme. A rate basically
represents a number of tokens available each second. Each response is
processed and classified (based on several discriminators, e.g.
source netblock, query type, zone name, rcode, etc.). Classified responses are
then hashed and assigned to a bucket containing number of available
tokens, timestamp and metadata. When available tokens are exhausted,
response is dropped or sent as truncated (see \fI\%slip\fP).
Number of available tokens is recalculated each second.
.sp
\fIRequired\fP
.SS table\-size
.sp
Size of the hash table in a number of buckets. The larger the hash table, the lesser
the probability of a hash collision, but at the expense of additional memory costs.
Each bucket is estimated roughly to 32 bytes. The size should be selected as
a reasonably large prime due to better hash function distribution properties.
Hash table is internally chained and works well up to a fill rate of 90 %, general
rule of thumb is to select a prime near 1.2 * maximum_qps.
.sp
\fIDefault:\fP 393241
.SS slip
.sp
As attacks using DNS/UDP are usually based on a forged source address,
an attacker could deny services to the victim\(aqs netblock if all
responses would be completely blocked. The idea behind SLIP mechanism
is to send each N\s-2\uth\d\s0 response as truncated, thus allowing client to
reconnect via TCP for at least some degree of service. It is worth
noting, that some responses can\(aqt be truncated (e.g. SERVFAIL).
.INDENT 0.0
.IP \(bu 2
Setting the value to \fB0\fP will cause that all rate\-limited responses will
be dropped. The outbound bandwidth and packet rate will be strictly capped
by the \fI\%rate\-limit\fP option. All legitimate requestors affected
by the limit will face denial of service and will observe excessive timeouts.
Therefore this setting is not recommended.
.IP \(bu 2
Setting the value to \fB1\fP will cause that all rate\-limited responses will
be sent as truncated. The amplification factor of the attack will be reduced,
but the outbound data bandwidth won\(aqt be lower than the incoming bandwidth.
Also the outbound packet rate will be the same as without RRL.
.IP \(bu 2
Setting the value to \fB2\fP will cause that half of the rate\-limited responses
will be dropped, the other half will be sent as truncated. With this
configuration, both outbound bandwidth and packet rate will be lower than the
inbound. On the other hand, the dropped responses enlarge the time window
for possible cache poisoning attack on the resolver.
.IP \(bu 2
Setting the value to anything \fBlarger than 2\fP will keep on decreasing
the outgoing rate\-limited bandwidth, packet rate, and chances to notify
legitimate requestors to reconnect using TCP. These attributes are inversely
proportional to the configured value. Setting the value high is not advisable.
.UNINDENT
.sp
\fIDefault:\fP 1
.SS whitelist
.sp
A list of IP addresses, network subnets, or network ranges to exempt from
rate limiting. Empty list means that no incoming connection will be
white\-listed.
.sp
\fIDefault:\fP not set
.SH MODULE DNSTAP
.sp
The module dnstap allows query and response logging.
.sp
For all queries logging, use this module in the \fIdefault\fP template. For
zone\-specific logging, use this module in the proper zone configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-dnstap:
\- id: STR
sink: STR
identity: STR
version: STR
log\-queries: BOOL
log\-responses: BOOL
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS sink
.sp
A sink path, which can be either a file or a UNIX socket when prefixed with
\fBunix:\fP\&.
.sp
\fIRequired\fP
.SS identity
.sp
A DNS server identity. Set empty value to disable.
.sp
\fIDefault:\fP FQDN hostname
.SS version
.sp
A DNS server version. Set empty value to disable.
.sp
\fIDefault:\fP server version
.SS log\-queries
.sp
If enabled, query messages will be logged.
.sp
\fIDefault:\fP on
.SS log\-responses
.sp
If enabled, response messages will be logged.
.sp
\fIDefault:\fP on
.SH MODULE ONLINE-SIGN
.sp
The module provides online DNSSEC signing. Instead of pre\-computing the zone signatures
when the zone is loaded into the server or instead of loading an externally signed zone,
the signatures are computed on\-the\-fly during answering.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-online\-sign:
\- id: STR
policy: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS policy
.sp
A \fI\%reference\fP to DNSSEC signing policy. A special \fIdefault\fP
value can be used for the default policy settings.
.SH MODULE SYNTH-RECORD
.sp
This module is able to synthesize either forward or reverse records for the
given prefix and subnet.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-synth\-record:
\- id: STR
type: forward | reverse
prefix: STR
origin: DNAME
ttl: INT
network: ADDR[/INT] | ADDR\-ADDR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS type
.sp
The type of generated records.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
\fBforward\fP – Forward records
.IP \(bu 2
\fBreverse\fP – Reverse records
.UNINDENT
.sp
\fIRequired\fP
.SS prefix
.sp
A record owner prefix.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The value doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP empty
.SS origin
.sp
A zone origin (only valid for the \fI\%reverse type\fP).
.sp
\fIRequired\fP
.SS ttl
.sp
Time to live of the generated records.
.sp
\fIDefault:\fP 3600
.SS network
.sp
An IP address, a network subnet, or a network range the query must match.
.sp
\fIRequired\fP
.SH MODULE DNSPROXY
.sp
The module catches all unsatisfied queries and forwards them to the indicated
server for resolution.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-dnsproxy:
\- id: STR
remote: remote_id
timeout: INT
fallback: BOOL
catch\-nxdomain: BOOL
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS remote
.sp
A \fI\%reference\fP to a remote server where the queries are
forwarded to.
.sp
\fIRequired\fP
.SS timeout
.sp
A remote response timeout in milliseconds.
.sp
\fIDefault:\fP 500
.SS fallback
.sp
If enabled, localy unsatisfied queries leading to REFUSED (no zone) are forwarded.
If disabled, all queries are directly forwarded without any local attempts
to resolve them.
.sp
\fIDefault:\fP on
.SS catch\-nxdomain
.sp
If enabled, localy unsatisfied queries leading to NXDOMAIN are forwarded.
This option is only relevant in the fallback mode.
.sp
\fIDefault:\fP off
.SH MODULE ROSEDB
.sp
The module provides a mean to override responses for certain queries before
the available zones are searched for the record.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-rosedb:
\- id: STR
dbdir: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS dbdir
.sp
A path to the directory where the database is stored.
.sp
\fIRequired\fP
.SH MODULE STATS
.sp
The module provides incoming query processing statistics.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Leading 16\-bit message size over TCP is not considered.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C