Commit 07a36b24 authored by Marek Vavrusa's avatar Marek Vavrusa

version bump, added kresd(8) man, updated doc

parent bb0c707f
......@@ -6,7 +6,6 @@
*.dylib.*
*.lo
*.la
*.in
*.Plo
*.swp
*.d
......
......@@ -6,21 +6,18 @@
[![Documentation Status](https://readthedocs.org/projects/knot-resolver/badge/?version=latest)](https://readthedocs.org/projects/knot-resolver/?badge=latest)
The Knot DNS Resolver is a caching full resolver implementation written in C and [LuaJIT][luajit], including both a resolver
library and a daemon. Modular architecture of the library keeps the core tiny and efficient, and provides
a state-machine like API for extensions. There are three built-in modules - *iterator*, *cache*, *validator*, and many external.
The Knot DNS Resolver is a caching full resolver implementation written in C and [LuaJIT][luajit], both a resolver library and a daemon. The core architecture is tiny and efficient, and provides a foundation and
a state-machine like API for extensions. There are three of those built-in - *iterator*, *cache*, *validator*, and most of the [rich features](http://knot-resolver.readthedocs.org/en/latest/modules.html) are written in LuaJIT, Go and C. Batteries are included, but optional.
The Lua modules, switchable and shareable cache, and fast FFI bindings makes it great to tap into resolution process, or be used for your recursive DNS service. It's the [OpenResty][openresty] of DNS.
The LuaJIT modules, support for DNS privacy and DNSSEC, and persistent cache with low memory footprint make it a great personal DNS resolver or a research tool to tap into DNS data. TL;DR it's the [OpenResty][openresty] of DNS.
The server adopts a [different scaling strategy][scaling] than the rest of the DNS recursors - no threading, shared-nothing architecture (except MVCC cache that may be shared). You can start and stop additional nodes depending on the contention without downtime.
Several cache backends (LMDB, Redis and Memcached), strong filtering rules, and auto-configuration with etcd make it a great large-scale resolver solution.
### Try it out?
Keep in mind that the Knot DNS Resolver is in beta. While it's being tested by the [DNS test harness][deckard], we'll be super glad to hear out your feedback!
The server adopts a [different scaling strategy][scaling] than the rest of the DNS recursors - no threading, shared-nothing architecture (except MVCC cache that may be shared) that allows you to pin instances on available CPU cores and grow by self-replication. You can start and stop additional nodes depending on the contention without downtime.
### Building from sources
The Knot DNS Resolver [depends][depends] on the 2.0.1 version of the Knot DNS library, [LuaJIT][luajit] and [libuv][libuv].
The Knot DNS Resolver [depends][depends] on the 2.1 version of the Knot DNS library, [LuaJIT][luajit] and [libuv][libuv].
See the [Building project][depends] documentation page for more information.
### Docker image
......
# Project
MAJOR := 1
MINOR := 0
PATCH := 0-beta4
PATCH := 0
ABIVER := 1
BUILDMODE := dynamic
HARDENING := yes
......@@ -25,3 +25,6 @@ INSTALL := install
BUILD_LDFLAGS += $(LDFLAGS)
BUILD_CFLAGS := $(CFLAGS) -std=c99 -D_GNU_SOURCE -D_FORTIFY_SOURCE=2 -Wno-unused -Wtype-limits -Wformat -Wformat-security -Wall -I$(abspath .) -I$(abspath lib/generic) -I$(abspath contrib)
BUILD_CFLAGS += -DPACKAGE_VERSION="\"$(MAJOR).$(MINOR).$(PATCH)\"" -DPREFIX="\"$(PREFIX)\"" -DMODULEDIR="\"$(MODULEDIR)\"" -DETCDIR="\"$(ETCDIR)\""
ifeq (,$(findstring -O,$(CFLAGS)))
BUILD_CFLAGS += -O2
endif
\ No newline at end of file
......@@ -209,9 +209,7 @@ This is useful if you're writing a module with a layer, that evaluates an answer
Dynamic configuration
^^^^^^^^^^^^^^^^^^^^^
Knowing that the the configuration is a Lua in disguise enables you to write dynamic rules, and also avoid
repetition and templating. This is unavoidable with static configuration, e.g. when you want to configure
each node a little bit differently.
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.
.. code-block:: lua
......
......@@ -32,8 +32,13 @@ $(eval $(call make_bin,kresd,daemon,yes))
endif
# Targets
date := $(shell date +%F)
daemon: $(kresd)
daemon-install: kresd-install bindings-install
ifneq ($(SED),)
$(SED) -e "s/@VERSION@/$(MAJOR).$(MINOR).$(PATCH)/" -e "s/@DATE@/$(date)/" doc/kresd.8.in > doc/kresd.8
$(INSTALL) -m 0644 doc/kresd.8 $(DESTDIR)$(PREFIX)/share/man/man8/
endif
daemon-clean: kresd-clean
@$(RM) daemon/lua/*.inc
......
.TH "kresd" "8" "@DATE@" "CZ.NIC" "Knot DNS Resolver @VERSION@"
.\"
.\" kresd.8 -- kresd daemon manpage
.\"
.\" Copyright (c) 2016, CZ.NIC. All rights reserved.
.\"
.\" See COPYING for the license.
.\"
.\"
.SH "NAME"
.B kresd
\- Knot DNS @VERSION@ full caching resolver.
.SH "SYNOPSIS"
.B kresd
.RB [ \-a
.IR addr[#port] ]
.RB [ \-\-fd=\fIfd\fR ]
.RB [ \-c
.IR config ]
.RB [ \-k
.IR keyfile ]
.RB [ \-f
.IR N ]
.RB [ \-q ]
.RB [ \-v ]
.RB [ \-V ]
.RB [ \-h ]
.IR [rundir]
.SH "DESCRIPTION"
.B Knot DNS Resolver is a DNSSEC-enabled full caching resolver.
.P
Default mode of operation: when it receives a DNS query it iteratively
asks authoritative nameservers starting from root zone (.) and ending
with a nameservers authoritative for queried name. Automatic DNSSEC means
verification of integrity of authoritative responses by following
keys and signatures starting from root. Root trust anchor is automatically
bootstrapped from IANA, or you can provide a file with root trust anchors
(same format as Unbound or BIND9 root keys file).
The daemon also caches intermediate answers into cache, which by default
uses LMDB memory-mapped database. This has a significant advantage over
in-memory caches as the process may be stopped and restarted without
loss of cache entries. In multi-user scenario a shared cache
is potential privacy/security issue, with kresd each user can have resolver cache
in their private directory and use it in similar fashion to keychain.
By default, no configuration is needed, only a directory where the daemon can store
runtime data (cache, control sockets, ...)
.P
To use a locally running
.B kresd
for resolving put
.sp
.RS 6n
nameserver 127.0.0.1
.RE
.sp
into
.IR resolv.conf (5)
and start
.B kresd
.PP
.nf
.RS 6n
$ kresd -a 127.0.0.1 -k root.keys
[system] interactive mode
>
.RE
.fi
.PP
.P
The daemon may be configured also as a plain forwarder using query policies, that requires
creating a file
.B config
in daemon runtime directory. See \fIdaemon/README.md\fR for more information about interacting
with CLI and configuration file options, or visit
.b http://knot-resolver.rtfd.org online documentation.
.PP
.nf
.RS 6n
# Create a basic forwarder configuration
$ cat << EOF > config
modules = { 'policy' }
policy:add(policy.all(policy.FORWARD('192.168.1.1')))
$ kresd -a 127.0.0.1 -k root.keys
EOF
.RE
.fi
.PP
.P
The available CLI options are:
.TP
.B \-a\fI addr[#port]
Listen on given address (and port) pair. If no port is given, \fI53\fR is used as a default.
Option may be passed multiple times to listen on more addresses.
.TP
.B \-S\fI fd\fR, \-\-fd=\fI<fd>
Listen on given file descriptor(s), passed by supervisor.
Option may be passed multiple times to listen on more file descriptors.
.TP
.B \-k\fI keyfile
Use given for keeping root trust anchors. If the file doesn't exist, it will be
automatically boostrapped from IANA and warning for you will be issued to check it
before trusting it. The file contains DNSKEY/DS records in presentation format,
and is compatible with Unbound or BIND9 root key files.
.TP
.B \-f\fI N
With this option, the daemon is started in non-interactive mode and instead creates a
UNIX socket in \fIrundir\fR that the operator can connect to for interactive session.
A number greater than 1 forks the daemon N times, all forks will bind to same addresses
and the kernel will load-balance between them on Linux with \fISO_REUSEPORT\fR support.
.TP
.B \-q
Daemon will refrain from printing any informative messages, not even a prompt.
.TP
.B \-v
Increase verbosity. If given multiple times, more information is logged.
This is in addition to the verbosity (if any) from the config file.
.TP
.B \-c\fI config
Set the config file with settings for unbound to read instead of reading the
file at the default location (\fIconfig\fR). The syntax is
described in \fIdaemon/README.md\fR.
.TP
.B \-h
Show the version and commandline option help.
.TP
.B \-V
Show the version.
.SH "SEE ALSO"
\fIdaemon/README.md\fR,
\fIhttp://knot-resolver.rtfd.org\fR
.SH "AUTHORS"
.B kresd
developers are mentioned in the AUTHORS file in the distribution.
\ No newline at end of file
......@@ -7,6 +7,7 @@ CCLD := $(CC)
CGO := go tool cgo
GO := go
CAT := cat
SED := sed
LIBEXT := .so
MODEXT := $(LIBEXT)
AREXT := .a
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment