diff options
Diffstat (limited to 'doc/kresd.8.in')
| -rw-r--r-- | doc/kresd.8.in | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/doc/kresd.8.in b/doc/kresd.8.in new file mode 100644 index 0000000..0fa8cc9 --- /dev/null +++ b/doc/kresd.8.in @@ -0,0 +1,172 @@ +.TH "kresd" "8" "@DATE@" "CZ.NIC" "Knot 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 @VERSION@ full caching resolver. +.SH "SYNOPSIS" +.B kresd +.RB [ \-a | \-\-addr +.IR addr[@port] ] +.RB [ \-t | \-\-tls +.IR addr[@port] ] +.RB [ \-S | \-\-fd +.IR fd ] +.RB [ \-T | \-\-tlsfd +.IR fd ] +.RB [ \-c | \-\-config +.IR config ] +.RB [ \-k | \-\-keyfile +.IR keyfile ] +.RB [ \-K | \-\-keyfile\-ro +.IR keyfile ] +.RB [ \-m | \-\-moduledir +.IR path ] +.RB [ \-f | \-\-forks +.IR N ] +.RB [ \-q | \-\-quiet ] +.RB [ \-v | \-\-verbose ] +.RB [ \-V | \-\-version ] +.RB [ \-h | \-\-help ] +.IR [rundir] +.SH "DESCRIPTION" +.B Knot 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 https://knot-resolver.readthedocs.io +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]\fR, \fB\-\-addr=\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 \-t\fI addr[@port]\fR, \fB\-\-tls=\fI<addr[@port]> +Listen using TLS on given address (and port) pair. If no port is +given, \fI853\fR is used as a default. Option may be passed multiple +times to listen on more addresses. +.TP +.B \-S\fI fd\fR, \fB\-\-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 \-T\fI fd\fR, \-\-tlsfd=\fI<fd> +Listen using TLS on given file descriptor(s), passed by supervisor. +Option may be passed multiple times to listen on more file descriptors. +.TP +.B \-c\fI config\fR, \fB\-\-config=\fI<config> +Set the config file with settings for kresd to read instead of reading the +file at the default location (\fIconfig\fR). The syntax is +described in \fIdaemon/README.md\fR. +.TP +.B \-k\fI keyfile\fR, \fB\-\-keyfile=\fI<keyfile> +(Recommended!) Automatically managed root trust anchors file. +Root trust anchors in this file are managed using standard RFC 5011 (Automated Updates of DNS Security Trust Anchors). +Kresd needs write access to the directory containing the keyfile. + +If the file does not exist, it will be automatically boostrapped from IANA using HTTPS protocol +and warning that you need to to check the key before trusting it will be issued. + +The file contains DNSKEY/DS records in presentation format, +and is compatible with Unbound and BIND 9 root key files. +.TP +.B \-K\fI keyfile\fR, \fB\-\-keyfile\-ro=\fI<keyfile> +(Discouraged) Static root trust anchors file. The file is not updated by kresd. Use of this option is discouraged because it will break your installation when the trust anchor key changes! + +Default: "@KEYFILE_DEFAULT@" (can be empty if your distribution did not provide one) +.TP +.B \-m\fI path\fR, \fB\-\-moduledir=\fI<path> +Override the directory that is searched for modules. Default: @MODULEDIR@ +.TP +.B \-f\fI N\fR, \fB\-\-forks=\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. + +When socket-activated and supervised by systemd or the equivalent, kresd defaults to +--forks=1, and must not be set to any other value. If you want multiple concurrent +processes supervised in this way, they should be supervised independently (see +\fBkresd.systemd(7)\fR). +.TP +.B \-q\fR, \fB\-\-quiet +Daemon will refrain from printing the command prompt. +.TP +.B \-v\fR, \fB\-\-verbose +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 \-h +Show short commandline option help. +.TP +.B \-V +Show the version. +.SH "SEE ALSO" +\fIkresd.systemd(7)\fR, +\fIhttps://knot-resolver.readthedocs.io\fR +.SH "AUTHORS" +.B kresd +developers are mentioned in the AUTHORS file in the distribution. |