Adding upstream version 3.2.1.upstream/3.2.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.