upstream/knot-dns
1
0
Fork 0
mirror of https://gitlab.nic.cz/knot/knot-dns.git synced 2026-02-03 18:49:28 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: move modules into separate module directories

Browse source
This commit is contained in:
Daniel Salzman 2017-05-08 19:57:57 +02:00
parent 83b56d9a5c
commit f9c59b77b5
14 changed files with 1171 additions and 1714 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
doc/configuration.rst
View file

@ -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
==================

2
doc/index.rst
View file

@ -10,10 +10,10 @@ Welcome to Knot DNS's documentation!
requirements
installation
configuration
modules
operation
troubleshooting
reference
modules
utilities
migration
appendices

539
doc/man/knot.conf.5in
View file

@ -1110,545 +1110,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
mod\-stats:
\- id: STR
request\-protocol: BOOL
server\-operation: BOOL
request\-bytes: BOOL
response\-bytes: BOOL
edns\-presence: BOOL
flag\-presence: BOOL
response\-code: BOOL
reply\-nodata: BOOL
query\-type: BOOL
query\-size: BOOL
reply\-size: BOOL
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS request\-protocol
.sp
If enabled, all incoming requests are counted by the network protocol:
.INDENT 0.0
.IP \(bu 2
udp4 \- UDP over IPv4
.IP \(bu 2
tcp4 \- TCP over IPv4
.IP \(bu 2
udp6 \- UDP over IPv6
.IP \(bu 2
tcp6 \- TCP over IPv6
.UNINDENT
.sp
\fIDefault:\fP on
.SS server\-operation
.sp
If enabled, all incoming requests are counted by the server operation. The
server operation is based on message header OpCode and message query (meta) type:
.INDENT 0.0
.IP \(bu 2
query \- Normal query operation
.IP \(bu 2
update \- Dynamic update operation
.IP \(bu 2
notify \- NOTIFY request operation
.IP \(bu 2
axfr \- Full zone transfer operation
.IP \(bu 2
ixfr \- Incremental zone transfer operation
.IP \(bu 2
invalid \- Invalid server operation
.UNINDENT
.sp
\fIDefault:\fP on
.SS request\-bytes
.sp
If enabled, all incoming request bytes are counted by the server operation:
.INDENT 0.0
.IP \(bu 2
query \- Normal query bytes
.IP \(bu 2
update \- Dynamic update bytes
.IP \(bu 2
other \- Other request bytes
.UNINDENT
.sp
\fIDefault:\fP on
.SS response\-bytes
.sp
If enabled, outgoing response bytes are counted by the server operation:
.INDENT 0.0
.IP \(bu 2
reply \- Normal response bytes
.IP \(bu 2
transfer \- Zone transfer bytes
.IP \(bu 2
other \- Other response bytes
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Dynamic update response bytes are not counted by this module.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP on
.SS edns\-presence
.sp
If enabled, EDNS pseudo section presence is counted by the message direction:
.INDENT 0.0
.IP \(bu 2
request \- EDNS present in request
.IP \(bu 2
response \- EDNS present in response
.UNINDENT
.sp
\fIDefault:\fP off
.SS flag\-presence
.sp
If enabled, some message header flags are counted:
.INDENT 0.0
.IP \(bu 2
TC \- Truncated Answer in response
.IP \(bu 2
DO \- DNSSEC OK in request
.UNINDENT
.sp
\fIDefault:\fP off
.SS response\-code
.sp
If enabled, outgoing response code is counted:
.INDENT 0.0
.IP \(bu 2
NOERROR
.IP \(bu 2
\&...
.IP \(bu 2
NOTZONE
.IP \(bu 2
BADVERS
.IP \(bu 2
\&...
.IP \(bu 2
BADCOOKIE
.IP \(bu 2
other \- All other codes
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In the case of multi\-message zone transfer response, just one counter is
incremented.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Dynamic update response code is not counted by this module.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP on
.SS reply\-nodata
.sp
If enabled, NODATA pseudo RCODE (see RFC 2308, Section 2.2) is counted by the
query type:
.INDENT 0.0
.IP \(bu 2
A
.IP \(bu 2
AAAA
.IP \(bu 2
other \- All other types
.UNINDENT
.sp
\fIDefault:\fP off
.SS query\-type
.sp
If enabled, normal query type is counted:
.INDENT 0.0
.IP \(bu 2
A (TYPE1)
.IP \(bu 2
\&...
.IP \(bu 2
TYPE65
.IP \(bu 2
SPF (TYPE99)
.IP \(bu 2
\&...
.IP \(bu 2
TYPE110
.IP \(bu 2
ANY (TYPE255)
.IP \(bu 2
\&...
.IP \(bu 2
TYPE260
.IP \(bu 2
other \- All other types
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Not all assigned meta types (IXFR, AXFR,...) have their own counters,
because such types are not processed as normal query.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP off
.SS query\-size
.sp
If enabled, normal query message size distribution is counted by the size range
in bytes:
.INDENT 0.0
.IP \(bu 2
0\-15
.IP \(bu 2
16\-31
.IP \(bu 2
\&...
.IP \(bu 2
272\-287
.IP \(bu 2
288\-65535
.UNINDENT
.sp
\fIDefault:\fP off
.SS reply\-size
.sp
If enabled, normal reply message size distribution is counted by the size range
in bytes:
.INDENT 0.0
.IP \(bu 2
0\-15
.IP \(bu 2
16\-31
.IP \(bu 2
\&...
.IP \(bu 2
4080\-4095
.IP \(bu 2
4096\-65535
.UNINDENT
.sp
\fIDefault:\fP off
.SH AUTHOR
CZ.NIC Labs <http://www.knot-dns.cz>
.SH COPYRIGHT

587
doc/modules.rst
View file

@ -1,587 +0,0 @@
.. highlight:: none
.. _Query_modules:
*************
Query modules
*************
Knot DNS supports configurable query modules that can alter the way
queries are processed. The concept is quite simple – 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``.
.. NOTE::
Query modules are processed in the order they are specified in the
zone/template configuration. In most cases, the recommended order is::
mod-synth-record, mod-online-sign, mod-rrl, mod-dnstap, mod-stats
``rrl`` — Response rate limiting
--------------------------------
Response rate limiting (RRL) is a method to combat DNS reflection amplification
attacks. These attacks rely on the fact that source address of a UDP query
can be forged, and without a worldwide deployment of `BCP38
<https://tools.ietf.org/html/bcp38>`_, such a forgery cannot be prevented.
An attacker can use a DNS server (or multiple servers) as an amplification
source and can flood a victim with a large number of unsolicited DNS responses.
The RRL lowers the amplification factor of these attacks by sending some of
the responses as truncated or by dropping them altogether.
The module introduces two counters. The number of slipped and dropped responses.
You can enable RRL by setting the :ref:`mod-rrl<mod-rrl>` module globally or per zone.
::
mod-rrl:
- id: default
rate-limit: 200 # Allow 200 resp/s for each flow
slip: 2 # Every other response slips
template:
- id: default
global-module: mod-rrl/default # Enable RRL globally
``dnstap`` – dnstap-enabled query logging
-----------------------------------------
A module for query and response logging based on dnstap_ library.
You can capture either all or zone-specific queries and responses; usually
you want to do the former. The configuration comprises only a
:ref:`mod-dnstap_sink` path parameter, which can be either a file or
a UNIX socket::
mod-dnstap:
- id: capture_all
sink: /tmp/capture.tap
template:
- id: default
global-module: mod-dnstap/capture_all
.. NOTE::
To be able to use a Unix socket you need an external program to create it.
Knot DNS connects to it as a client using the libfstrm library. It operates
exactly like syslog. See `here
<https://www.nlnetlabs.nl/bugs-script/show_bug.cgi?id=741#c10>`_ for
more details.
.. NOTE::
Dnstap log files can also be created or read using ``kdig``.
.. _dnstap: http://dnstap.info/
``synth-record`` – Automatic forward/reverse records
----------------------------------------------------
This module is able to synthesize either forward or reverse records for
a given prefix and subnet.
Records are synthesized only if the query can't be satisfied from the zone.
Both IPv4 and IPv6 are supported.
Automatic forward records
.........................
Example::
mod-synth-record:
- id: test1
type: forward
prefix: dynamic-
ttl: 400
network: 2620:0:b61::/52
zone:
- domain: test.
file: test.zone # Must exist
module: mod-synth-record/test1
Result:
.. code-block:: console
$ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test.
...
;; QUESTION SECTION:
;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. IN AAAA
;; ANSWER SECTION:
dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. 400 IN AAAA 2620:0:b61:100::1
You can also have CNAME aliases to the dynamic records, which are going to be
further resolved:
.. code-block:: console
$ kdig AAAA alias.test.
...
;; QUESTION SECTION:
;; alias.test. IN AAAA
;; ANSWER SECTION:
alias.test. 3600 IN CNAME dynamic-2620-0000-0b61-0100-0000-0000-0000-0002.test.
dynamic-2620-0000-0b61-0100-0000-0000-0000-0002.test. 400 IN AAAA 2620:0:b61:100::2
Automatic reverse records
.........................
Example::
mod-synth-record:
- id: test2
type: reverse
prefix: dynamic-
origin: test
ttl: 400
network: 2620:0:b61::/52
zone:
- domain: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
file: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.zone # Must exist
module: mod-synth-record/test2
Result:
.. code-block:: console
$ kdig -x 2620:0:b61::1
...
;; QUESTION SECTION:
;; 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. IN PTR
;; ANSWER SECTION:
1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 400 IN PTR
dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.test.
``dnsproxy`` – Tiny DNS proxy
-----------------------------
The module forwards all queries, or all specific zone queries if configured
per zone, to the indicated server for resolution. If configured in the fallback
mode, only localy unsatisfied queries are forwarded. I.e. a tiny DNS proxy.
There are several uses of this feature:
* A substitute public-facing server in front of the real one
* Local zones (poor man's "views"), rest is forwarded to the public-facing server
* etc.
.. NOTE::
The module does not alter the query/response as the resolver would,
and the original transport protocol is kept as well.
The configuration is straightforward and just a single remote server is
required::
remote:
- id: hidden
address: 10.0.1.1
mod-dnsproxy:
- id: default
remote: hidden
fallback: on
template:
- id: default
global-module: mod-dnsproxy/default
zone:
- domain: local.zone
When clients query for anything in the ``local.zone``, they will be
responded to locally. The rest of the requests will be forwarded to the
specified server (``10.0.1.1`` in this case).
``rosedb`` – Static resource records
------------------------------------
The module provides a mean to override responses for certain queries before
the record is searched in the available zones. The module comes with the
``rosedb_tool`` tool used to manipulate the database of static records.
Neither the tool nor the module are enabled by default, recompile with
the ``--enable-rosedb`` configuration flag to enable them.
For example, let's suppose we have a database of following records:
.. code-block:: none
myrecord.com. 3600 IN A 127.0.0.1
www.myrecord.com. 3600 IN A 127.0.0.2
ipv6.myrecord.com. 3600 IN AAAA ::1
And we query the nameserver with the following:
.. code-block:: console
$ kdig IN A myrecord.com
... returns NOERROR, 127.0.0.1
$ kdig IN A www.myrecord.com
... returns NOERROR, 127.0.0.2
$ kdig IN A stuff.myrecord.com
... returns NOERROR, 127.0.0.1
$ kdig IN AAAA myrecord.com
... returns NOERROR, NODATA
$ kdig IN AAAA ipv6.myrecord.com
... returns NOERROR, ::1
An entry in the database matches anything at the same or a lower domain
level, i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well.
This can be utilized to create catch-all entries.
You can also add authority information for the entries, provided you create
SOA + NS records for a name, like so:
.. code-block:: none
myrecord.com. 3600 IN SOA master host 1 3600 60 3600 3600
myrecord.com. 3600 IN NS ns1.myrecord.com.
myrecord.com. 3600 IN NS ns2.myrecord.com.
ns1.myrecord.com. 3600 IN A 127.0.0.1
ns2.myrecord.com. 3600 IN A 127.0.0.2
In this case, the responses will:
1. Be authoritative (AA flag set)
2. Provide an authority section (SOA + NS)
3. Be NXDOMAIN if the name is found *(i.e. the 'IN AAAA myrecord.com' from
the example)*, but not the RR type *(this is to allow the synthesis of
negative responses)*
The SOA record applies only to the 'myrecord.com.', not to any other
record (not even those of its subdomains). From this point of view, all records
in the database are unrelated and not hierarchical. The idea is to provide
subtree isolation for each entry.*
In addition, the module is able to log matching queries via remote syslog if
you specify a syslog address endpoint and an optional string code.
Here is an example on how to use the module:
* Create the entries in the database:
.. code-block:: console
$ mkdir /tmp/static_rrdb
$ # No logging
$ rosedb_tool /tmp/static_rrdb add myrecord.com. A 3600 "127.0.0.1" "-" "-"
$ # Logging as 'www_query' to Syslog at 10.0.0.1
$ rosedb_tool /tmp/static_rrdb add www.myrecord.com. A 3600 "127.0.0.1" \
"www_query" "10.0.0.1"
$ # Logging as 'ipv6_query' to Syslog at 10.0.0.1
$ rosedb_tool /tmp/static_rrdb add ipv6.myrecord.com. AAAA 3600 "::1" \
"ipv6_query" "10.0.0.1"
$ # Verify settings
$ rosedb_tool /tmp/static_rrdb list
www.myrecord.com. A RDATA=10B www_query 10.0.0.1
ipv6.myrecord.com. AAAA RDATA=22B ipv6_query 10.0.0.1
myrecord.com. A RDATA=10B - -
.. NOTE::
The database may be modified later on while the server is running.
* Configure the query module::
mod-rosedb:
- id: default
dbdir: /tmp/static_rrdb
template:
- id: default
global-module: mod-rosedb/default
The module accepts just one parameter – the path to the directory where
the database will be stored.
* Start the server:
.. code-block:: console
$ knotd -c knot.conf
* Verify the running instance:
.. code-block:: console
$ kdig @127.0.0.1#6667 A myrecord.com
``online-sign`` — Online DNSSEC signing
---------------------------------------
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.
The main purpose of the module is to enable authenticated responses with
zones which use other dynamic module (e.g., automatic reverse record
synthesis) because these zones cannot be pre-signed. However, it can be also
used as a simple signing solution for zones with low traffic and also as
a protection against zone content enumeration (zone walking).
In order to minimize the number of computed signatures per query, the module
produces a bit different responses from the responses that would be sent if
the zone was pre-signed. Still, the responses should be perfectly valid for
a DNSSEC validating resolver.
Differences from statically signed zones:
* The NSEC records are constructed as Minimally Covering NSEC Records
(see Appendix A in :rfc:`7129`). Therefore the generated domain names cover
the complete domain name space in the zone's authority.
* NXDOMAIN responses are promoted to NODATA responses. The module proves
that the query type does not exist rather than that the domain name does not
exist.
* Domain names matching a wildcard are expanded. The module pretends and proves
that the domain name exists rather than proving a presence of the wildcard.
Records synthesized by the module:
* DNSKEY record is synthesized in the zone apex and includes public key
material for the active signing key.
* NSEC records are synthesized as needed.
* RRSIG records are synthesized for authoritative content of the zone.
How to use the online signing module:
* Enable the module in the zone configuration with the default signing policy::
zone:
- domain: example.com
module: mod-online-sign
Or with an explicit signing policy::
policy:
- id: rsa
algorithm: RSASHA256
zsk-size: 2048
mod-online-sign:
- id: explicit
policy: rsa
zone:
- domain: example.com
module: mod-online-sign/explicit
Or use manual policy in an analogous manner, see
:ref:`Manual key management<dnssec-manual-key-management>`.
.. NOTE::
Only id, manual, keystore, algorithm, zsk-size, and rrsig-lifetime policy items are
relevant to this module. If no rrsig-lifetime is configured, the
default value is 25 hours.
* Make sure the zone is not signed and also that the automatic signing is
disabled. All is set, you are good to go. Reload (or start) the server:
.. code-block:: console
$ knotc reload
The following example stacks the online signing with reverse record synthesis
module::
mod-synth-record:
- id: lan-forward
type: forward
prefix: ip-
ttl: 1200
network: 192.168.100.0/24
zone:
- domain: corp.example.net
module: [mod-synth-record/lan-forward, mod-online-sign]
Known issues:
* The delegations are not signed correctly.
* Some CNAME records are not signed correctly.
* The automatic policy-based key rotation does not work. The rotation events are
invoked just at server (re)load.
Limitations:
* Online-sign module always enforces Single-Type Signing scheme.
* Only one active signing key can be used.
* Key rollover is not possible.
* The NSEC records may differ for one domain name if queried for different
types. This is an implementation shortcoming as the dynamic modules
cooperate loosely. Possible synthesis of a type by other module cannot
be predicted. This dissimilarity should not affect response validation,
even with validators performing `aggressive negative caching
<https://datatracker.ietf.org/doc/draft-fujiwara-dnsop-nsec-aggressiveuse/>`_.
* The NSEC proofs will work well with other dynamic modules only if the
modules synthesize only A and AAAA records. If synthesis of other type
is required, please, report this information to Knot DNS developers.
``whoami`` — whoami module
--------------------------
The module synthesizes an A or AAAA record containing the query source IP address,
at the apex of the zone being served. It makes sure to allow Knot DNS to generate
cacheable negative responses, and to allow fallback to extra records defined in the
underlying zone file. The TTL of the synthesized record is copied from
the TTL of the SOA record in the zone file.
Because a DNS query for type A or AAAA has nothing to do with whether
the query occurs over IPv4 or IPv6, this module requires a special
zone configuration to support both address families. For A queries, the
underlying zone must have a set of nameservers that only have IPv4
addresses, and for AAAA queries, the underlying zone must have a set of
nameservers that only have IPv6 addresses.
To enable this module, you need to add something like the following to
the Knot DNS configuration file::
zone:
- domain: whoami.domain.example
file: "/path/to/whoami.domain.example"
module: mod-whoami
zone:
- domain: whoami6.domain.example
file: "/path/to/whoami6.domain.example"
module: mod-whoami
.. NOTE::
This module is not configurable.
The whoami.domain.example zone file example:
.. code-block:: none
$TTL 1
@ SOA (
whoami.domain.example. ; MNAME
hostmaster.domain.example. ; RNAME
2016051300 ; SERIAL
86400 ; REFRESH
86400 ; RETRY
86400 ; EXPIRE
1 ; MINIMUM
)
$TTL 86400
@ NS ns1.whoami.domain.example.
@ NS ns2.whoami.domain.example.
@ NS ns3.whoami.domain.example.
@ NS ns4.whoami.domain.example.
ns1 A 198.51.100.53
ns2 A 192.0.2.53
ns3 A 203.0.113.53
ns4 A 198.19.123.53
The whoami6.domain.example zone file example:
.. code-block:: none
$TTL 1
@ SOA (
whoami6.domain.example. ; MNAME
hostmaster.domain.example. ; RNAME
2016051300 ; SERIAL
86400 ; REFRESH
86400 ; RETRY
86400 ; EXPIRE
1 ; MINIMUM
)
$TTL 86400
@ NS ns1.whoami6.domain.example.
@ NS ns2.whoami6.domain.example.
@ NS ns3.whoami6.domain.example.
@ NS ns4.whoami6.domain.example.
ns1 AAAA 2001:db8:100::53
ns2 AAAA 2001:db8:200::53
ns3 AAAA 2001:db8:300::53
ns4 AAAA 2001:db8:400::53
The parent domain would then delegate whoami.domain.example to
ns[1-4].whoami.domain.example and whoami6.domain.example to
ns[1-4].whoami6.domain.example, and include the corresponding A-only or
AAAA-only glue records.
``noudp`` — noudp module
------------------------
The module sends empty truncated response to any UDP query. This is similar
to a slipped answer in :ref:`response rate limiting<mod-rrl_rate-limit>`.
TCP queries are not affected.
To enable this module globally, you need to add something like the following
to the configuration file::
template:
- id: default
global-module: mod-noudp
.. NOTE::
This module is not configurable.
``stats`` — query statistics
----------------------------
The module extends server statistics with incoming DNS request and corresponding
response counters, such as used network protocol, total number of responded bytes,
etc (see :ref:`mod-stats<mod-stats>` for full list of supported counters).
This module should be configured as the last module.
Common statistics with default module configuration::
template:
- id: default
global-module: mod-stats
Per zone statistics with explicit module configuration::
mod-stats:
- id: custom
edns-presence: on
query-type: on
template:
- id: default
module: mod-stats/custom
.. NOTE::
Server initiated communication (outgoing NOTIFY, incoming \*XFR,...) is not
counted by this module.

587
doc/reference.rst
View file

@ -1269,590 +1269,3 @@ any
Minimum severity level for all message types that are logged.
*Default:* not set
.. _mod-rrl:
Module rrl
==========
A response rate limiting module.
::
mod-rrl:
- id: STR
rate-limit: INT
slip: INT
table-size: INT
whitelist: ADDR[/INT] | ADDR-ADDR ...
.. _mod-rrl_id:
id
--
A module identifier.
.. _mod-rrl_rate-limit:
rate-limit
----------
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 :ref:`mod-rrl_slip`).
Number of available tokens is recalculated each second.
*Required*
.. _mod-rrl_table-size:
table-size
----------
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.
*Default:* 393241
.. _mod-rrl_slip:
slip
----
As attacks using DNS/UDP are usually based on a forged source address,
an attacker could deny services to the victim's netblock if all
responses would be completely blocked. The idea behind SLIP mechanism
is to send each N\ :sup:`th` 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't be truncated (e.g. SERVFAIL).
- Setting the value to **0** will cause that all rate-limited responses will
be dropped. The outbound bandwidth and packet rate will be strictly capped
by the :ref:`mod-rrl_rate-limit` option. All legitimate requestors affected
by the limit will face denial of service and will observe excessive timeouts.
Therefore this setting is not recommended.
- Setting the value to **1** 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't be lower than the incoming bandwidth.
Also the outbound packet rate will be the same as without RRL.
- Setting the value to **2** 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.
- Setting the value to anything **larger than 2** 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.
*Default:* 1
.. _mod-rrl_whitelist:
whitelist
---------
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.
*Default:* not set
.. _Module dnstap:
Module dnstap
=============
The module dnstap allows query and response logging.
For all queries logging, use this module in the *default* template. For
zone-specific logging, use this module in the proper zone configuration.
::
mod-dnstap:
- id: STR
sink: STR
identity: STR
version: STR
log-queries: BOOL
log-responses: BOOL
.. _mod-dnstap_id:
id
--
A module identifier.
.. _mod-dnstap_sink:
sink
----
A sink path, which can be either a file or a UNIX socket when prefixed with
``unix:``.
*Required*
.. _mod-dnstap_identity:
identity
--------
A DNS server identity. Set empty value to disable.
*Default:* FQDN hostname
.. _mod-dnstap_version:
version
-------
A DNS server version. Set empty value to disable.
*Default:* server version
.. _mod-dnstap_log-queries:
log-queries
-----------
If enabled, query messages will be logged.
*Default:* on
.. _mod-dnstap_log-responses:
log-responses
-------------
If enabled, response messages will be logged.
*Default:* on
.. _Module online-sign:
Module online-sign
==================
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.
::
mod-online-sign:
- id: STR
policy: STR
.. _mod-online-sign_id:
id
--
A module identifier.
.. _mod-online-sign_policy:
policy
------
A :ref:`reference<policy_id>` to DNSSEC signing policy. A special *default*
value can be used for the default policy settings.
.. _Module synth-record:
Module synth-record
===================
This module is able to synthesize either forward or reverse records for the
given prefix and subnet.
::
mod-synth-record:
- id: STR
type: forward | reverse
prefix: STR
origin: DNAME
ttl: INT
network: ADDR[/INT] | ADDR-ADDR
.. _mod-synth-record_id:
id
--
A module identifier.
.. _mod-synth-record_type:
type
----
The type of generated records.
Possible values:
- ``forward`` – Forward records
- ``reverse`` – Reverse records
*Required*
.. _mod-synth-record_prefix:
prefix
------
A record owner prefix.
.. NOTE::
The value doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
*Default:* empty
.. _mod-synth-record_origin:
origin
------
A zone origin (only valid for the :ref:`reverse type<mod-synth-record_type>`).
*Required*
.. _mod-synth-record_ttl:
ttl
---
Time to live of the generated records.
*Default:* 3600
.. _mod-synth-record_network:
network
-------
An IP address, a network subnet, or a network range the query must match.
*Required*
.. _Module dnsproxy:
Module dnsproxy
===============
The module catches all unsatisfied queries and forwards them to the indicated
server for resolution.
::
mod-dnsproxy:
- id: STR
remote: remote_id
timeout: INT
fallback: BOOL
catch-nxdomain: BOOL
.. _mod-dnsproxy_id:
id
--
A module identifier.
.. _mod-dnsproxy_remote:
remote
------
A :ref:`reference<remote_id>` to a remote server where the queries are
forwarded to.
*Required*
.. _mod-dnsproxy_timeout:
timeout
-------
A remote response timeout in milliseconds.
*Default:* 500
.. _mod-dnsproxy_fallback:
fallback
--------
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.
*Default:* on
.. _mod-dnsproxy_catch-nxdomain:
catch-nxdomain
--------------
If enabled, localy unsatisfied queries leading to NXDOMAIN are forwarded.
This option is only relevant in the fallback mode.
*Default:* off
.. _Module rosedb:
Module rosedb
=============
The module provides a mean to override responses for certain queries before
the available zones are searched for the record.
::
mod-rosedb:
- id: STR
dbdir: STR
.. _mod-rosedb_id:
id
--
A module identifier.
.. _mod-rosedb_dbdir:
dbdir
-----
A path to the directory where the database is stored.
*Required*
.. _mod-stats:
Module stats
============
The module provides incoming query processing statistics.
.. NOTE::
Leading 16-bit message size over TCP is not considered.
::
mod-stats:
- id: STR
request-protocol: BOOL
server-operation: BOOL
request-bytes: BOOL
response-bytes: BOOL
edns-presence: BOOL
flag-presence: BOOL
response-code: BOOL
reply-nodata: BOOL
query-type: BOOL
query-size: BOOL
reply-size: BOOL
.. _mod-stats_id:
id
--
A module identifier.
.. _mod-stats_request-protocol:
request-protocol
----------------
If enabled, all incoming requests are counted by the network protocol:
* udp4 - UDP over IPv4
* tcp4 - TCP over IPv4
* udp6 - UDP over IPv6
* tcp6 - TCP over IPv6
*Default:* on
.. _mod-stats_server-operation:
server-operation
----------------
If enabled, all incoming requests are counted by the server operation. The
server operation is based on message header OpCode and message query (meta) type:
* query - Normal query operation
* update - Dynamic update operation
* notify - NOTIFY request operation
* axfr - Full zone transfer operation
* ixfr - Incremental zone transfer operation
* invalid - Invalid server operation
*Default:* on
.. _mod-stats_request-bytes:
request-bytes
-------------
If enabled, all incoming request bytes are counted by the server operation:
* query - Normal query bytes
* update - Dynamic update bytes
* other - Other request bytes
*Default:* on
.. _mod-stats_response-bytes:
response-bytes
--------------
If enabled, outgoing response bytes are counted by the server operation:
* reply - Normal response bytes
* transfer - Zone transfer bytes
* other - Other response bytes
.. WARNING::
Dynamic update response bytes are not counted by this module.
*Default:* on
.. _mod-stats_edns-presence:
edns-presence
-------------
If enabled, EDNS pseudo section presence is counted by the message direction:
* request - EDNS present in request
* response - EDNS present in response
*Default:* off
.. _mod-stats_flag-presence:
flag-presence
-------------
If enabled, some message header flags are counted:
* TC - Truncated Answer in response
* DO - DNSSEC OK in request
*Default:* off
.. _mod-stats_response-code:
response-code
-------------
If enabled, outgoing response code is counted:
* NOERROR
* ...
* NOTZONE
* BADVERS
* ...
* BADCOOKIE
* other - All other codes
.. NOTE::
In the case of multi-message zone transfer response, just one counter is
incremented.
.. WARNING::
Dynamic update response code is not counted by this module.
*Default:* on
.. _mod-stats_reply-nodata:
reply-nodata
------------
If enabled, NODATA pseudo RCODE (see RFC 2308, Section 2.2) is counted by the
query type:
* A
* AAAA
* other - All other types
*Default:* off
.. _mod-stats_query-type:
query-type
----------
If enabled, normal query type is counted:
* A (TYPE1)
* ...
* TYPE65
* SPF (TYPE99)
* ...
* TYPE110
* ANY (TYPE255)
* ...
* TYPE260
* other - All other types
.. NOTE::
Not all assigned meta types (IXFR, AXFR,...) have their own counters,
because such types are not processed as normal query.
*Default:* off
.. _mod-stats_query-size:
query-size
----------
If enabled, normal query message size distribution is counted by the size range
in bytes:
* 0-15
* 16-31
* ...
* 272-287
* 288-65535
*Default:* off
.. _mod-stats_reply-size:
reply-size
----------
If enabled, normal reply message size distribution is counted by the size range
in bytes:
* 0-15
* 16-31
* ...
* 4080-4095
* 4096-65535
*Default:* off

102
src/knot/modules/dnsproxy/dnsproxy.rst Normal file
View file

@ -0,0 +1,102 @@
.. _mod-dnsproxy:
``dnsproxy`` – Tiny DNS proxy
=============================
The module forwards all queries, or all specific zone queries if configured
per zone, to the indicated server for resolution. If configured in the fallback
mode, only localy unsatisfied queries are forwarded. I.e. a tiny DNS proxy.
There are several uses of this feature:
* A substitute public-facing server in front of the real one
* Local zones (poor man's "views"), rest is forwarded to the public-facing server
* etc.
.. NOTE::
The module does not alter the query/response as the resolver would,
and the original transport protocol is kept as well.
Example
-------
The configuration is straightforward and just a single remote server is
required::
remote:
- id: hidden
address: 10.0.1.1
mod-dnsproxy:
- id: default
remote: hidden
fallback: on
template:
- id: default
global-module: mod-dnsproxy/default
zone:
- domain: local.zone
When clients query for anything in the ``local.zone``, they will be
responded to locally. The rest of the requests will be forwarded to the
specified server (``10.0.1.1`` in this case).
Module reference
----------------
::
mod-dnsproxy:
- id: STR
remote: remote_id
timeout: INT
fallback: BOOL
catch-nxdomain: BOOL
.. _mod-dnsproxy_id:
id
..
A module identifier.
.. _mod-dnsproxy_remote:
remote
......
A :ref:`reference<remote_id>` to a remote server where the queries are
forwarded to.
*Required*
.. _mod-dnsproxy_timeout:
timeout
.......
A remote response timeout in milliseconds.
*Default:* 500
.. _mod-dnsproxy_fallback:
fallback
........
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.
*Default:* on
.. _mod-dnsproxy_catch-nxdomain:
catch-nxdomain
..............
If enabled, localy unsatisfied queries leading to NXDOMAIN are forwarded.
This option is only relevant in the fallback mode.
*Default:* off

103
src/knot/modules/dnstap/dnstap.rst Normal file
View file

@ -0,0 +1,103 @@
.. _mod-dnstap:
``dnstap`` – Dnstap traffic logging
===================================
A module for query and response logging based on the dnstap_ library.
You can capture either all or zone-specific queries and responses; usually
you want to do the former.
Example
-------
The configuration comprises only a :ref:`mod-dnstap_sink` path parameter,
which can be either a file or a UNIX socket::
mod-dnstap:
- id: capture_all
sink: /tmp/capture.tap
template:
- id: default
global-module: mod-dnstap/capture_all
.. NOTE::
To be able to use a Unix socket you need an external program to create it.
Knot DNS connects to it as a client using the libfstrm library. It operates
exactly like syslog. See `here
<https://www.nlnetlabs.nl/bugs-script/show_bug.cgi?id=741#c10>`_ for
more details.
.. NOTE::
Dnstap log files can also be created or read using ``kdig``.
.. _dnstap: http://dnstap.info/
Module reference
----------------
For all queries logging, use this module in the *default* template. For
zone-specific logging, use this module in the proper zone configuration.
::
mod-dnstap:
- id: STR
sink: STR
identity: STR
version: STR
log-queries: BOOL
log-responses: BOOL
.. _mod-dnstap_id:
id
..
A module identifier.
.. _mod-dnstap_sink:
sink
....
A sink path, which can be either a file or a UNIX socket when prefixed with
``unix:``.
*Required*
.. _mod-dnstap_identity:
identity
........
A DNS server identity. Set empty value to disable.
*Default:* FQDN hostname
.. _mod-dnstap_version:
version
.......
A DNS server version. Set empty value to disable.
*Default:* server version
.. _mod-dnstap_log-queries:
log-queries
...........
If enabled, query messages will be logged.
*Default:* on
.. _mod-dnstap_log-responses:
log-responses
.............
If enabled, response messages will be logged.
*Default:* on

20
src/knot/modules/noudp/noudp.rst Normal file
View file

@ -0,0 +1,20 @@
.. _mod-noudp:
``noudp`` — No UDP response
===========================
The module sends empty truncated response to any UDP query. TCP queries are
not affected.
Example
-------
To enable this module globally, you need to add something like the following
to the configuration file::
template:
- id: default
global-module: mod-noudp
.. NOTE::
This module is not configurable.

147
src/knot/modules/onlinesign/onlinesign.rst Normal file
View file

@ -0,0 +1,147 @@
.. _mod-onlinesign:
``onlinesign`` — Online DNSSEC signing
======================================
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.
The main purpose of the module is to enable authenticated responses with
zones which use other dynamic module (e.g., automatic reverse record
synthesis) because these zones cannot be pre-signed. However, it can be also
used as a simple signing solution for zones with low traffic and also as
a protection against zone content enumeration (zone walking).
In order to minimize the number of computed signatures per query, the module
produces a bit different responses from the responses that would be sent if
the zone was pre-signed. Still, the responses should be perfectly valid for
a DNSSEC validating resolver.
Differences from statically signed zones:
* The NSEC records are constructed as Minimally Covering NSEC Records
(see Appendix A in :rfc:`7129`). Therefore the generated domain names cover
the complete domain name space in the zone's authority.
* NXDOMAIN responses are promoted to NODATA responses. The module proves
that the query type does not exist rather than that the domain name does not
exist.
* Domain names matching a wildcard are expanded. The module pretends and proves
that the domain name exists rather than proving a presence of the wildcard.
Records synthesized by the module:
* DNSKEY record is synthesized in the zone apex and includes public key
material for the active signing key.
* NSEC records are synthesized as needed.
* RRSIG records are synthesized for authoritative content of the zone.
Known issues:
* The delegations are not signed correctly.
* Some CNAME records are not signed correctly.
* The automatic policy-based key rotation does not work. The rotation events are
invoked just at server (re)load.
Limitations:
* Online-sign module always enforces Single-Type Signing scheme.
* Only one active signing key can be used.
* Key rollover is not possible.
* The NSEC records may differ for one domain name if queried for different
types. This is an implementation shortcoming as the dynamic modules
cooperate loosely. Possible synthesis of a type by other module cannot
be predicted. This dissimilarity should not affect response validation,
even with validators performing `aggressive negative caching
<https://datatracker.ietf.org/doc/draft-fujiwara-dnsop-nsec-aggressiveuse/>`_.
* The NSEC proofs will work well with other dynamic modules only if the
modules synthesize only A and AAAA records. If synthesis of other type
is required, please, report this information to Knot DNS developers.
Example
-------
* Enable the module in the zone configuration with the default signing policy::
zone:
- domain: example.com
module: mod-onlinesign
Or with an explicit signing policy::
policy:
- id: rsa
algorithm: RSASHA256
zsk-size: 2048
mod-onlinesign:
- id: explicit
policy: rsa
zone:
- domain: example.com
module: mod-onlinesign/explicit
Or use manual policy in an analogous manner, see
:ref:`Manual key management<dnssec-manual-key-management>`.
.. NOTE::
Only id, manual, keystore, algorithm, zsk-size, and rrsig-lifetime policy items are
relevant to this module. If no rrsig-lifetime is configured, the
default value is 25 hours.
* Make sure the zone is not signed and also that the automatic signing is
disabled. All is set, you are good to go. Reload (or start) the server:
.. code-block:: console
$ knotc reload
The following example stacks the online signing with reverse record synthesis
module::
mod-synthrecord:
- id: lan-forward
type: forward
prefix: ip-
ttl: 1200
network: 192.168.100.0/24
zone:
- domain: corp.example.net
module: [mod-synthrecord/lan-forward, mod-onlinesign]
Module reference
----------------
::
mod-onlinesign:
- id: STR
policy: STR
.. _mod-onlinesign_id:
id
..
A module identifier.
.. _mod-onlinesign_policy:
policy
......
A :ref:`reference<policy_id>` to DNSSEC signing policy. A special *default*
value can be used for the default policy settings.

137
src/knot/modules/rosedb/rosedb.rst Normal file
View file

@ -0,0 +1,137 @@
.. _mod-rosedb:
``rosedb`` – Static resource records
====================================
The module provides a mean to override responses for certain queries before
the record is searched in the available zones. The module comes with the
``rosedb_tool`` tool used to manipulate the database of static records.
For example, let's suppose we have a database of following records:
.. code-block:: none
myrecord.com. 3600 IN A 127.0.0.1
www.myrecord.com. 3600 IN A 127.0.0.2
ipv6.myrecord.com. 3600 IN AAAA ::1
And we query the nameserver with the following:
.. code-block:: console
$ kdig IN A myrecord.com
... returns NOERROR, 127.0.0.1
$ kdig IN A www.myrecord.com
... returns NOERROR, 127.0.0.2
$ kdig IN A stuff.myrecord.com
... returns NOERROR, 127.0.0.1
$ kdig IN AAAA myrecord.com
... returns NOERROR, NODATA
$ kdig IN AAAA ipv6.myrecord.com
... returns NOERROR, ::1
An entry in the database matches anything at the same or a lower domain
level, i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well.
This can be utilized to create catch-all entries.
You can also add authority information for the entries, provided you create
SOA + NS records for a name, like so:
.. code-block:: none
myrecord.com. 3600 IN SOA master host 1 3600 60 3600 3600
myrecord.com. 3600 IN NS ns1.myrecord.com.
myrecord.com. 3600 IN NS ns2.myrecord.com.
ns1.myrecord.com. 3600 IN A 127.0.0.1
ns2.myrecord.com. 3600 IN A 127.0.0.2
In this case, the responses will:
1. Be authoritative (AA flag set)
2. Provide an authority section (SOA + NS)
3. Be NXDOMAIN if the name is found *(i.e. the 'IN AAAA myrecord.com' from
the example)*, but not the RR type *(this is to allow the synthesis of
negative responses)*
The SOA record applies only to the 'myrecord.com.', not to any other
record (not even those of its subdomains). From this point of view, all records
in the database are unrelated and not hierarchical. The idea is to provide
subtree isolation for each entry.
In addition, the module is able to log matching queries via remote syslog if
you specify a syslog address endpoint and an optional string code.
Example
-------
* Create the entries in the database:
.. code-block:: console
$ mkdir /tmp/static_rrdb
$ # No logging
$ rosedb_tool /tmp/static_rrdb add myrecord.com. A 3600 "127.0.0.1" "-" "-"
$ # Logging as 'www_query' to Syslog at 10.0.0.1
$ rosedb_tool /tmp/static_rrdb add www.myrecord.com. A 3600 "127.0.0.1" \
"www_query" "10.0.0.1"
$ # Logging as 'ipv6_query' to Syslog at 10.0.0.1
$ rosedb_tool /tmp/static_rrdb add ipv6.myrecord.com. AAAA 3600 "::1" \
"ipv6_query" "10.0.0.1"
$ # Verify settings
$ rosedb_tool /tmp/static_rrdb list
www.myrecord.com. A RDATA=10B www_query 10.0.0.1
ipv6.myrecord.com. AAAA RDATA=22B ipv6_query 10.0.0.1
myrecord.com. A RDATA=10B - -
.. NOTE::
The database may be modified later on while the server is running.
* Configure the query module::
mod-rosedb:
- id: default
dbdir: /tmp/static_rrdb
template:
- id: default
global-module: mod-rosedb/default
The module accepts just one parameter – the path to the directory where
the database will be stored.
* Start the server:
.. code-block:: console
$ knotd -c knot.conf
* Verify the running instance:
.. code-block:: console
$ kdig @127.0.0.1#6667 A myrecord.com
Module reference
----------------
::
mod-rosedb:
- id: STR
dbdir: STR
.. _mod-rosedb_id:
id
..
A module identifier.
.. _mod-rosedb_dbdir:
dbdir
.....
A path to the directory where the database is stored.
*Required*

129
src/knot/modules/rrl/rrl.rst Normal file
View file

@ -0,0 +1,129 @@
.. _mod-rrl:
``rrl`` — Response rate limiting
================================
Response rate limiting (RRL) is a method to combat DNS reflection amplification
attacks. These attacks rely on the fact that source address of a UDP query
can be forged, and without a worldwide deployment of `BCP38
<https://tools.ietf.org/html/bcp38>`_, such a forgery cannot be prevented.
An attacker can use a DNS server (or multiple servers) as an amplification
source and can flood a victim with a large number of unsolicited DNS responses.
The RRL lowers the amplification factor of these attacks by sending some of
the responses as truncated or by dropping them altogether.
.. NOTE::
The module introduces two statistics counters. The number of slipped and
dropped responses.
Example
-------
You can enable RRL by setting the module globally or per zone.
::
mod-rrl:
- id: default
rate-limit: 200 # Allow 200 resp/s for each flow
slip: 2 # Every other response slips
template:
- id: default
global-module: mod-rrl/default # Enable RRL globally
Module reference
----------------
::
mod-rrl:
- id: STR
rate-limit: INT
slip: INT
table-size: INT
whitelist: ADDR[/INT] | ADDR-ADDR ...
.. _mod-rrl_id:
id
..
A module identifier.
.. _mod-rrl_rate-limit:
rate-limit
..........
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 :ref:`mod-rrl_slip`).
Number of available tokens is recalculated each second.
*Required*
.. _mod-rrl_table-size:
table-size
..........
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.
*Default:* 393241
.. _mod-rrl_slip:
slip
....
As attacks using DNS/UDP are usually based on a forged source address,
an attacker could deny services to the victim's netblock if all
responses would be completely blocked. The idea behind SLIP mechanism
is to send each N\ :sup:`th` 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't be truncated (e.g. SERVFAIL).
- Setting the value to **0** will cause that all rate-limited responses will
be dropped. The outbound bandwidth and packet rate will be strictly capped
by the :ref:`mod-rrl_rate-limit` option. All legitimate requestors affected
by the limit will face denial of service and will observe excessive timeouts.
Therefore this setting is not recommended.
- Setting the value to **1** 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't be lower than the incoming bandwidth.
Also the outbound packet rate will be the same as without RRL.
- Setting the value to **2** 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.
- Setting the value to anything **larger than 2** 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.
*Default:* 1
.. _mod-rrl_whitelist:
whitelist
.........
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.
*Default:* not set

240
src/knot/modules/stats/stats.rst Normal file
View file

@ -0,0 +1,240 @@
.. _mod-stats:
``stats`` — Query statistics
============================
The module extends server statistics with incoming DNS request and corresponding
response counters, such as used network protocol, total number of responded bytes,
etc (see module reference for full list of supported counters).
This module should be configured as the last module.
.. NOTE::
Server initiated communication (outgoing NOTIFY, incoming \*XFR,...) is not
counted by this module.
.. NOTE::
Leading 16-bit message size over TCP is not considered.
Example
-------
Common statistics with default module configuration::
template:
- id: default
global-module: mod-stats
Per zone statistics with explicit module configuration::
mod-stats:
- id: custom
edns-presence: on
query-type: on
template:
- id: default
module: mod-stats/custom
Module reference
----------------
::
mod-stats:
- id: STR
request-protocol: BOOL
server-operation: BOOL
request-bytes: BOOL
response-bytes: BOOL
edns-presence: BOOL
flag-presence: BOOL
response-code: BOOL
reply-nodata: BOOL
query-type: BOOL
query-size: BOOL
reply-size: BOOL
.. _mod-stats_id:
id
..
A module identifier.
.. _mod-stats_request-protocol:
request-protocol
................
If enabled, all incoming requests are counted by the network protocol:
* udp4 - UDP over IPv4
* tcp4 - TCP over IPv4
* udp6 - UDP over IPv6
* tcp6 - TCP over IPv6
*Default:* on
.. _mod-stats_server-operation:
server-operation
................
If enabled, all incoming requests are counted by the server operation. The
server operation is based on message header OpCode and message query (meta) type:
* query - Normal query operation
* update - Dynamic update operation
* notify - NOTIFY request operation
* axfr - Full zone transfer operation
* ixfr - Incremental zone transfer operation
* invalid - Invalid server operation
*Default:* on
.. _mod-stats_request-bytes:
request-bytes
.............
If enabled, all incoming request bytes are counted by the server operation:
* query - Normal query bytes
* update - Dynamic update bytes
* other - Other request bytes
*Default:* on
.. _mod-stats_response-bytes:
response-bytes
..............
If enabled, outgoing response bytes are counted by the server operation:
* reply - Normal response bytes
* transfer - Zone transfer bytes
* other - Other response bytes
.. WARNING::
Dynamic update response bytes are not counted by this module.
*Default:* on
.. _mod-stats_edns-presence:
edns-presence
.............
If enabled, EDNS pseudo section presence is counted by the message direction:
* request - EDNS present in request
* response - EDNS present in response
*Default:* off
.. _mod-stats_flag-presence:
flag-presence
.............
If enabled, some message header flags are counted:
* TC - Truncated Answer in response
* DO - DNSSEC OK in request
*Default:* off
.. _mod-stats_response-code:
response-code
.............
If enabled, outgoing response code is counted:
* NOERROR
* ...
* NOTZONE
* BADVERS
* ...
* BADCOOKIE
* other - All other codes
.. NOTE::
In the case of multi-message zone transfer response, just one counter is
incremented.
.. WARNING::
Dynamic update response code is not counted by this module.
*Default:* on
.. _mod-stats_reply-nodata:
reply-nodata
............
If enabled, NODATA pseudo RCODE (see RFC 2308, Section 2.2) is counted by the
query type:
* A
* AAAA
* other - All other types
*Default:* off
.. _mod-stats_query-type:
query-type
..........
If enabled, normal query type is counted:
* A (TYPE1)
* ...
* TYPE65
* SPF (TYPE99)
* ...
* TYPE110
* ANY (TYPE255)
* ...
* TYPE260
* other - All other types
.. NOTE::
Not all assigned meta types (IXFR, AXFR,...) have their own counters,
because such types are not processed as normal query.
*Default:* off
.. _mod-stats_query-size:
query-size
..........
If enabled, normal query message size distribution is counted by the size range
in bytes:
* 0-15
* 16-31
* ...
* 272-287
* 288-65535
*Default:* off
.. _mod-stats_reply-size:
reply-size
..........
If enabled, normal reply message size distribution is counted by the size range
in bytes:
* 0-15
* 16-31
* ...
* 4080-4095
* 4096-65535
*Default:* off

161
src/knot/modules/synthrecord/synthrecord.rst Normal file
View file

@ -0,0 +1,161 @@
.. _mod-synthrecord:
``synthrecord`` – Automatic forward/reverse records
===================================================
This module is able to synthesize either forward or reverse records for
a given prefix and subnet.
Records are synthesized only if the query can't be satisfied from the zone.
Both IPv4 and IPv6 are supported.
Example
-------
Automatic forward records
.........................
::
mod-synthrecord:
- id: test1
type: forward
prefix: dynamic-
ttl: 400
network: 2620:0:b61::/52
zone:
- domain: test.
file: test.zone # Must exist
module: mod-synthrecord/test1
Result:
.. code-block:: console
$ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test.
...
;; QUESTION SECTION:
;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. IN AAAA
;; ANSWER SECTION:
dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. 400 IN AAAA 2620:0:b61:100::1
You can also have CNAME aliases to the dynamic records, which are going to be
further resolved:
.. code-block:: console
$ kdig AAAA alias.test.
...
;; QUESTION SECTION:
;; alias.test. IN AAAA
;; ANSWER SECTION:
alias.test. 3600 IN CNAME dynamic-2620-0000-0b61-0100-0000-0000-0000-0002.test.
dynamic-2620-0000-0b61-0100-0000-0000-0000-0002.test. 400 IN AAAA 2620:0:b61:100::2
Automatic reverse records
.........................
::
mod-synthrecord:
- id: test2
type: reverse
prefix: dynamic-
origin: test
ttl: 400
network: 2620:0:b61::/52
zone:
- domain: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
file: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.zone # Must exist
module: mod-synthrecord/test2
Result:
.. code-block:: console
$ kdig -x 2620:0:b61::1
...
;; QUESTION SECTION:
;; 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. IN PTR
;; ANSWER SECTION:
1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 400 IN PTR
dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.test.
Module reference
----------------
::
mod-synthrecord:
- id: STR
type: forward | reverse
prefix: STR
origin: DNAME
ttl: INT
network: ADDR[/INT] | ADDR-ADDR
.. _mod-synthrecord_id:
id
..
A module identifier.
.. _mod-synthrecord_type:
type
....
The type of generated records.
Possible values:
- ``forward`` – Forward records
- ``reverse`` – Reverse records
*Required*
.. _mod-synthrecord_prefix:
prefix
......
A record owner prefix.
.. NOTE::
The value doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
*Default:* empty
.. _mod-synthrecord_origin:
origin
......
A zone origin (only valid for the :ref:`reverse type<mod-synthrecord_type>`).
*Required*
.. _mod-synthrecord_ttl:
ttl
...
Time to live of the generated records.
*Default:* 3600
.. _mod-synthrecord_network:
network
.......
An IP address, a network subnet, or a network range the query must match.
*Required*

97
src/knot/modules/whoami/whoami.rst Normal file
View file

@ -0,0 +1,97 @@
.. _mod-whoami:
``whoami`` — Whoami response
============================
The module synthesizes an A or AAAA record containing the query source IP address,
at the apex of the zone being served. It makes sure to allow Knot DNS to generate
cacheable negative responses, and to allow fallback to extra records defined in the
underlying zone file. The TTL of the synthesized record is copied from
the TTL of the SOA record in the zone file.
Because a DNS query for type A or AAAA has nothing to do with whether
the query occurs over IPv4 or IPv6, this module requires a special
zone configuration to support both address families. For A queries, the
underlying zone must have a set of nameservers that only have IPv4
addresses, and for AAAA queries, the underlying zone must have a set of
nameservers that only have IPv6 addresses.
Example
-------
To enable this module, you need to add something like the following to
the Knot DNS configuration file::
zone:
- domain: whoami.domain.example
file: "/path/to/whoami.domain.example"
module: mod-whoami
zone:
- domain: whoami6.domain.example
file: "/path/to/whoami6.domain.example"
module: mod-whoami
The whoami.domain.example zone file example:
.. code-block:: none
$TTL 1
@ SOA (
whoami.domain.example. ; MNAME
hostmaster.domain.example. ; RNAME
2016051300 ; SERIAL
86400 ; REFRESH
86400 ; RETRY
86400 ; EXPIRE
1 ; MINIMUM
)
$TTL 86400
@ NS ns1.whoami.domain.example.
@ NS ns2.whoami.domain.example.
@ NS ns3.whoami.domain.example.
@ NS ns4.whoami.domain.example.
ns1 A 198.51.100.53
ns2 A 192.0.2.53
ns3 A 203.0.113.53
ns4 A 198.19.123.53
The whoami6.domain.example zone file example:
.. code-block:: none
$TTL 1
@ SOA (
whoami6.domain.example. ; MNAME
hostmaster.domain.example. ; RNAME
2016051300 ; SERIAL
86400 ; REFRESH
86400 ; RETRY
86400 ; EXPIRE
1 ; MINIMUM
)
$TTL 86400
@ NS ns1.whoami6.domain.example.
@ NS ns2.whoami6.domain.example.
@ NS ns3.whoami6.domain.example.
@ NS ns4.whoami6.domain.example.
ns1 AAAA 2001:db8:100::53
ns2 AAAA 2001:db8:200::53
ns3 AAAA 2001:db8:300::53
ns4 AAAA 2001:db8:400::53
The parent domain would then delegate whoami.domain.example to
ns[1-4].whoami.domain.example and whoami6.domain.example to
ns[1-4].whoami6.domain.example, and include the corresponding A-only or
AAAA-only glue records.
.. NOTE::
This module is not configurable.