diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man/kdig.1in | 378 | ||||
| -rw-r--r-- | doc/man/keymgr.8in | 286 | ||||
| -rw-r--r-- | doc/man/khost.1in | 152 | ||||
| -rw-r--r-- | doc/man/kjournalprint.8in | 92 | ||||
| -rw-r--r-- | doc/man/knot.conf.5in | 1401 | ||||
| -rw-r--r-- | doc/man/knotc.8in | 324 | ||||
| -rw-r--r-- | doc/man/knotd.8in | 76 | ||||
| -rw-r--r-- | doc/man/knsec3hash.1in | 87 | ||||
| -rw-r--r-- | doc/man/knsupdate.1in | 198 | ||||
| -rw-r--r-- | doc/man/kzonecheck.1in | 73 | ||||
| -rw-r--r-- | doc/man_kdig.rst | 324 | ||||
| -rw-r--r-- | doc/man_keymgr.rst | 216 | ||||
| -rw-r--r-- | doc/man_khost.rst | 102 | ||||
| -rw-r--r-- | doc/man_kjournalprint.rst | 58 | ||||
| -rw-r--r-- | doc/man_knotc.rst | 274 | ||||
| -rw-r--r-- | doc/man_knotd.rst | 48 | ||||
| -rw-r--r-- | doc/man_knsec3hash.rst | 49 | ||||
| -rw-r--r-- | doc/man_knsupdate.rst | 164 | ||||
| -rw-r--r-- | doc/man_kzonecheck.rst | 45 |
19 files changed, 4347 insertions, 0 deletions
diff --git a/doc/man/kdig.1in b/doc/man/kdig.1in new file mode 100644 index 0000000..8bb2d01 --- /dev/null +++ b/doc/man/kdig.1in @@ -0,0 +1,378 @@ +.\" Man page generated from reStructuredText. +. +.TH "KDIG" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +kdig \- Advanced DNS lookup utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBkdig\fP [\fIcommon\-settings\fP] [\fIquery\fP [\fIsettings\fP]]... +.sp +\fBkdig\fP \fB\-h\fP +.SH DESCRIPTION +.sp +This utility sends one or more DNS queries to a nameserver. Each query can have +individual \fIsettings\fP, or it can be specified globally via \fIcommon\-settings\fP, +which must precede \fIquery\fP specification. +.SS Parameters +.INDENT 0.0 +.TP +\fIquery\fP +\fIname\fP | \fB\-q\fP \fIname\fP | \fB\-x\fP \fIaddress\fP | \fB\-G\fP \fItapfile\fP +.TP +\fIcommon\-settings\fP, \fIsettings\fP +[\fIquery_class\fP] [\fIquery_type\fP] [\fB@\fP\fIserver\fP]... [\fIoptions\fP] +.TP +\fIname\fP +Is a domain name that is to be looked up. +.TP +\fIserver\fP +Is a domain name or an IPv4 or IPv6 address of the nameserver to send a query +to. An additional port can be specified using address:port ([address]:port +for IPv6 address), address@port, or address#port notation. If no server is +specified, the servers from \fB/etc/resolv.conf\fP are used. +.UNINDENT +.sp +If no arguments are provided, \fBkdig\fP sends NS query for the root +zone. +.SS Query classes +.sp +A \fIquery_class\fP can be either a DNS class name (IN, CH) or generic class +specification \fBCLASS\fP\fIXXXXX\fP where \fIXXXXX\fP is a corresponding decimal +class number. The default query class is IN. +.SS Query types +.sp +A \fIquery_type\fP can be either a DNS resource record type +(A, AAAA, NS, SOA, DNSKEY, ANY, etc.) or one of the following: +.INDENT 0.0 +.TP +\fBTYPE\fP\fIXXXXX\fP +Generic query type specification where \fIXXXXX\fP is a corresponding decimal +type number. +.TP +\fBAXFR\fP +Full zone transfer request. +.TP +\fBIXFR=\fP\fIserial\fP +Incremental zone transfer request for specified starting SOA serial number. +.TP +\fBNOTIFY=\fP\fIserial\fP +Notify message with a SOA serial hint specified. +.TP +\fBNOTIFY\fP +Notify message with a SOA serial hint unspecified. +.UNINDENT +.sp +The default query type is A. +.SS Options +.INDENT 0.0 +.TP +\fB\-4\fP +Use the IPv4 protocol only. +.TP +\fB\-6\fP +Use the IPv6 protocol only. +.TP +\fB\-b\fP \fIaddress\fP +Set the source IP address of the query to \fIaddress\fP\&. The address must be a +valid address for local interface or :: or 0.0.0.0. An optional port +can be specified in the same format as the \fIserver\fP value. +.TP +\fB\-c\fP \fIclass\fP +An explicit \fIquery_class\fP specification. See possible values above. +.TP +\fB\-d\fP +Enable debug messages. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-k\fP \fIkeyfile\fP +Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The +file must contain the key in the same format as accepted by the +\fB\-y\fP option. +.TP +\fB\-p\fP \fIport\fP +Set the nameserver port number or service name to send a query to. The default +port is 53. +.TP +\fB\-q\fP \fIname\fP +Set the query name. An explicit variant of \fIname\fP specification. If no \fIname\fP +is provided, empty question section is set. +.TP +\fB\-t\fP \fItype\fP +An explicit \fIquery_type\fP specification. See possible values above. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.TP +\fB\-x\fP \fIaddress\fP +Send a reverse (PTR) query for IPv4 or IPv6 \fIaddress\fP\&. The correct name, class +and type is set automatically. +.TP +\fB\-y\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP +Use the TSIG key named \fIname\fP to authenticate the request. The \fIalg\fP +part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies +the shared secret encoded in Base64. +.TP +\fB\-E\fP \fItapfile\fP +Export a dnstap trace of the query and response messages received to the +file \fItapfile\fP\&. +.TP +\fB\-G\fP \fItapfile\fP +Generate message output from a previously saved dnstap file \fItapfile\fP\&. +.TP +\fB+\fP[\fBno\fP]\fBmultiline\fP +Wrap long records to more lines and improve human readability. +.TP +\fB+\fP[\fBno\fP]\fBshort\fP +Show record data only. +.TP +\fB+\fP[\fBno\fP]\fBgeneric\fP +Use the generic representation format when printing resource record types +and data. +.TP +\fB+\fP[\fBno\fP]\fBcrypto\fP +Display the DNSSEC keys and signatures values in hexdump, instead of omitting them. +.TP +\fB+\fP[\fBno\fP]\fBaaflag\fP +Set the AA flag. +.TP +\fB+\fP[\fBno\fP]\fBtcflag\fP +Set the TC flag. +.TP +\fB+\fP[\fBno\fP]\fBrdflag\fP +Set the RD flag. +.TP +\fB+\fP[\fBno\fP]\fBrecurse\fP +Same as \fB+\fP[\fBno\fP]\fBrdflag\fP +.TP +\fB+\fP[\fBno\fP]\fBraflag\fP +Set the RA flag. +.TP +\fB+\fP[\fBno\fP]\fBzflag\fP +Set the zero flag bit. +.TP +\fB+\fP[\fBno\fP]\fBadflag\fP +Set the AD flag. +.TP +\fB+\fP[\fBno\fP]\fBcdflag\fP +Set the CD flag. +.TP +\fB+\fP[\fBno\fP]\fBdnssec\fP +Set the DO flag. +.TP +\fB+\fP[\fBno\fP]\fBall\fP +Show all packet sections. +.TP +\fB+\fP[\fBno\fP]\fBqr\fP +Show the query packet. +.TP +\fB+\fP[\fBno\fP]\fBheader\fP +Show the packet header. +.TP +\fB+\fP[\fBno\fP]\fBcomments\fP +Show commented section names. +.TP +\fB+\fP[\fBno\fP]\fBopt\fP +Show the EDNS pseudosection. +.TP +\fB+\fP[\fBno\fP]\fBquestion\fP +Show the question section. +.TP +\fB+\fP[\fBno\fP]\fBanswer\fP +Show the answer section. +.TP +\fB+\fP[\fBno\fP]\fBauthority\fP +Show the authority section. +.TP +\fB+\fP[\fBno\fP]\fBadditional\fP +Show the additional section. +.TP +\fB+\fP[\fBno\fP]\fBtsig\fP +Show the TSIG pseudosection. +.TP +\fB+\fP[\fBno\fP]\fBstats\fP +Show trailing packet statistics. +.TP +\fB+\fP[\fBno\fP]\fBclass\fP +Show the DNS class. +.TP +\fB+\fP[\fBno\fP]\fBttl\fP +Show the TTL value. +.TP +\fB+\fP[\fBno\fP]\fBtcp\fP +Use the TCP protocol (default is UDP for standard query and TCP for AXFR/IXFR). +.TP +\fB+\fP[\fBno\fP]\fBfastopen\fP +Use TCP Fast Open (default with TCP). +.TP +\fB+\fP[\fBno\fP]\fBignore\fP +Don\(aqt use TCP automatically if a truncated reply is received. +.TP +\fB+\fP[\fBno\fP]\fBtls\fP +Use TLS with the Opportunistic privacy profile (\fI\%RFC 7858#section\-4.1\fP). +.TP +\fB+\fP[\fBno\fP]\fBtls\-ca\fP[=\fIFILE\fP] +Use TLS with a certificate validation. Certification authority certificates +are loaded from the specified PEM file (default is system certificate storage +if no argument is provided). +Can be specified multiple times. If the +tls\-hostname option is not provided, +the name of the target server (if specified) is used for strict authentication. +.TP +\fB+\fP[\fBno\fP]\fBtls\-pin\fP=\fIBASE64\fP +Use TLS with the Out\-of\-Band key\-pinned privacy profile (\fI\%RFC 7858#section\-4.2\fP). +The PIN must be a Base64 encoded SHA\-256 hash of the X.509 SubjectPublicKeyInfo. +Can be specified multiple times. +.TP +\fB+\fP[\fBno\fP]\fBtls\-hostname\fP=\fISTR\fP +Use TLS with a remote server hostname check. +.TP +\fB+\fP[\fBno\fP]\fBtls\-sni\fP=\fISTR\fP +Use TLS with a Server Name Indication. +.TP +\fB+\fP[\fBno\fP]\fBnsid\fP +Request the nameserver identifier (NSID). +.TP +\fB+\fP[\fBno\fP]\fBbufsize\fP=\fIB\fP +Set EDNS buffer size in bytes (default is 512 bytes). +.TP +\fB+\fP[\fBno\fP]\fBpadding\fP[=\fIB\fP] +Use EDNS(0) padding option to pad queries, optionally to a specific +size. The default is to pad queries with a sensible amount when using ++tls, and not to pad at all when queries are sent without TLS. With +no argument (i.e., just +padding) pad every query with a sensible +amount regardless of the use of TLS. With +nopadding, never pad. +.TP +\fB+\fP[\fBno\fP]\fBalignment\fP[=\fIB\fP] +Align the query to B\-byte\-block message using the EDNS(0) padding option +(default is no or 128 if no argument is specified). +.TP +\fB+\fP[\fBno\fP]\fBsubnet\fP=\fISUBN\fP +Set EDNS(0) client subnet SUBN=addr/prefix. +.TP +\fB+\fP[\fBno\fP]\fBedns\fP[=\fIN\fP] +Use EDNS version (default is 0). +.TP +\fB+\fP[\fBno\fP]\fBtimeout\fP=\fIT\fP +Set the wait\-for\-reply interval in seconds (default is 5 seconds). This timeout +applies to each query attempt. +.TP +\fB+\fP[\fBno\fP]\fBretry\fP=\fIN\fP +Set the number (>=0) of UDP retries (default is 2). This doesn\(aqt apply to +AXFR/IXFR. +.TP +\fB+\fP[\fBno\fP]\fBcookie\fP=\fIHEX\fP +Attach EDNS(0) cookie to the query. +.TP +\fB+\fP[\fBno\fP]\fBbadcookie\fP +Repeat a query with the correct cookie. +.TP +\fB+\fP[\fBno\fP]\fBednsopt\fP[=\fICODE\fP[:\fIHEX\fP]] +Send custom EDNS option. The \fICODE\fP is EDNS option code in decimal, \fIHEX\fP +is an optional hex encoded string to use as EDNS option value. This argument +can be used multiple times. +noednsopt clears all EDNS options specified by ++ednsopt. +.TP +\fB+noidn\fP +Disable the IDN transformation to ASCII and vice versa. IDNA2003 support depends +on libidn availability during project building! +.UNINDENT +.SH NOTES +.sp +Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously. +.sp +Dnssec\-keygen keyfile format is not supported. Use \fBkeymgr(8)\fP instead. +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Get A records for example.com: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig example.com A +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Perform AXFR for zone example.com from the server 192.0.2.1: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig example.com \-t AXFR @192.0.2.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 3. 3 +Get A records for example.com from 192.0.2.1 and reverse lookup for address +2001:DB8::1 from 192.0.2.2. Both using the TCP protocol: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig +tcp example.com \-t A @192.0.2.1 \-x 2001:DB8::1 @192.0.2.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 4. 3 +Get SOA record for example.com, use TLS, use system certificates, check +for specified hostname, check for certificate pin, and print additional +debug info: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig \-d @185.49.141.38 +tls\-ca +tls\-host=getdnsapi.net \e + +tls\-pin=foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S= soa example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fBkhost(1)\fP, \fBknsupdate(1)\fP, \fBkeymgr(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/keymgr.8in b/doc/man/keymgr.8in new file mode 100644 index 0000000..78a322f --- /dev/null +++ b/doc/man/keymgr.8in @@ -0,0 +1,286 @@ +.\" Man page generated from reStructuredText. +. +.TH "KEYMGR" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +keymgr \- Knot DNS key management utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBkeymgr\fP \fIbasic_option\fP [\fIparameters\fP\&...] +.sp +\fBkeymgr\fP [\fIconfig_option\fP \fIconfig_storage\fP] \fIzone\fP \fIcommand\fP \fIargument\fP\&... +.SH DESCRIPTION +.sp +The \fBkeymgr\fP utility serves for manual key management in Knot DNS server. +.sp +Functions for DNSSEC keys and KASP (Key And Signature Policy) +management are provided. +.sp +The DNSSEC and KASP configuration is stored in a so called KASP database. +The database is backed by LMDB. +.SS Basic options +.INDENT 0.0 +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.TP +\fB\-t\fP, \fB\-\-tsig\fP \fItsig_name\fP [\fItsig_algorithm\fP] [\fItsig_bits\fP] +Generates a TSIG key. TSIG algorithm can be specified by string (default: hmac\-sha256), +bit length of the key by number (default: optimal length given by algorithm). The generated +TSIG key is only displayed on \fIstdout\fP: the command does not create a file, nor include the +key in a keystore. +.UNINDENT +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.TP +\fB\-d\fP, \fB\-\-dir\fP \fIpath\fP +Use specified KASP database path and default configuration. +.UNINDENT +.SS Commands +.INDENT 0.0 +.TP +\fBlist\fP [\fItimestamp_format\fP] +Prints the list of key IDs and parameters of keys belonging to the zone. +.TP +\fBgenerate\fP [\fIarguments\fP\&...] +Generates new DNSSEC key and stores it in KASP database. Prints the key ID. +This action takes some number of arguments (see below). Values for unspecified arguments are taken +from corresponding policy (if \fI\-c\fP or \fI\-C\fP options used) or from Knot policy defaults. +.TP +\fBimport\-bind\fP \fIBIND_key_file\fP +Imports a BIND\-style key into KASP database (converting it to PEM format). +Takes one argument: path to BIND key file (private or public, but both MUST exist). +.TP +\fBimport\-pub\fP \fIBIND_pubkey_file\fP +Imports a public key into KASP database. This key won\(aqt be rollovered nor used for signing. +Takes one argument: path to BIND public key file. +.TP +\fBimport\-pem\fP \fIPEM_file\fP [\fIarguments\fP\&...] +Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be +specified (mainly algorithm, timers...) because they are not contained in the PEM format. +.TP +\fBimport\-pkcs11\fP \fIkey_id\fP [\fIarguments\fP\&...] +Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be +specified (mainly algorithm, timers...) because they are not available. In fact, no key +data is imported, only KASP database metadata is created. +.TP +\fBnsec3\-salt\fP [\fInew_salt\fP] +Prints the current NSEC3 salt used for signing. If \fInew_salt\fP is specified, the salt is overwritten. +The salt is printed and expected in hexadecimal, or dash if empty. +.TP +\fBset\fP \fIkey_spec\fP [\fIarguments\fP\&...] +Changes a timing argument (or ksk/zsk) of an existing key to a new value. \fIKey_spec\fP is either the +key tag or a prefix of the key ID; \fIarguments\fP are like for \fBgenerate\fP, but just the related ones. +.TP +\fBds\fP [\fIkey_spec\fP] +Generate DS record (all digest algorithms together) for specified key. \fIKey_spec\fP +is like for \fBset\fP, if unspecified, all KSKs are used. +.TP +\fBdnskey\fP [\fIkey_spec\fP] +Generate DNSKEY record for specified key. \fIKey_spec\fP +is like for \fBds\fP, if unspecified, all KSKs are used. +.TP +\fBdelete\fP \fIkey_spec\fP +Remove the specified key from zone. If the key was not shared, it is also deleted from keystore. +.TP +\fBshare\fP \fIkey_ID\fP +Import a key (specified by full key ID) from another zone as shared. After this, the key is +owned by both zones equally. +.UNINDENT +.SS Generate arguments +.sp +Arguments are separated by space, each of them is in format \(aqname=value\(aq. +.INDENT 0.0 +.TP +\fBalgorithm\fP +Either an algorithm number (e.g. 14), or text name without dashes (e.g. ECDSAP384SHA384). +.TP +\fBsize\fP +Key length in bits. +.TP +\fBksk\fP +If set to \fByes\fP, the key will be used for signing DNSKEY rrset. The generated key will also +have the Secure Entry Point flag set to 1. +.TP +\fBzsk\fP +If set to \fByes\fP, the key will be used for signing zone (except DNSKEY rrset). This flag can +be set concurrently with the \fBksk\fP flag. +.TP +\fBsep\fP +Overrides the standard setting of the Secure Entry Point flag for the generated key. +.UNINDENT +.sp +The following arguments are timestamps of key lifetime: +.INDENT 0.0 +.TP +\fBcreated\fP +Key created. +.TP +\fBpre_active\fP +Key started to be used for signing, not published (only for algorithm rollover). +.TP +\fBpublish\fP +Key published. +.TP +\fBready\fP +Key used for signing and submitted to the parent zone (only for KSK). +.TP +\fBactive\fP +Key used for signing. +.TP +\fBpost_active\fP +Key still used for singing, but another key is active (only for KSK). +.TP +\fBretire_active\fP +Key no longer published, but still used for signing (only for algorithm rollover). +.TP +\fBretire\fP +Key still published, but no longer used for signing. +.TP +\fBremove\fP +Key deleted. +.UNINDENT +.SS Timestamps +.INDENT 0.0 +.TP +0 +Zero timestamp means infinite future. +.TP +\fIUNIX_time\fP +Positive number of seconds since 1970 UTC. +.TP +\fIYYYYMMDDHHMMSS\fP +Date and time in this format without any punctuation. +.TP +\fIrelative_timestamp\fP +A sign character (\fB+\fP, \fB\-\fP), a number, and an optional time unit +(\fBy\fP, \fBmo\fP, \fBd\fP, \fBh\fP, \fBmi\fP, \fBs\fP). The default unit is one second. +E.g. +1mi, \-2mo. +.UNINDENT +.SS Output timestamp formats +.INDENT 0.0 +.TP +(none) +The timestamps are printed as UNIX timestamp. +.TP +\fBhuman\fP +The timestamps are printed relatively to now using time units (e.g. \-2y5mo, +1h13s). +.TP +\fBiso\fP +The timestamps are printed in the ISO8601 format (e.g. 2016\-12\-31T23:59:00). +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Generate new TSIG key: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr \-t my_name hmac\-sha384 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Generate new DNSSEC key: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \e + ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 3. 3 +Import a DNSSEC key from BIND: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. import\-bind ~/bind/Kharbinge4d5.+007+63089.key +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 4. 3 +Configure key timing: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 5. 3 +Share a KSK from another zone: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 6781\fP \- DNSSEC Operational Practices. +\fI\%RFC 7583\fP \- DNSSEC Key Rollover Timing Considerations. +.sp +\fBknot.conf(5)\fP, +\fBknotc(8)\fP, +\fBknotd(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/khost.1in b/doc/man/khost.1in new file mode 100644 index 0000000..d102136 --- /dev/null +++ b/doc/man/khost.1in @@ -0,0 +1,152 @@ +.\" Man page generated from reStructuredText. +. +.TH "KHOST" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +khost \- Simple DNS lookup utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBkhost\fP [\fIoptions\fP] \fIname\fP [\fIserver\fP] +.SH DESCRIPTION +.sp +This utility sends a DNS query for the \fIname\fP to the \fIserver\fP and prints a reply +in more user\-readable form. For more advanced DNS queries use \fBkdig\fP +instead. +.SS Parameters +.INDENT 0.0 +.TP +\fIname\fP +Is a domain name that is to be looked up. If the \fIname\fP is IPv4 or IPv6 +address the PTR query type is used. +.TP +\fIserver\fP +Is a name or an address of the nameserver to send a query to. The address +can be specified using [address]:port notation. If no server is specified, +the servers from \fB/etc/resolv.conf\fP are used. +.UNINDENT +.sp +If no arguments are provided, \fBkhost\fP prints a short help. +.SS Options +.INDENT 0.0 +.TP +\fB\-4\fP +Use the IPv4 protocol only. +.TP +\fB\-6\fP +Use the IPv6 protocol only. +.TP +\fB\-a\fP +Send ANY query with verbose mode. +.TP +\fB\-d\fP +Enable debug messages. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-r\fP +Disable recursion. +.TP +\fB\-T\fP +Use the TCP protocol. +.TP +\fB\-v\fP +Enable verbose output. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.TP +\fB\-w\fP +Wait forever for the reply. +.TP +\fB\-c\fP \fIclass\fP +Set the query class (e.g. CH, CLASS4). The default class is IN. +.TP +\fB\-t\fP \fItype\fP +Set the query type (e.g. NS, IXFR=12345, TYPE65535). The default is to send 3 +queries (A, AAAA and MX). +.TP +\fB\-R\fP \fIretries\fP +The number (>=0) of UDP retries to query a nameserver. The default is 1. +.TP +\fB\-W\fP \fIwait\fP +The time to wait for a reply in seconds. This timeout applies to each query +try. The default is 2 seconds. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Get the A, AAAA and MX records for example.com: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ khost example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Get the reverse record for address 192.0.2.1: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ khost 192.0.2.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 3. 3 +Perform a verbose zone transfer for zone example.com: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ khost \-t AXFR \-v example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fBkdig(1)\fP, \fBknsupdate(1)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kjournalprint.8in b/doc/man/kjournalprint.8in new file mode 100644 index 0000000..796e54f --- /dev/null +++ b/doc/man/kjournalprint.8in @@ -0,0 +1,92 @@ +.\" Man page generated from reStructuredText. +. +.TH "KJOURNALPRINT" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +kjournalprint \- Knot DNS journal print utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBkjournalprint\fP [\fIoptions\fP] \fIjournal_db\fP \fIzone_name\fP +.SH DESCRIPTION +.sp +The program prints zone history stored in a journal database. As default, +changes are colored for terminal. +.SS Options +.INDENT 0.0 +.TP +\fB\-l\fP, \fB\-\-limit\fP \fIlimit\fP +Limits the number of displayed changes. +.TP +\fB\-d\fP, \fB\-\-debug\fP +Debug mode brief output. +.TP +\fB\-n\fP, \fB\-\-no\-color\fP +Removes changes coloring. +.TP +\fB\-z\fP, \fB\-\-zone\-list\fP +Instead of reading jurnal, display the list of zones in the DB. +(\fIzone_name\fP not needed) +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.UNINDENT +.SS Parameters +.INDENT 0.0 +.TP +\fIjournal_db\fP +A path to the journal database. +.TP +\fIzone_name\fP +A name of the zone to print the history for. +.UNINDENT +.SH EXAMPLES +.sp +Last (most recent) 5 changes without colors: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kjournalprint \-nl 5 /var/lib/knot/journal example.com. +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in new file mode 100644 index 0000000..9eac7bc --- /dev/null +++ b/doc/man/knot.conf.5in @@ -0,0 +1,1401 @@ +.\" Man page generated from reStructuredText. +. +.TH "KNOT.CONF" "5" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knot.conf \- Knot DNS configuration file +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH DESCRIPTION +.sp +Configuration files for Knot DNS use simplified YAML format. Simplified means +that not all of the features are supported. +.sp +For the description of configuration items, we have to declare a meaning of +the following symbols: +.INDENT 0.0 +.IP \(bu 2 +\fIINT\fP – Integer +.IP \(bu 2 +\fISTR\fP – Textual string +.IP \(bu 2 +\fIHEXSTR\fP – Hexadecimal string (with \fB0x\fP prefix) +.IP \(bu 2 +\fIBOOL\fP – Boolean value (\fBon\fP/\fBoff\fP or \fBtrue\fP/\fBfalse\fP) +.IP \(bu 2 +\fITIME\fP – Number of seconds, an integer with possible time multiplier suffix +(\fBs\fP ~ 1, \fBm\fP ~ 60, \fBh\fP ~ 3600 or \fBd\fP ~ 24 * 3600) +.IP \(bu 2 +\fISIZE\fP – Number of bytes, an integer with possible size multiplier suffix +(\fBB\fP ~ 1, \fBK\fP ~ 1024, \fBM\fP ~ 1024^2 or \fBG\fP ~ 1024^3) +.IP \(bu 2 +\fIBASE64\fP – Base64 encoded string +.IP \(bu 2 +\fIADDR\fP – IPv4 or IPv6 address +.IP \(bu 2 +\fIDNAME\fP – Domain name +.IP \(bu 2 +\&... – Multi\-valued item, order of the values is preserved +.IP \(bu 2 +[ ] – Optional value +.IP \(bu 2 +| – Choice +.UNINDENT +.sp +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 +A multi\-valued item can be specified either as a YAML sequence: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +address: [10.0.0.1, 10.0.0.2] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +or as more single\-valued items each on an extra line: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +address: 10.0.0.1 +address: 10.0.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If an item value contains spaces or other special characters, it is necessary +to enclose such value within double quotes \fB"\fP \fB"\fP\&. +.SH COMMENTS +.sp +A comment begins with a \fB#\fP character and is ignored during processing. +Also each configuration section or sequence block allows a permanent +comment using the \fBcomment\fP item which is stored in the server beside the +configuration. +.SH INCLUDES +.sp +Another configuration file or files, matching a pattern, can be included at +the top level in the current file. If the path is not absolute, then it +is considered to be relative to the current file. The pattern can be +an arbitrary string meeting POSIX \fIglob\fP requirements, e.g. dir/*.conf. +Matching files are processed in sorted order. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +include: STR +.ft P +.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. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +server: + identity: [STR] + version: [STR] + nsid: [STR|HEXSTR] + rundir: STR + user: STR[:STR] + pidfile: STR + udp\-workers: INT + tcp\-workers: INT + background\-workers: INT + async\-start: BOOL + tcp\-handshake\-timeout: TIME + tcp\-idle\-timeout: TIME + tcp\-reply\-timeout: TIME + max\-tcp\-clients: INT + max\-udp\-payload: SIZE + max\-ipv4\-udp\-payload: SIZE + max\-ipv6\-udp\-payload: SIZE + edns\-client\-subnet: BOOL + answer\-rotation: BOOL + listen: ADDR[@INT] ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS identity +.sp +An identity of the server returned in the response to the query for TXT +record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (\fI\%RFC 4892\fP). +Set empty value to disable. +.sp +\fIDefault:\fP FQDN hostname +.SS version +.sp +A version of the server software returned in the response to the query +for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS +class (\fI\%RFC 4892\fP). Set empty value to disable. +.sp +\fIDefault:\fP server version +.SS nsid +.sp +A DNS name server identifier (\fI\%RFC 5001\fP). Set empty value to disable. +.sp +\fIDefault:\fP FQDN hostname +.SS rundir +.sp +A path for storing run\-time data (PID file, unix sockets, etc.). +.sp +\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP) +.SS user +.sp +A system user with an optional system group (\fBuser:group\fP) under which the +server is run after starting and binding to interfaces. Linux capabilities +are employed if supported. +.sp +\fIDefault:\fP root:root +.SS pidfile +.sp +A PID file location. +.sp +\fIDefault:\fP \fI\%rundir\fP/knot.pid +.SS udp\-workers +.sp +A number of UDP workers (threads) used to process incoming queries +over UDP. +.sp +\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs +.SS tcp\-workers +.sp +A number of TCP workers (threads) used to process incoming queries +over TCP. +.sp +\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs +.SS background\-workers +.sp +A number of workers (threads) used to execute background operations (zone +loading, zone updates, etc.). +.sp +\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs +.SS async\-start +.sp +If enabled, server doesn\(aqt wait for the zones to be loaded and starts +responding immediately with SERVFAIL answers until the zone loads. +.sp +\fIDefault:\fP off +.SS tcp\-handshake\-timeout +.sp +Maximum time between newly accepted TCP connection and the first query. +This is useful to disconnect inactive connections faster than connections +that already made at least 1 meaningful query. +.sp +\fIDefault:\fP 5 +.SS tcp\-idle\-timeout +.sp +Maximum idle time between requests on a TCP connection. This also limits +receiving of a single query, each query must be received in this time limit. +.sp +\fIDefault:\fP 20 +.SS tcp\-reply\-timeout +.sp +Maximum time to wait for an outgoing connection or for a reply to an issued +request (SOA, NOTIFY, AXFR...). +.sp +\fIDefault:\fP 10 +.SS max\-tcp\-clients +.sp +A maximum number of TCP clients connected in parallel, set this below the file +descriptor limit to avoid resource exhaustion. +.sp +\fIDefault:\fP 100 +.SS max\-udp\-payload +.sp +Maximum EDNS0 UDP payload size default for both IPv4 and IPv6. +.sp +\fIDefault:\fP 4096 +.SS max\-ipv4\-udp\-payload +.sp +Maximum EDNS0 UDP payload size for IPv4. +.sp +\fIDefault:\fP 4096 +.SS max\-ipv6\-udp\-payload +.sp +Maximum EDNS0 UDP payload size for IPv6. +.sp +\fIDefault:\fP 4096 +.SS edns\-client\-subnet +.sp +Enable or disable EDNS Client Subnet support. If enabled, responses to queries +containing the EDNS Client Subnet option +always contain a valid EDNS Client Subnet option according to \fI\%RFC 7871\fP\&. +.sp +\fIDefault:\fP off +.SS answer\-rotation +.sp +Enable or disable sorted\-rrset rotation in the answer section of normal replies. +The rotation shift is simply determined by a query ID. +.sp +\fIDefault:\fP off +.SS listen +.sp +One or more IP addresses where the server listens for incoming queries. +Optional port specification (default is 53) can be appended to each address +using \fB@\fP separator. Use \fB0.0.0.0\fP for all configured IPv4 addresses or +\fB::\fP for all configured IPv6 addresses. +.sp +\fIDefault:\fP not set +.SH KEY SECTION +.sp +Shared TSIG keys used to authenticate communication with the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key: + \- id: DNAME + algorithm: hmac\-md5 | hmac\-sha1 | hmac\-sha224 | hmac\-sha256 | hmac\-sha384 | hmac\-sha512 + secret: BASE64 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A key name identifier. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value MUST be exactly the same as the name of the TSIG key on the +opposite master/slave server(s). +.UNINDENT +.UNINDENT +.SS algorithm +.sp +A TSIG key algorithm. See +\fI\%TSIG Algorithm Numbers\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBhmac\-md5\fP +.IP \(bu 2 +\fBhmac\-sha1\fP +.IP \(bu 2 +\fBhmac\-sha224\fP +.IP \(bu 2 +\fBhmac\-sha256\fP +.IP \(bu 2 +\fBhmac\-sha384\fP +.IP \(bu 2 +\fBhmac\-sha512\fP +.UNINDENT +.sp +\fIDefault:\fP not set +.SS secret +.sp +Shared key secret. +.sp +\fIDefault:\fP not set +.SH ACL SECTION +.sp +Access control list rule definitions. The ACLs are used to match incoming +connections to allow or deny requested operation (zone transfer request, DDNS +update, etc.). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +acl: + \- id: STR + address: ADDR[/INT] | ADDR\-ADDR ... + key: key_id ... + action: notify | transfer | update ... + deny: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +An ACL rule identifier. +.SS address +.sp +An ordered list of IP addresses, network subnets, or network ranges. The query +must match one of them. Empty value means that address match is not required. +.sp +\fIDefault:\fP not set +.SS key +.sp +An ordered list of \fI\%reference\fPs to TSIG keys. The query must +match one of them. Empty value means that transaction authentication is not used. +.sp +\fIDefault:\fP not set +.SS action +.sp +An ordered list of allowed (or denied) actions. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnotify\fP – Allow incoming notify. +.IP \(bu 2 +\fBtransfer\fP – Allow zone transfer. +.IP \(bu 2 +\fBupdate\fP – Allow zone updates. +.UNINDENT +.sp +\fIDefault:\fP not set +.SS deny +.sp +If enabled, instead of allowing, deny the specified \fI\%action\fP, +\fI\%address\fP, \fI\%key\fP, or combination if these +items. If no action is specified, deny all actions. +.sp +\fIDefault:\fP off +.SH CONTROL SECTION +.sp +Configuration of the server control interface. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +control: + listen: STR + timeout: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS listen +.sp +A UNIX socket path where the server listens for control commands. +.sp +\fIDefault:\fP \fI\%rundir\fP/knot.sock +.SS timeout +.sp +Maximum time the control socket operations can take. Set 0 for infinity. +.sp +\fIDefault:\fP 5 +.SH STATISTICS SECTION +.sp +Periodic server statistics dumping. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +statistics: + timer: TIME + file: STR + append: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS timer +.sp +A period after which all available statistics metrics will by written to the +\fI\%file\fP\&. +.sp +\fIDefault:\fP not set +.SS file +.sp +A file path of statistics output in the YAML format. +.sp +\fIDefault:\fP \fI\%rundir\fP/stats.yaml +.SS append +.sp +If enabled, the output will be appended to the \fI\%file\fP +instead of file replacement. +.sp +\fIDefault:\fP off +.SH KEYSTORE SECTION +.sp +DNSSEC keystore configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +keystore: + \- id: STR + backend: pem | pkcs11 + config: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A keystore identifier. +.SS backend +.sp +A key storage backend type. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBpem\fP – PEM files. +.IP \(bu 2 +\fBpkcs11\fP – PKCS #11 storage. +.UNINDENT +.sp +\fIDefault:\fP pem +.SS config +.sp +A backend specific configuration. A directory with PEM files (the path can +be specified as a relative path to \fI\%kasp\-db\fP) or +a configuration string for PKCS #11 storage (\fI<pkcs11\-url> <module\-path>\fP). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Example configuration string for PKCS #11: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +"pkcs11:token=knot;pin\-value=1234 /usr/lib64/pkcs11/libsofthsm2.so" +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%kasp\-db\fP/keys +.SH SUBMISSION SECTION +.sp +Parameters of KSK submission checks. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +submission: + \- id: STR + parent: remote_id ... + check\-interval: TIME + timeout: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A submission identifier. +.SS parent +.sp +A list of \fI\%references\fP to parent\(aqs DNS servers to be checked for +presence of corresponding DS records in the case of KSK submission. All of them must +have a corresponding DS for the rollover to continue. If none is specified, the +rollover must be pushed forward manually. +.sp +\fIDefault:\fP not set +.sp +\fBTIP:\fP +.INDENT 0.0 +.INDENT 3.5 +A DNSSEC\-validating resolver can be set as a parent. +.UNINDENT +.UNINDENT +.SS check\-interval +.sp +Interval for periodic checks of DS presence on parent\(aqs DNS servers, in the +case of the KSK submission. +.sp +\fIDefault:\fP 1 hour +.SS timeout +.sp +After this period, the KSK submission is automatically considered successful, even +if all the checks were negative or no parents are configured. Set 0 for infinity. +.sp +\fIDefault:\fP 0 +.SH POLICY SECTION +.sp +DNSSEC policy configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +policy: + \- id: STR + keystore: STR + manual: BOOL + single\-type\-signing: BOOL + algorithm: rsasha1 | rsasha1\-nsec3\-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 + ksk\-size: SIZE + zsk\-size: SIZE + ksk\-shared: BOOL + dnskey\-ttl: TIME + zsk\-lifetime: TIME + ksk\-lifetime: TIME + propagation\-delay: TIME + rrsig\-lifetime: TIME + rrsig\-refresh: TIME + nsec3: BOOL + nsec3\-iterations: INT + nsec3\-opt\-out: BOOL + nsec3\-salt\-length: INT + nsec3\-salt\-lifetime: TIME + ksk\-submission: submission_id + cds\-cdnskey\-publish: none | delete\-dnssec | rollover | always +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A policy identifier. +.SS keystore +.sp +A \fI\%reference\fP to a keystore holding private key material +for zones. A special \fIdefault\fP value can be used for the default keystore settings. +.sp +\fIDefault:\fP default +.SS manual +.sp +If enabled, automatic key management is not used. +.sp +\fIDefault:\fP off +.SS single\-type\-signing +.sp +If enabled, Single\-Type Signing Scheme is used in the automatic key management +mode. +.sp +\fIDefault:\fP off +.SS algorithm +.sp +An algorithm of signing keys and issued signatures. See +\fI\%DNSSEC Algorithm Numbers\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBrsasha1\fP +.IP \(bu 2 +\fBrsasha1\-nsec3\-sha1\fP +.IP \(bu 2 +\fBrsasha256\fP +.IP \(bu 2 +\fBrsasha512\fP +.IP \(bu 2 +\fBecdsap256sha256\fP +.IP \(bu 2 +\fBecdsap384sha384\fP +.IP \(bu 2 +\fBed25519\fP +.UNINDENT +.sp +\fIDefault:\fP ecdsap256sha256 +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Ed25519 algorithm is only available when compiled with GnuTLS 3.6.0+. +.UNINDENT +.UNINDENT +.SS ksk\-size +.sp +A length of newly generated KSK or +CSK keys. +.sp +\fIDefault:\fP 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519) +.SS zsk\-size +.sp +A length of newly generated ZSK keys. +.sp +\fIDefault:\fP see default for \fI\%ksk\-size\fP +.SS ksk\-shared +.sp +If enabled, all zones with this policy assigned will share one KSK. +.sp +\fIDefault:\fP off +.SS dnskey\-ttl +.sp +A TTL value for DNSKEY records added into zone apex. +.sp +\fIDefault:\fP zone SOA TTL +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Has infuence over ZSK key lifetime. +.UNINDENT +.UNINDENT +.SS zsk\-lifetime +.sp +A period between ZSK publication and the next rollover initiation. +.sp +\fIDefault:\fP 30 days +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +ZSK key lifetime is also infuenced by propagation\-delay and dnskey\-ttl +.sp +Zero (aka infinity) value causes no ZSK rollover as a result. +.UNINDENT +.UNINDENT +.SS ksk\-lifetime +.sp +A period between KSK publication and the next rollover initiation. +.sp +\fIDefault:\fP 0 +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +KSK key lifetime is also infuenced by propagation\-delay, dnskey\-ttl, +and KSK submission delay. +.sp +Zero (aka infinity) value causes no KSK rollover as a result. +.sp +This applies for CSK lifetime if single\-type\-signing is enabled. +.UNINDENT +.UNINDENT +.SS propagation\-delay +.sp +An extra delay added for each key rollover step. This value should be high +enough to cover propagation of data from the master server to all slaves. +.sp +\fIDefault:\fP 1 hour +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Has infuence over ZSK key lifetime. +.UNINDENT +.UNINDENT +.SS rrsig\-lifetime +.sp +A validity period of newly issued signatures. +.sp +\fIDefault:\fP 14 days +.SS rrsig\-refresh +.sp +A period how long before a signature expiration the signature will be refreshed. +.sp +\fIDefault:\fP 7 days +.SS nsec3 +.sp +Specifies if NSEC3 will be used instead of NSEC. +.sp +\fIDefault:\fP off +.SS nsec3\-iterations +.sp +A number of additional times the hashing is performed. +.sp +\fIDefault:\fP 5 +.SS nsec3\-opt\-out +.sp +If set, NSEC3 records won\(aqt be created for insecure delegations. +This speeds up the zone signing and reduces overall zone size. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +NSEC3 with the Opt\-Out bit set no longer works as a proof of non\-existence +in this zone. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP off +.SS nsec3\-salt\-length +.sp +A length of a salt field in octets, which is appended to the original owner +name before hashing. +.sp +\fIDefault:\fP 8 +.SS nsec3\-salt\-lifetime +.sp +A validity period of newly issued salt field. +.sp +\fIDefault:\fP 30 days +.SS ksk\-submission +.sp +A reference to \fI\%submission\fP section holding parameters of +KSK submittion checks. +.sp +\fIDefault:\fP not set +.SS cds\-cdnskey\-publish +.sp +Controls if and how shall the CDS and CDNSKEY be published in the zone. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This only applies if the zone keys are automatically managed by the server. +.UNINDENT +.UNINDENT +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Never publish any CDS or CDNSKEY records in the zone. +.IP \(bu 2 +\fBdelete\-dnssec\fP – Publish special CDS and CDNSKEY records indicating turning off DNSSEC. +.IP \(bu 2 +\fBrollover\fP – Publish CDS and CDNSKEY records only in the submission phase of KSK rollover. +.IP \(bu 2 +\fBalways\fP – Always publish CDS and CDNSKEY records for the current KSK. +.UNINDENT +.sp +\fIDefault:\fP always +.SH REMOTE SECTION +.sp +Definitions of remote servers for outgoing connections (source of a zone +transfer, target for a notification, etc.). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote: + \- id: STR + address: ADDR[@INT] ... + via: ADDR[@INT] ... + key: key_id +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A remote identifier. +.SS address +.sp +An ordered list of destination IP addresses which are used for communication +with the remote server. The addresses are tried in sequence unless the +operation is successful. Optional destination port (default is 53) +can be appended to the address using \fB@\fP separator. +.sp +\fIDefault:\fP not set +.SS via +.sp +An ordered list of source IP addresses. The first address with the same family +as the destination address is used. Optional source port (default is random) +can be appended to the address using \fB@\fP separator. +.sp +\fIDefault:\fP not set +.SS key +.sp +A \fI\%reference\fP to the TSIG key which is used to authenticate +the communication with the remote server. +.sp +\fIDefault:\fP not set +.SH TEMPLATE SECTION +.sp +A template is a shareable zone setting which can be used for configuration of +many zones in one place. A special default template (with the \fIdefault\fP identifier) +can be used for global querying configuration or as an implicit configuration +if a zone doesn\(aqt have another template specified. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +template: + \- id: STR + timer\-db: STR + max\-timer\-db\-size: SIZE + journal\-db: STR + journal\-db\-mode: robust | asynchronous + max\-journal\-db\-size: SIZE + kasp\-db: STR + max\-kasp\-db\-size: SIZE + global\-module: STR/STR ... + # All zone options (excluding \(aqtemplate\(aq item) +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A template identifier. +.SS timer\-db +.sp +Specifies a path of the persistent timer database. The path can be specified +as a relative path to the \fIdefault\fP template \fI\%storage\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%storage\fP/timers +.SS max\-timer\-db\-size +.sp +Hard limit for the timer database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP 100 MiB +.SS journal\-db +.sp +Specifies a path of the persistent journal database. The path can be specified +as a relative path to the \fIdefault\fP template \fI\%storage\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%storage\fP/journal +.SS journal\-db\-mode +.sp +Specifies journal LMDB backend configuration, which influences performance +and durability. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBrobust\fP – The journal DB disk sychronization ensures DB durability but is +generally slower. +.IP \(bu 2 +\fBasynchronous\fP – The journal DB disk synchronization is optimized for +better performance at the expense of lower DB durability; this mode is +recommended only on slave nodes with many zones. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP robust +.SS max\-journal\-db\-size +.sp +Hard limit for the common journal DB. There is no cleanup logic in journal +to recover from reaching this limit: journal simply starts refusing changes +across all zones. Decreasing this value has no effect if lower than actual +DB file size. +.sp +It is recommended to limit \fI\%max\-journal\-usage\fP +per\-zone instead of max\-journal\-size in most cases. Please keep this value +larger than the sum of all zones\(aq journal usage limits. See more details +regarding journal behaviour\&. +.sp +This value also influences server\(aqs usage of virtual memory. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP 20 GiB (1 GiB for 32\-bit) +.SS kasp\-db +.sp +A KASP database path. Non\-absolute path is relative to +\fI\%storage\fP\&. +.sp +\fIDefault:\fP \fI\%storage\fP/keys +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.SS max\-kasp\-db\-size +.sp +Hard limit for the KASP database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP 500 MiB +.SS global\-module +.sp +An ordered list of references to query modules in the form of \fImodule_name\fP or +\fImodule_name/module_id\fP\&. These modules apply to all queries. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SH ZONE SECTION +.sp +Definition of zones served by the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone: + \- domain: DNAME + template: template_id + storage: STR + file: STR + master: remote_id ... + ddns\-master: remote_id + notify: remote_id ... + acl: acl_id ... + semantic\-checks: BOOL + disable\-any: BOOL + zonefile\-sync: TIME + zonefile\-load: none | difference | difference\-no\-serial | whole + journal\-content: none | changes | all + max\-journal\-usage: SIZE + max\-journal\-depth: INT + max\-zone\-size : SIZE + dnssec\-signing: BOOL + dnssec\-policy: STR + request\-edns\-option: INT:[HEXSTR] + serial\-policy: increment | unixtime | dateserial + min\-refresh\-interval: TIME + max\-refresh\-interval: TIME + module: STR/STR ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS domain +.sp +A zone name identifier. +.SS template +.sp +A \fI\%reference\fP to a configuration template. +.sp +\fIDefault:\fP not set or \fIdefault\fP (if the template exists) +.SS storage +.sp +A data directory for storing zone files, journal database, and timers database. +.sp +\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) +.SS file +.sp +A path to the zone file. Non\-absolute path is relative to +\fI\%storage\fP\&. It is also possible to use the following formatters: +.INDENT 0.0 +.IP \(bu 2 +\fB%c[\fP\fIN\fP\fB]\fP or \fB%c[\fP\fIN\fP\fB\-\fP\fIM\fP\fB]\fP – Means the \fIN\fPth +character or a sequence of characters beginning from the \fIN\fPth and ending +with the \fIM\fPth character of the textual zone name (see \fB%s\fP). The +indexes are counted from 0 from the left. All dots (including the terminal +one) are considered. If the character is not available, the formatter has no effect. +.IP \(bu 2 +\fB%l[\fP\fIN\fP\fB]\fP – Means the \fIN\fPth label of the textual zone name +(see \fB%s\fP). The index is counted from 0 from the right (0 ~ TLD). +If the label is not available, the formatter has no effect. +.IP \(bu 2 +\fB%s\fP – Means the current zone name in the textual representation. +The zone name doesn\(aqt include the terminating dot (the result for the root +zone is the empty string!). +.IP \(bu 2 +\fB%%\fP – Means the \fB%\fP character. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Beware of special characters which are escaped or encoded in the \eDDD form +where DDD is corresponding decimal ASCII code. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%storage\fP/\fB%s\fP\&.zone +.SS master +.sp +An ordered list of \fI\%references\fP to zone master servers. +.sp +\fIDefault:\fP not set +.SS ddns\-master +.sp +A \fI\%reference\fP to zone primary master server. +If not specified, the first \fI\%master\fP server is used. +.sp +\fIDefault:\fP not set +.SS notify +.sp +An ordered list of \fI\%references\fP to remotes to which notify +message is sent if the zone changes. +.sp +\fIDefault:\fP not set +.SS acl +.sp +An ordered list of \fI\%references\fP to ACL rules which can allow +or disallow zone transfers, updates or incoming notifies. +.sp +\fIDefault:\fP not set +.SS semantic\-checks +.sp +If enabled, extra zone semantic checks are turned on. +.sp +Several checks are enabled by default and cannot be turned off. An error in +mandatory checks causes zone not to be loaded. An error in extra checks is +logged only. +.sp +Mandatory checks: +.INDENT 0.0 +.IP \(bu 2 +SOA record missing in the zone (\fI\%RFC 1034\fP) +.IP \(bu 2 +An extra record together with CNAME record except for RRSIG and DS (\fI\%RFC 1034\fP) +.IP \(bu 2 +Multiple CNAME record with the same owner +.IP \(bu 2 +DNAME record having a record under it (\fI\%RFC 2672\fP) +.UNINDENT +.sp +Extra checks: +.INDENT 0.0 +.IP \(bu 2 +Missing NS record at the zone apex +.IP \(bu 2 +Missing glue A or AAAA record +.IP \(bu 2 +Invalid DNSKEY, DS, or NSEC3PARAM record +.IP \(bu 2 +CDS or CDNSKEY inconsistency +.IP \(bu 2 +Missing, invalid, or unverifiable RRSIG record +.IP \(bu 2 +Invalid NSEC(3) record +.IP \(bu 2 +Broken or non\-cyclic NSEC(3) chain +.UNINDENT +.sp +\fIDefault:\fP off +.SS disable\-any +.sp +If enabled, all authoritative ANY queries sent over UDP will be answered +with an empty response and with the TC bit set. Use this option to minimize +the risk of DNS reflection attack. +.sp +\fIDefault:\fP off +.SS zonefile\-sync +.sp +The time after which the current zone in memory will be synced with a zone file +on the disk (see \fI\%file\fP). The server will serve the latest +zone even after a restart using zone journal, but the zone file on the disk will +only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone +flush). This is applicable when the zone is updated via IXFR, DDNS or automatic +DNSSEC signing. In order to completely disable automatic zone file synchronization, +set the value to \-1. In that case, it is still possible to force a manual zone flush +using the \fB\-f\fP option. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you are serving large zones with frequent updates where +the immediate sync with a zone file is not desirable, increase the value. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP 0 (immediate) +.SS zonefile\-load +.sp +Selects how the zone file contents are applied during zone load. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – The zone file is not used at all. +.IP \(bu 2 +\fBdifference\fP – If the zone contents are already available during server start or reload, +the difference is computed between them and the contents of the zone file. This difference +is then checked for semantic errors and +applied to the current zone contents. +.IP \(bu 2 +\fBdifference\-no\-serial\fP – Same as \fBdifference\fP, but the SOA serial in the zone file is +ignored, the server takes care of incrementing the serial automatically. +.IP \(bu 2 +\fBwhole\fP – Zone contents are loaded from the zone file. +.UNINDENT +.sp +When \fBdifference\fP is configured and there are no zone contents yet (cold start of Knot +and no zone contents in journal), it behaves the same way like \fBwhole\fP\&. +.sp +\fIDefault:\fP whole +.SS journal\-content +.sp +Selects how the journal shall be used to store zone and its changes. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – The journal is not used at all. +.IP \(bu 2 +\fBchanges\fP – Zone changes history is stored in journal. +.IP \(bu 2 +\fBall\fP – Zone contents and history is stored in journal. +.UNINDENT +.sp +\fIDefault:\fP changes +.SS max\-journal\-usage +.sp +Policy how much space in journal DB will the zone\(aqs journal occupy. +.sp +\fIDefault:\fP 100 MiB +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Journal DB may grow far above the sum of max\-journal\-usage across +all zones, because of DB free space fragmentation. +.UNINDENT +.UNINDENT +.SS max\-journal\-depth +.sp +Maximum history length of journal. +.sp +\fIMinimum:\fP 2 +.sp +\fIDefault:\fP 2^64 +.SS max\-zone\-size +.sp +Maximum size of the zone. The size is measured as size of the zone records +in wire format without compression. The limit is enforced for incoming zone +transfers and dynamic updates. +.sp +For incremental transfers (IXFR), the effective limit for the total size of +the records in the transfer is twice the configured value. However the final +size of the zone must satisfy the configured value. +.sp +\fIDefault:\fP 2^64 +.SS dnssec\-signing +.sp +If enabled, automatic DNSSEC signing for the zone is turned on. +.sp +\fIDefault:\fP off +.SS dnssec\-policy +.sp +A \fI\%reference\fP to DNSSEC signing policy. A special \fIdefault\fP +value can be used for the default policy settings. +.sp +\fIRequired\fP +.SS request\-edns\-option +.sp +An arbitrary EDNS0 option which is included into a server request (AXFR, IXFR, +SOA, or NOTIFY). The value is in the option_code:option_data format. +.sp +\fIDefault:\fP not set +.SS serial\-policy +.sp +Specifies how the zone serial is updated after a dynamic update or +automatic DNSSEC signing. If the serial is changed by the dynamic update, +no change is made. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBincrement\fP – The serial is incremented according to serial number arithmetic. +.IP \(bu 2 +\fBunixtime\fP – The serial is set to the current unix time. +.IP \(bu 2 +\fBdateserial\fP – The 10\-digit serial (YYYYMMDDnn) is incremented, the first +8 digits match the current iso\-date. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In case of \fBunixtime\fP, if the resulting serial is lower or equal than current zone +(this happens e.g. in case of migrating from other policy or frequent updates) +the serial is incremented instead. +.sp +Use dateserial only if you expect less than 100 updates per day per zone. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP increment +.SS min\-refresh\-interval +.sp +Forced minimum zone refresh interval to avoid flooding master. +.sp +\fIDefault:\fP 2 +.SS max\-refresh\-interval +.sp +Forced maximum zone refresh interval. +.sp +\fIDefault:\fP not set +.SS module +.sp +An ordered list of references to query modules in the form of \fImodule_name\fP or +\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries. +.sp +\fIDefault:\fP not set +.SH LOGGING SECTION +.sp +Server can be configured to log to the standard output, standard error +output, syslog (or systemd journal if systemd is enabled) or into an arbitrary +file. +.sp +There are 6 logging severity levels: +.INDENT 0.0 +.IP \(bu 2 +\fBcritical\fP – Non\-recoverable error resulting in server shutdown. +.IP \(bu 2 +\fBerror\fP – Recoverable error, action should be taken. +.IP \(bu 2 +\fBwarning\fP – Warning that might require user action. +.IP \(bu 2 +\fBnotice\fP – Server notice or hint. +.IP \(bu 2 +\fBinfo\fP – Informational message. +.IP \(bu 2 +\fBdebug\fP – Debug messages (must be turned on at compile time). +.UNINDENT +.sp +In the case of missing log section, \fBwarning\fP or more serious messages +will be logged to both standard error output and syslog. The \fBinfo\fP and +\fBnotice\fP messages will be logged to standard output. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +log: + \- target: stdout | stderr | syslog | STR + server: critical | error | warning | notice | info | debug + control: critical | error | warning | notice | info | debug + zone: critical | error | warning | notice | info | debug + any: critical | error | warning | notice | info | debug +.ft P +.fi +.UNINDENT +.UNINDENT +.SS target +.sp +A logging output. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBstdout\fP – Standard output. +.IP \(bu 2 +\fBstderr\fP – Standard error output. +.IP \(bu 2 +\fBsyslog\fP – Syslog. +.IP \(bu 2 +\fIfile_name\fP – A specific file. +.UNINDENT +.SS server +.sp +Minimum severity level for messages related to general operation of the server +that are logged. +.sp +\fIDefault:\fP not set +.SS control +.sp +Minimum severity level for messages related to server control that are logged. +.sp +\fIDefault:\fP not set +.SS zone +.sp +Minimum severity level for messages related to zones that are logged. +.sp +\fIDefault:\fP not set +.SS any +.sp +Minimum severity level for all message types that are logged. +.sp +\fIDefault:\fP not set +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knotc.8in b/doc/man/knotc.8in new file mode 100644 index 0000000..88fedb9 --- /dev/null +++ b/doc/man/knotc.8in @@ -0,0 +1,324 @@ +.\" Man page generated from reStructuredText. +. +.TH "KNOTC" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knotc \- Knot DNS control utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBknotc\fP [\fIparameters\fP] \fIaction\fP [\fIaction_args\fP] +.SH DESCRIPTION +.sp +If no \fIaction\fP is specified, the program is executed in interactive mode. +.SS Parameters +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.TP +\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP +Set maximum configuration size (default is @conf_mapsize@ MiB, maximum 10000 MiB). +.TP +\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP +Use a control UNIX socket path (default is \fB@run_dir@/knot.sock\fP). +.TP +\fB\-t\fP, \fB\-\-timeout\fP \fIseconds\fP +Use a control timeout in seconds. Set 0 for infinity (default is 10). +.TP +\fB\-f\fP, \fB\-\-force\fP +Forced operation. Overrides some checks. +.TP +\fB\-v\fP, \fB\-\-verbose\fP +Enable debug output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.UNINDENT +.SS Actions +.INDENT 0.0 +.TP +\fBstatus\fP [\fIdetail\fP] +Check if the server is running. Details are \fBversion\fP for the running +server version, \fBworkers\fP for the numbers of worker threads, +or \fBconfigure\fP for the configure summary. +.TP +\fBstop\fP +Stop the server if running. +.TP +\fBreload\fP +Reload the server configuration and modified zone files. All open zone +transactions will be aborted! +.TP +\fBstats\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] +Show global statistics counter(s). To print also counters with value 0, use +force option. +.TP +\fBzone\-status\fP \fIzone\fP [\fIfilter\fP] +Show the zone status. Filters are \fB+role\fP, \fB+serial\fP, \fB+transaction\fP, +\fB+events\fP, and \fB+freeze\fP\&. +.TP +\fBzone\-check\fP [\fIzone\fP\&...] +Test if the server can load the zone. Semantic checks are executed if enabled +in the configuration. (*) +.TP +\fBzone\-memstats\fP [\fIzone\fP\&...] +Estimate memory use for the zone. (*) +.TP +\fBzone\-reload\fP [\fIzone\fP\&...] +Trigger a zone reload from a disk without checking its modification time. For +slave zone, the refresh from a master server is scheduled; for master zone, +the notification of slave servers is scheduled. An open zone transaction +will be aborted! +.TP +\fBzone\-refresh\fP [\fIzone\fP\&...] +Trigger a check for the zone serial on the zone\(aqs master. If the master has a +newer zone, a transfer is scheduled. This command is valid for slave zones. +.TP +\fBzone\-retransfer\fP [\fIzone\fP\&...] +Trigger a zone transfer from the zone\(aqs master. The server doesn\(aqt check the +serial of the master\(aqs zone. This command is valid for slave zones. +.TP +\fBzone\-notify\fP [\fIzone\fP\&...] +Trigger a NOTIFY message to all configured remotes. This can help in cases +when previous NOTIFY had been lost or the slaves offline. +.TP +\fBzone\-flush\fP [\fIzone\fP\&...] [\fB+outdir\fP \fIdirectory\fP] +Trigger a zone journal flush into the zone file. If output dir is specified, +instead of flushing the zonefile, the zone is dumped to a file in the specified +directory. +.TP +\fBzone\-sign\fP [\fIzone\fP\&...] +Trigger a DNSSEC re\-sign of the zone. Existing signatures will be dropped. +This command is valid for zones with DNSSEC signing enabled. +.TP +\fBzone\-ksk\-submitted\fP \fIzone\fP\&... +Use when the zone\(aqs KSK rollover is in submittion phase. By calling this command +the user confirms manually that the parent zone contains DS record for the new +KSK in submission phase and the old KSK can be retired. +.TP +\fBzone\-freeze\fP [\fIzone\fP\&...] +Temporarily postpone zone\-changing events (load, refresh, update, flush, and +DNSSEC signing). +.TP +\fBzone\-thaw\fP [\fIzone\fP\&...] +Dismiss zone freeze. +.TP +\fBzone\-read\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] +Get zone data that are currently being presented. +.TP +\fBzone\-begin\fP \fIzone\fP\&... +Begin a zone transaction. +.TP +\fBzone\-commit\fP \fIzone\fP\&... +Commit the zone transaction. All changes are applied to the zone. +.TP +\fBzone\-abort\fP \fIzone\fP\&... +Abort the zone transaction. All changes are discarded. +.TP +\fBzone\-diff\fP \fIzone\fP +Get zone changes within the transaction. +.TP +\fBzone\-get\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] +Get zone data within the transaction. +.TP +\fBzone\-set\fP \fIzone\fP \fIowner\fP [\fIttl\fP] \fItype\fP \fIrdata\fP +Add zone record within the transaction. The first record in a rrset +requires a ttl value specified. +.TP +\fBzone\-unset\fP \fIzone\fP \fIowner\fP [\fItype\fP [\fIrdata\fP]] +Remove zone data within the transaction. +.TP +\fBzone\-purge\fP \fIzone\fP\&... [\fIfilter\fP\&...] +Purge zone data, zone file, journal, timers, and/or KASP data of specified zones. +Available filters are \fB+expire\fP, \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, +and \fB+kaspdb\fP\&. If no filter is specified, all filters are enabled. +If the zone is no longer configured, add \fB+orphan\fP filter (zone file cannot +be purged in this case). +.TP +\fBzone\-stats\fP \fIzone\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] +Show zone statistics counter(s). To print also counters with value 0, use +force option. +.TP +\fBconf\-init\fP +Initialize the configuration database. (*) +.TP +\fBconf\-check\fP +Check the server configuration. (*) +.TP +\fBconf\-import\fP \fIfilename\fP +Import a configuration file into the configuration database. Ensure the +server is not using the configuration database! (*) +.TP +\fBconf\-export\fP [\fIfilename\fP] +Export the configuration database into a config file or stdout. (*) +.TP +\fBconf\-list\fP [\fIitem\fP] +List the configuration database sections or section items. +.TP +\fBconf\-read\fP [\fIitem\fP] +Read the item from the active configuration database. +.TP +\fBconf\-begin\fP +Begin a writing configuration database transaction. Only one transaction +can be opened at a time. +.TP +\fBconf\-commit\fP +Commit the configuration database transaction. +.TP +\fBconf\-abort\fP +Rollback the configuration database transaction. +.TP +\fBconf\-diff\fP [\fIitem\fP] +Get the item difference in the transaction. +.TP +\fBconf\-get\fP [\fIitem\fP] +Get the item data from the transaction. +.TP +\fBconf\-set\fP \fIitem\fP [\fIdata\fP\&...] +Set the item data in the transaction. +.TP +\fBconf\-unset\fP [\fIitem\fP] [\fIdata\fP\&...] +Unset the item data in the transaction. +.UNINDENT +.SS Note +.sp +Empty or \fB\-\-\fP \fIzone\fP parameter means all zones or all zones with a transaction. +.sp +Use \fB@\fP \fIowner\fP to denote the zone name. +.sp +Type \fIitem\fP parameter in the form of \fIsection\fP[\fB[\fP\fIid\fP\fB]\fP][\fB\&.\fP\fIname\fP]. +.sp +(*) indicates a local operation which requires a configuration. +.SS Interactive mode +.sp +The utility provides interactive mode with basic line editing functionality, +command completion, and command history. +.sp +Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to +\fBeditrc(5)\fP for details. +.sp +Command history is saved in \fI~/.knotc_history\fP\&. +.SH EXAMPLES +.SS Reload the whole server configuration +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc reload +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Flush the example.com and example.org zones +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc zone\-flush example.com example.org +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the current server configuration +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-read server +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the list of the current zones +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-read zone.domain +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the master remotes for the example.com zone +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-read \(aqzone[example.com].master\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Add example.org zone with a zonefile location +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-begin +$ knotc conf\-set \(aqzone[example.org]\(aq +$ knotc conf\-set \(aqzone[example.org].file\(aq \(aq/var/zones/example.org.zone\(aq +$ knotc conf\-commit +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the SOA record for each configured zone +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc zone\-read \-\- @ SOA +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP, \fBeditrc(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knotd.8in b/doc/man/knotd.8in new file mode 100644 index 0000000..2ae6450 --- /dev/null +++ b/doc/man/knotd.8in @@ -0,0 +1,76 @@ +.\" Man page generated from reStructuredText. +. +.TH "KNOTD" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knotd \- Knot DNS server daemon +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBknotd\fP [\fIparameters\fP] +.SH DESCRIPTION +.SS Parameters +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.TP +\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP +Set maximum configuration size (default is @conf_mapsize@ MiB, maximum 10000 MiB). +.TP +\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP +Use a remote control UNIX socket path (default is \fB@run_dir@/knot.sock\fP). +.TP +\fB\-d\fP, \fB\-\-daemonize\fP [\fIdirectory\fP] +Run the server as a daemon. New root directory may be specified +(default is \fB/\fP). +.TP +\fB\-v\fP, \fB\-\-verbose\fP +Enable debug output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.UNINDENT +.SH SEE ALSO +.sp +\fBknot.conf(5)\fP, \fBknotc(8)\fP, \fBkeymgr(8)\fP, +\fBkjournalprint(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knsec3hash.1in b/doc/man/knsec3hash.1in new file mode 100644 index 0000000..a450097 --- /dev/null +++ b/doc/man/knsec3hash.1in @@ -0,0 +1,87 @@ +.\" Man page generated from reStructuredText. +. +.TH "KNSEC3HASH" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knsec3hash \- Simple utility to compute NSEC3 hash +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBknsec3hash\fP \fIsalt\fP \fIalgorithm\fP \fIiterations\fP \fIname\fP +.SH DESCRIPTION +.sp +This utility generates a NSEC3 hash for a given domain name and parameters of NSEC3 hash. +.SS Parameters +.INDENT 0.0 +.TP +\fIsalt\fP +Specifies a binary salt encoded as a hexadecimal string. +.TP +\fIalgorithm\fP +Specifies a hashing algorithm by number. Currently, the only supported algorithm is SHA\-1 (number 1). +.TP +\fIiterations\fP +Specifies the number of additional iterations of the hashing algorithm. +.TP +\fIname\fP +Specifies the domain name to be hashed. +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knsec3hash c01dcafe 1 10 knot\-dns.cz +7PTVGE7QV67EM61ROS9238P5RAKR2DM7 (salt=c01dcafe, hash=1, iterations=10) +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knsec3hash \- 1 0 net +A1RT98BS5QGC9NFI51S9HCI47ULJG6JH (salt=\-, hash=1, iterations=0) +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 5155\fP – DNS Security (DNSSEC) Hashed Authenticated Denial of Existence. +.sp +\fBknotc(8)\fP, \fBknotd(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knsupdate.1in b/doc/man/knsupdate.1in new file mode 100644 index 0000000..10c0b87 --- /dev/null +++ b/doc/man/knsupdate.1in @@ -0,0 +1,198 @@ +.\" Man page generated from reStructuredText. +. +.TH "KNSUPDATE" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knsupdate \- Dynamic DNS update utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBknsupdate\fP [\fIoptions\fP] [\fIfilename\fP] +.SH DESCRIPTION +.sp +This utility sends Dynamic DNS update messages to a DNS server. Update content +is read from a file (if the parameter \fIfilename\fP is given) or from the standard +input. +.sp +The format of updates is textual and is made up of commands. Every command is +placed on the separate line of the input. Lines starting with a semicolon are +comments and are not processed. +.SS Options +.INDENT 0.0 +.TP +\fB\-d\fP +Enable debug messages. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-k\fP \fIkeyfile\fP +Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The +file should contain the key in the same format, which is accepted by the +\fB\-y\fP option. +.TP +\fB\-p\fP \fIport\fP +Set the port to use for connections to the server (if not explicitly specified +in the update). The default is 53. +.TP +\fB\-r\fP \fIretries\fP +The number of retries for UDP requests. The default is 3. +.TP +\fB\-t\fP \fItimeout\fP +The total timeout (for all UDP update tries) of the update request in seconds. +The default is 12. If set to zero, the timeout is infinite. +.TP +\fB\-v\fP +Use a TCP connection. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.TP +\fB\-y\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP +Use the TSIG key with a name \fIname\fP to authenticate the request. The \fIalg\fP +part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies +the shared secret encoded in Base64. +.UNINDENT +.SS Commands +.INDENT 0.0 +.TP +\fBserver\fP \fIname\fP [\fIport\fP] +Specifies a receiving server of the dynamic update message. The \fIname\fP parameter +can be either a host name or an IP address. If the \fIport\fP is not specified, +the default port is used. The default port value can be controlled using +the \fB\-p\fP program option. +.TP +\fBlocal\fP \fIaddress\fP [\fIport\fP] +Specifies outgoing \fIaddress\fP and \fIport\fP\&. If no local is specified, the +address and port are set by the system automatically. The default port number +is 0. +.TP +\fBzone\fP \fIname\fP +Specifies that all updates are done within a zone \fIname\fP\&. If not used, +the default zone is the root zone. +.TP +\fBorigin\fP \fIname\fP +Specifies fully qualified domain name suffix which is appended to non\-fqd +owners in update commands. The default origin is the root zone. +.TP +\fBclass\fP \fIname\fP +Sets \fIname\fP as the default class for all updates. If not used, the default +class is IN. +.TP +\fBttl\fP \fIvalue\fP +Sets \fIvalue\fP as the default TTL (in seconds). If not used, the default value +is 0. +.TP +\fBkey\fP [\fIalg\fP:]\fIname\fP \fIkey\fP +Specifies the TSIG \fIkey\fP named \fIname\fP to authenticate the request. An optional +\fIalg\fP algorithm can be specified. This command has the same effect as +the program option \fB\-y\fP\&. +.TP +[\fBprereq\fP] \fBnxdomain\fP \fIname\fP +Adds a prerequisite for a non\-existing record owned by \fIname\fP\&. +.TP +[\fBprereq\fP] \fByxdomain\fP \fIname\fP +Adds a prerequisite for an existing record owned by \fIname\fP\&. +.TP +[\fBprereq\fP] \fBnxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP +Adds a prerequisite for a non\-existing record of the \fItype\fP owned by \fIname\fP\&. +Internet \fIclass\fP is expected. +.TP +[\fBprereq\fP] \fByxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP [\fIdata\fP] +Adds a prerequisite for an existing record of the \fItype\fP owned by \fIname\fP +with optional \fIdata\fP\&. Internet \fIclass\fP is expected. +.TP +[\fBupdate\fP] \fBadd\fP \fIname\fP [\fIttl\fP] [\fIclass\fP] \fItype\fP \fIdata\fP +Adds a request to add a new resource record into the zone. +Please note that if the \fIname\fP is not fully qualified domain name, the +current origin name is appended to it. +.TP +[\fBupdate\fP] \fBdel\fP[\fBete\fP] \fIname\fP [\fIttl\fP] [\fIclass\fP] [\fItype\fP] [\fIdata\fP] +Adds a request to remove all (or matching \fIclass\fP, \fItype\fP or \fIdata\fP) +resource records from the zone. There is the same requirement for the \fIname\fP +parameter as in \fBupdate add\fP command. The \fIttl\fP item is ignored. +.TP +\fBshow\fP +Displays current content of the update message. +.TP +\fBsend\fP +Sends the current update message and cleans the list of updates. +.TP +\fBanswer\fP +Displays the last answer from the server. +.TP +\fBdebug\fP +Enable debugging. This command has the same meaning as the \fB\-d\fP program option. +.TP +\fBquit\fP +Quit the program. +.UNINDENT +.SH NOTES +.sp +Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously. +.sp +Dnssec\-keygen keyfile format is not supported. Use \fBkeymgr(8)\fP instead. +.sp +Zone name/server guessing is not supported if the zone name/server is not specified. +.sp +Empty line doesn\(aqt send the update. +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Send one update of the zone example.com to the server 192.168.1.1. The update +contains two new records: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knsupdate +> server 192.168.1.1 +> zone example.com. +> origin example.com. +> ttl 3600 +> add test1.example.com. 7200 A 192.168.2.2 +> add test2 TXT "hello" +> show +> send +> answer +> quit +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBkdig(1)\fP, \fBkhost(1)\fP, \fBkeymgr(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kzonecheck.1in b/doc/man/kzonecheck.1in new file mode 100644 index 0000000..cb8fe22 --- /dev/null +++ b/doc/man/kzonecheck.1in @@ -0,0 +1,73 @@ +.\" Man page generated from reStructuredText. +. +.TH "KZONECHECK" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +kzonecheck \- Knot DNS zone check tool +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBkzonecheck\fP [\fIoptions\fP] \fIfilename\fP +.SH DESCRIPTION +.sp +The utility checks zone file syntax and runs semantic checks on the zone +content. The executed checks are the same as the checks run by the Knot +DNS server. +.sp +Please, refer to the \fBsemantic\-checks\fP configuration option in +\fBknot.conf(5)\fP for the full list of available semantic checks. +.SS Options +.INDENT 0.0 +.TP +\fB\-o\fP, \fB\-\-origin\fP \fIorigin\fP +Zone origin. If not specified, the origin is determined from the file name +(possibly removing the \fB\&.zone\fP suffix). +.TP +\fB\-t\fP, \fB\-\-time\fP \fItime\fP +Current time specification. Use UNIX timestamp, YYYYMMDDHHmmSS +format, or [+/\-]\fItime\fP[unit] format, where unit can be \fBY\fP, \fBM\fP, +\fBD\fP, \fBh\fP, \fBm\fP, or \fBs\fP\&. Default is current UNIX timestamp. +.TP +\fB\-v\fP, \fB\-\-verbose\fP +Enable debug output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. +.UNINDENT +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2019, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man_kdig.rst b/doc/man_kdig.rst new file mode 100644 index 0000000..c1b3961 --- /dev/null +++ b/doc/man_kdig.rst @@ -0,0 +1,324 @@ +.. highlight:: console + +kdig – Advanced DNS lookup utility +================================== + +Synopsis +-------- + +:program:`kdig` [*common-settings*] [*query* [*settings*]]... + +:program:`kdig` **-h** + +Description +----------- + +This utility sends one or more DNS queries to a nameserver. Each query can have +individual *settings*, or it can be specified globally via *common-settings*, +which must precede *query* specification. + +Parameters +.......... + +*query* + *name* | **-q** *name* | **-x** *address* | **-G** *tapfile* + +*common-settings*, *settings* + [*query_class*] [*query_type*] [**@**\ *server*]... [*options*] + +*name* + Is a domain name that is to be looked up. + +*server* + Is a domain name or an IPv4 or IPv6 address of the nameserver to send a query + to. An additional port can be specified using address:port ([address]:port + for IPv6 address), address@port, or address#port notation. If no server is + specified, the servers from :file:`/etc/resolv.conf` are used. + +If no arguments are provided, :program:`kdig` sends NS query for the root +zone. + +Query classes +............. + +A *query_class* can be either a DNS class name (IN, CH) or generic class +specification **CLASS**\ *XXXXX* where *XXXXX* is a corresponding decimal +class number. The default query class is IN. + +Query types +........... + +A *query_type* can be either a DNS resource record type +(A, AAAA, NS, SOA, DNSKEY, ANY, etc.) or one of the following: + +**TYPE**\ *XXXXX* + Generic query type specification where *XXXXX* is a corresponding decimal + type number. + +**AXFR** + Full zone transfer request. + +**IXFR=**\ *serial* + Incremental zone transfer request for specified starting SOA serial number. + +**NOTIFY=**\ *serial* + Notify message with a SOA serial hint specified. + +**NOTIFY** + Notify message with a SOA serial hint unspecified. + +The default query type is A. + +Options +....... + +**-4** + Use the IPv4 protocol only. + +**-6** + Use the IPv6 protocol only. + +**-b** *address* + Set the source IP address of the query to *address*. The address must be a + valid address for local interface or :: or 0.0.0.0. An optional port + can be specified in the same format as the *server* value. + +**-c** *class* + An explicit *query_class* specification. See possible values above. + +**-d** + Enable debug messages. + +**-h**, **--help** + Print the program help. + +**-k** *keyfile* + Use the TSIG key stored in a file *keyfile* to authenticate the request. The + file must contain the key in the same format as accepted by the + **-y** option. + +**-p** *port* + Set the nameserver port number or service name to send a query to. The default + port is 53. + +**-q** *name* + Set the query name. An explicit variant of *name* specification. If no *name* + is provided, empty question section is set. + +**-t** *type* + An explicit *query_type* specification. See possible values above. + +**-V**, **--version** + Print the program version. + +**-x** *address* + Send a reverse (PTR) query for IPv4 or IPv6 *address*. The correct name, class + and type is set automatically. + +**-y** [*alg*:]\ *name*:*key* + Use the TSIG key named *name* to authenticate the request. The *alg* + part specifies the algorithm (the default is hmac-sha256) and *key* specifies + the shared secret encoded in Base64. + +**-E** *tapfile* + Export a dnstap trace of the query and response messages received to the + file *tapfile*. + +**-G** *tapfile* + Generate message output from a previously saved dnstap file *tapfile*. + +**+**\ [\ **no**\ ]\ **multiline** + Wrap long records to more lines and improve human readability. + +**+**\ [\ **no**\ ]\ **short** + Show record data only. + +**+**\ [\ **no**\ ]\ **generic** + Use the generic representation format when printing resource record types + and data. + +**+**\ [\ **no**\ ]\ **crypto** + Display the DNSSEC keys and signatures values in hexdump, instead of omitting them. + +**+**\ [\ **no**\ ]\ **aaflag** + Set the AA flag. + +**+**\ [\ **no**\ ]\ **tcflag** + Set the TC flag. + +**+**\ [\ **no**\ ]\ **rdflag** + Set the RD flag. + +**+**\ [\ **no**\ ]\ **recurse** + Same as **+**\ [\ **no**\ ]\ **rdflag** + +**+**\ [\ **no**\ ]\ **raflag** + Set the RA flag. + +**+**\ [\ **no**\ ]\ **zflag** + Set the zero flag bit. + +**+**\ [\ **no**\ ]\ **adflag** + Set the AD flag. + +**+**\ [\ **no**\ ]\ **cdflag** + Set the CD flag. + +**+**\ [\ **no**\ ]\ **dnssec** + Set the DO flag. + +**+**\ [\ **no**\ ]\ **all** + Show all packet sections. + +**+**\ [\ **no**\ ]\ **qr** + Show the query packet. + +**+**\ [\ **no**\ ]\ **header** + Show the packet header. + +**+**\ [\ **no**\ ]\ **comments** + Show commented section names. + +**+**\ [\ **no**\ ]\ **opt** + Show the EDNS pseudosection. + +**+**\ [\ **no**\ ]\ **question** + Show the question section. + +**+**\ [\ **no**\ ]\ **answer** + Show the answer section. + +**+**\ [\ **no**\ ]\ **authority** + Show the authority section. + +**+**\ [\ **no**\ ]\ **additional** + Show the additional section. + +**+**\ [\ **no**\ ]\ **tsig** + Show the TSIG pseudosection. + +**+**\ [\ **no**\ ]\ **stats** + Show trailing packet statistics. + +**+**\ [\ **no**\ ]\ **class** + Show the DNS class. + +**+**\ [\ **no**\ ]\ **ttl** + Show the TTL value. + +**+**\ [\ **no**\ ]\ **tcp** + Use the TCP protocol (default is UDP for standard query and TCP for AXFR/IXFR). + +**+**\ [\ **no**\ ]\ **fastopen** + Use TCP Fast Open (default with TCP). + +**+**\ [\ **no**\ ]\ **ignore** + Don't use TCP automatically if a truncated reply is received. + +**+**\ [\ **no**\ ]\ **tls** + Use TLS with the Opportunistic privacy profile (:rfc:`7858#section-4.1`). + +**+**\ [\ **no**\ ]\ **tls-ca**\[\ =\ *FILE*\] + Use TLS with a certificate validation. Certification authority certificates + are loaded from the specified PEM file (default is system certificate storage + if no argument is provided). + Can be specified multiple times. If the +tls-hostname option is not provided, + the name of the target server (if specified) is used for strict authentication. + +**+**\ [\ **no**\ ]\ **tls-pin**\ =\ *BASE64* + Use TLS with the Out-of-Band key-pinned privacy profile (:rfc:`7858#section-4.2`). + The PIN must be a Base64 encoded SHA-256 hash of the X.509 SubjectPublicKeyInfo. + Can be specified multiple times. + +**+**\ [\ **no**\ ]\ **tls-hostname**\ =\ *STR* + Use TLS with a remote server hostname check. + +**+**\ [\ **no**\ ]\ **tls-sni**\ =\ *STR* + Use TLS with a Server Name Indication. + +**+**\ [\ **no**\ ]\ **nsid** + Request the nameserver identifier (NSID). + +**+**\ [\ **no**\ ]\ **bufsize**\ =\ *B* + Set EDNS buffer size in bytes (default is 512 bytes). + +**+**\ [\ **no**\ ]\ **padding**\[\ =\ *B*\] + Use EDNS(0) padding option to pad queries, optionally to a specific + size. The default is to pad queries with a sensible amount when using + +tls, and not to pad at all when queries are sent without TLS. With + no argument (i.e., just +padding) pad every query with a sensible + amount regardless of the use of TLS. With +nopadding, never pad. + +**+**\ [\ **no**\ ]\ **alignment**\[\ =\ *B*\] + Align the query to B\-byte-block message using the EDNS(0) padding option + (default is no or 128 if no argument is specified). + +**+**\ [\ **no**\ ]\ **subnet**\ =\ *SUBN* + Set EDNS(0) client subnet SUBN=addr/prefix. + +**+**\ [\ **no**\ ]\ **edns**\[\ =\ *N*\] + Use EDNS version (default is 0). + +**+**\ [\ **no**\ ]\ **timeout**\ =\ *T* + Set the wait-for-reply interval in seconds (default is 5 seconds). This timeout + applies to each query attempt. + +**+**\ [\ **no**\ ]\ **retry**\ =\ *N* + Set the number (>=0) of UDP retries (default is 2). This doesn't apply to + AXFR/IXFR. + +**+**\ [\ **no**\ ]\ **cookie**\ =\ *HEX* + Attach EDNS(0) cookie to the query. + +**+**\ [\ **no**\ ]\ **badcookie** + Repeat a query with the correct cookie. + +**+**\ [\ **no**\ ]\ **ednsopt**\[\ =\ *CODE*\[:*HEX*\]\] + Send custom EDNS option. The *CODE* is EDNS option code in decimal, *HEX* + is an optional hex encoded string to use as EDNS option value. This argument + can be used multiple times. +noednsopt clears all EDNS options specified by + +ednsopt. + +**+noidn** + Disable the IDN transformation to ASCII and vice versa. IDNA2003 support depends + on libidn availability during project building! + +Notes +----- + +Options **-k** and **-y** can not be used simultaneously. + +Dnssec-keygen keyfile format is not supported. Use :manpage:`keymgr(8)` instead. + +Examples +-------- + +1. Get A records for example.com:: + + $ kdig example.com A + +2. Perform AXFR for zone example.com from the server 192.0.2.1:: + + $ kdig example.com -t AXFR @192.0.2.1 + +3. Get A records for example.com from 192.0.2.1 and reverse lookup for address + 2001:DB8::1 from 192.0.2.2. Both using the TCP protocol:: + + $ kdig +tcp example.com -t A @192.0.2.1 -x 2001:DB8::1 @192.0.2.2 + +4. Get SOA record for example.com, use TLS, use system certificates, check + for specified hostname, check for certificate pin, and print additional + debug info:: + + $ kdig -d @185.49.141.38 +tls-ca +tls-host=getdnsapi.net \ + +tls-pin=foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S= soa example.com + +Files +----- + +:file:`/etc/resolv.conf` + +See Also +-------- + +:manpage:`khost(1)`, :manpage:`knsupdate(1)`, :manpage:`keymgr(8)`. diff --git a/doc/man_keymgr.rst b/doc/man_keymgr.rst new file mode 100644 index 0000000..03409b6 --- /dev/null +++ b/doc/man_keymgr.rst @@ -0,0 +1,216 @@ +.. highlight:: console + +keymgr – Key management utility +=============================== + +Synopsis +-------- + +:program:`keymgr` *basic_option* [*parameters*...] + +:program:`keymgr` [*config_option* *config_storage*] *zone* *command* *argument*... + +Description +----------- + +The :program:`keymgr` utility serves for manual key management in Knot DNS server. + +Functions for DNSSEC keys and KASP (Key And Signature Policy) +management are provided. + +The DNSSEC and KASP configuration is stored in a so called KASP database. +The database is backed by LMDB. + +Basic options +............. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +**-t**, **--tsig** *tsig_name* [*tsig_algorithm*] [*tsig_bits*] + Generates a TSIG key. TSIG algorithm can be specified by string (default: hmac-sha256), + bit length of the key by number (default: optimal length given by algorithm). The generated + TSIG key is only displayed on `stdout`: the command does not create a file, nor include the + key in a keystore. + +Config options +.............. + +**-c**, **--config** *file* + Use a textual configuration file (default is :file:`@config_dir@/knot.conf`). + +**-C**, **--confdb** *directory* + Use a binary configuration database directory (default is :file:`@storage_dir@/confdb`). + The default configuration database, if exists, has a preference to the default + configuration file. + +**-d**, **--dir** *path* + Use specified KASP database path and default configuration. + +Commands +........ + +**list** [*timestamp_format*] + Prints the list of key IDs and parameters of keys belonging to the zone. + +**generate** [*arguments*...] + Generates new DNSSEC key and stores it in KASP database. Prints the key ID. + This action takes some number of arguments (see below). Values for unspecified arguments are taken + from corresponding policy (if *-c* or *-C* options used) or from Knot policy defaults. + +**import-bind** *BIND_key_file* + Imports a BIND-style key into KASP database (converting it to PEM format). + Takes one argument: path to BIND key file (private or public, but both MUST exist). + +**import-pub** *BIND_pubkey_file* + Imports a public key into KASP database. This key won't be rollovered nor used for signing. + Takes one argument: path to BIND public key file. + +**import-pem** *PEM_file* [*arguments*...] + Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be + specified (mainly algorithm, timers...) because they are not contained in the PEM format. + +**import-pkcs11** *key_id* [*arguments*...] + Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be + specified (mainly algorithm, timers...) because they are not available. In fact, no key + data is imported, only KASP database metadata is created. + +**nsec3-salt** [*new_salt*] + Prints the current NSEC3 salt used for signing. If *new_salt* is specified, the salt is overwritten. + The salt is printed and expected in hexadecimal, or dash if empty. + +**set** *key_spec* [*arguments*...] + Changes a timing argument (or ksk/zsk) of an existing key to a new value. *Key_spec* is either the + key tag or a prefix of the key ID; *arguments* are like for **generate**, but just the related ones. + +**ds** [*key_spec*] + Generate DS record (all digest algorithms together) for specified key. *Key_spec* + is like for **set**, if unspecified, all KSKs are used. + +**dnskey** [*key_spec*] + Generate DNSKEY record for specified key. *Key_spec* + is like for **ds**, if unspecified, all KSKs are used. + +**delete** *key_spec* + Remove the specified key from zone. If the key was not shared, it is also deleted from keystore. + +**share** *key_ID* + Import a key (specified by full key ID) from another zone as shared. After this, the key is + owned by both zones equally. + +Generate arguments +.................. + +Arguments are separated by space, each of them is in format 'name=value'. + +**algorithm** + Either an algorithm number (e.g. 14), or text name without dashes (e.g. ECDSAP384SHA384). + +**size** + Key length in bits. + +**ksk** + If set to **yes**, the key will be used for signing DNSKEY rrset. The generated key will also + have the Secure Entry Point flag set to 1. + +**zsk** + If set to **yes**, the key will be used for signing zone (except DNSKEY rrset). This flag can + be set concurrently with the **ksk** flag. + +**sep** + Overrides the standard setting of the Secure Entry Point flag for the generated key. + +The following arguments are timestamps of key lifetime: + +**created** + Key created. + +**pre_active** + Key started to be used for signing, not published (only for algorithm rollover). + +**publish** + Key published. + +**ready** + Key used for signing and submitted to the parent zone (only for KSK). + +**active** + Key used for signing. + +**post_active** + Key still used for singing, but another key is active (only for KSK). + +**retire_active** + Key no longer published, but still used for signing (only for algorithm rollover). + +**retire** + Key still published, but no longer used for signing. + +**remove** + Key deleted. + +Timestamps +.......... + +0 + Zero timestamp means infinite future. + +*UNIX_time* + Positive number of seconds since 1970 UTC. + +*YYYYMMDDHHMMSS* + Date and time in this format without any punctuation. + +*relative_timestamp* + A sign character (**+**, **-**), a number, and an optional time unit + (**y**, **mo**, **d**, **h**, **mi**, **s**). The default unit is one second. + E.g. +1mi, -2mo. + +Output timestamp formats +........................ + +(none) + The timestamps are printed as UNIX timestamp. + +**human** + The timestamps are printed relatively to now using time units (e.g. -2y5mo, +1h13s). + +**iso** + The timestamps are printed in the ISO8601 format (e.g. 2016-12-31T23:59:00). + +Examples +-------- + +1. Generate new TSIG key:: + + $ keymgr -t my_name hmac-sha384 + +2. Generate new DNSSEC key:: + + $ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \ + ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y + +3. Import a DNSSEC key from BIND:: + + $ keymgr example.com. import-bind ~/bind/Kharbinge4d5.+007+63089.key + +4. Configure key timing:: + + $ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi + +5. Share a KSK from another zone:: + + $ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 + +See Also +-------- + +:rfc:`6781` - DNSSEC Operational Practices. +:rfc:`7583` - DNSSEC Key Rollover Timing Considerations. + +:manpage:`knot.conf(5)`, +:manpage:`knotc(8)`, +:manpage:`knotd(8)`. diff --git a/doc/man_khost.rst b/doc/man_khost.rst new file mode 100644 index 0000000..b6e2d6b --- /dev/null +++ b/doc/man_khost.rst @@ -0,0 +1,102 @@ +.. highlight:: console + +khost – Simple DNS lookup utility +================================= + +Synopsis +-------- + +:program:`khost` [*options*] *name* [*server*] + +Description +----------- + +This utility sends a DNS query for the *name* to the *server* and prints a reply +in more user-readable form. For more advanced DNS queries use :program:`kdig` +instead. + +Parameters +.......... + +*name* + Is a domain name that is to be looked up. If the *name* is IPv4 or IPv6 + address the PTR query type is used. + +*server* + Is a name or an address of the nameserver to send a query to. The address + can be specified using [address]:port notation. If no server is specified, + the servers from :file:`/etc/resolv.conf` are used. + +If no arguments are provided, :program:`khost` prints a short help. + +Options +....... + +**-4** + Use the IPv4 protocol only. + +**-6** + Use the IPv6 protocol only. + +**-a** + Send ANY query with verbose mode. + +**-d** + Enable debug messages. + +**-h**, **--help** + Print the program help. + +**-r** + Disable recursion. + +**-T** + Use the TCP protocol. + +**-v** + Enable verbose output. + +**-V**, **--version** + Print the program version. + +**-w** + Wait forever for the reply. + +**-c** *class* + Set the query class (e.g. CH, CLASS4). The default class is IN. + +**-t** *type* + Set the query type (e.g. NS, IXFR=12345, TYPE65535). The default is to send 3 + queries (A, AAAA and MX). + +**-R** *retries* + The number (>=0) of UDP retries to query a nameserver. The default is 1. + +**-W** *wait* + The time to wait for a reply in seconds. This timeout applies to each query + try. The default is 2 seconds. + +Examples +-------- + +1. Get the A, AAAA and MX records for example.com:: + + $ khost example.com + +2. Get the reverse record for address 192.0.2.1:: + + $ khost 192.0.2.1 + +3. Perform a verbose zone transfer for zone example.com:: + + $ khost -t AXFR -v example.com + +Files +----- + +:file:`/etc/resolv.conf` + +See Also +-------- + +:manpage:`kdig(1)`, :manpage:`knsupdate(1)`. diff --git a/doc/man_kjournalprint.rst b/doc/man_kjournalprint.rst new file mode 100644 index 0000000..f8868dd --- /dev/null +++ b/doc/man_kjournalprint.rst @@ -0,0 +1,58 @@ +.. highlight:: console + +kjournalprint – Knot DNS journal print utility +============================================== + +Synopsis +-------- + +:program:`kjournalprint` [*options*] *journal_db* *zone_name* + +Description +----------- + +The program prints zone history stored in a journal database. As default, +changes are colored for terminal. + +Options +....... + +**-l**, **--limit** *limit* + Limits the number of displayed changes. + +**-d**, **--debug** + Debug mode brief output. + +**-n**, **--no-color** + Removes changes coloring. + +**-z**, **--zone-list** + Instead of reading jurnal, display the list of zones in the DB. + (*zone_name* not needed) + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +Parameters +.......... + +*journal_db* + A path to the journal database. + +*zone_name* + A name of the zone to print the history for. + +Examples +-------- + +Last (most recent) 5 changes without colors:: + + $ kjournalprint -nl 5 /var/lib/knot/journal example.com. + +See Also +-------- + +:manpage:`knotd(8)`, :manpage:`knot.conf(5)`. diff --git a/doc/man_knotc.rst b/doc/man_knotc.rst new file mode 100644 index 0000000..ebfe4f1 --- /dev/null +++ b/doc/man_knotc.rst @@ -0,0 +1,274 @@ +.. highlight:: console + +knotc – Knot DNS control utility +================================ + +Synopsis +-------- + +:program:`knotc` [*parameters*] *action* [*action_args*] + +Description +----------- + +If no *action* is specified, the program is executed in interactive mode. + +Parameters +.......... + +**-c**, **--config** *file* + Use a textual configuration file (default is :file:`@config_dir@/knot.conf`). + +**-C**, **--confdb** *directory* + Use a binary configuration database directory (default is :file:`@storage_dir@/confdb`). + The default configuration database, if exists, has a preference to the default + configuration file. + +**-m**, **--max-conf-size** *MiB* + Set maximum configuration size (default is @conf_mapsize@ MiB, maximum 10000 MiB). + +**-s**, **--socket** *path* + Use a control UNIX socket path (default is :file:`@run_dir@/knot.sock`). + +**-t**, **--timeout** *seconds* + Use a control timeout in seconds. Set 0 for infinity (default is 10). + +**-f**, **--force** + Forced operation. Overrides some checks. + +**-v**, **--verbose** + Enable debug output. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +Actions +....... + +**status** [*detail*] + Check if the server is running. Details are **version** for the running + server version, **workers** for the numbers of worker threads, + or **configure** for the configure summary. + +**stop** + Stop the server if running. + +**reload** + Reload the server configuration and modified zone files. All open zone + transactions will be aborted! + +**stats** [*module*\ [\ **.**\ *counter*\ ]] + Show global statistics counter(s). To print also counters with value 0, use + force option. + +**zone-status** *zone* [*filter*] + Show the zone status. Filters are **+role**, **+serial**, **+transaction**, + **+events**, and **+freeze**. + +**zone-check** [*zone*...] + Test if the server can load the zone. Semantic checks are executed if enabled + in the configuration. (*) + +**zone-memstats** [*zone*...] + Estimate memory use for the zone. (*) + +**zone-reload** [*zone*...] + Trigger a zone reload from a disk without checking its modification time. For + slave zone, the refresh from a master server is scheduled; for master zone, + the notification of slave servers is scheduled. An open zone transaction + will be aborted! + +**zone-refresh** [*zone*...] + Trigger a check for the zone serial on the zone's master. If the master has a + newer zone, a transfer is scheduled. This command is valid for slave zones. + +**zone-retransfer** [*zone*...] + Trigger a zone transfer from the zone's master. The server doesn't check the + serial of the master's zone. This command is valid for slave zones. + +**zone-notify** [*zone*...] + Trigger a NOTIFY message to all configured remotes. This can help in cases + when previous NOTIFY had been lost or the slaves offline. + +**zone-flush** [*zone*...] [**+outdir** *directory*] + Trigger a zone journal flush into the zone file. If output dir is specified, + instead of flushing the zonefile, the zone is dumped to a file in the specified + directory. + +**zone-sign** [*zone*...] + Trigger a DNSSEC re-sign of the zone. Existing signatures will be dropped. + This command is valid for zones with DNSSEC signing enabled. + +**zone-ksk-submitted** *zone*... + Use when the zone's KSK rollover is in submittion phase. By calling this command + the user confirms manually that the parent zone contains DS record for the new + KSK in submission phase and the old KSK can be retired. + +**zone-freeze** [*zone*...] + Temporarily postpone zone-changing events (load, refresh, update, flush, and + DNSSEC signing). + +**zone-thaw** [*zone*...] + Dismiss zone freeze. + +**zone-read** *zone* [*owner* [*type*]] + Get zone data that are currently being presented. + +**zone-begin** *zone*... + Begin a zone transaction. + +**zone-commit** *zone*... + Commit the zone transaction. All changes are applied to the zone. + +**zone-abort** *zone*... + Abort the zone transaction. All changes are discarded. + +**zone-diff** *zone* + Get zone changes within the transaction. + +**zone-get** *zone* [*owner* [*type*]] + Get zone data within the transaction. + +**zone-set** *zone* *owner* [*ttl*] *type* *rdata* + Add zone record within the transaction. The first record in a rrset + requires a ttl value specified. + +**zone-unset** *zone* *owner* [*type* [*rdata*]] + Remove zone data within the transaction. + +**zone-purge** *zone*... [*filter*...] + Purge zone data, zone file, journal, timers, and/or KASP data of specified zones. + Available filters are **+expire**, **+zonefile**, **+journal**, **+timers**, + and **+kaspdb**. If no filter is specified, all filters are enabled. + If the zone is no longer configured, add **+orphan** filter (zone file cannot + be purged in this case). + +**zone-stats** *zone* [*module*\ [\ **.**\ *counter*\ ]] + Show zone statistics counter(s). To print also counters with value 0, use + force option. + +**conf-init** + Initialize the configuration database. (*) + +**conf-check** + Check the server configuration. (*) + +**conf-import** *filename* + Import a configuration file into the configuration database. Ensure the + server is not using the configuration database! (*) + +**conf-export** [*filename*] + Export the configuration database into a config file or stdout. (*) + +**conf-list** [*item*] + List the configuration database sections or section items. + +**conf-read** [*item*] + Read the item from the active configuration database. + +**conf-begin** + Begin a writing configuration database transaction. Only one transaction + can be opened at a time. + +**conf-commit** + Commit the configuration database transaction. + +**conf-abort** + Rollback the configuration database transaction. + +**conf-diff** [*item*] + Get the item difference in the transaction. + +**conf-get** [*item*] + Get the item data from the transaction. + +**conf-set** *item* [*data*...] + Set the item data in the transaction. + +**conf-unset** [*item*] [*data*...] + Unset the item data in the transaction. + +Note +.... + +Empty or **--** *zone* parameter means all zones or all zones with a transaction. + +Use **@** *owner* to denote the zone name. + +Type *item* parameter in the form of *section*\ [**[**\ *id*\ **]**\ ][**.**\ *name*]. + +(*) indicates a local operation which requires a configuration. + +Interactive mode +................ + +The utility provides interactive mode with basic line editing functionality, +command completion, and command history. + +Interactive mode behavior can be customized in `~/.editrc`. Refer to +:manpage:`editrc(5)` for details. + +Command history is saved in `~/.knotc_history`. + +Examples +-------- + +Reload the whole server configuration +..................................... + +:: + + $ knotc reload + +Flush the example.com and example.org zones +........................................... + +:: + + $ knotc zone-flush example.com example.org + +Get the current server configuration +.................................... + +:: + + $ knotc conf-read server + +Get the list of the current zones +................................. + +:: + + $ knotc conf-read zone.domain + +Get the master remotes for the example.com zone +............................................... + +:: + + $ knotc conf-read 'zone[example.com].master' + +Add example.org zone with a zonefile location +............................................. + +:: + + $ knotc conf-begin + $ knotc conf-set 'zone[example.org]' + $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone' + $ knotc conf-commit + +Get the SOA record for each configured zone +........................................... + +:: + + $ knotc zone-read -- @ SOA + +See Also +-------- + +:manpage:`knotd(8)`, :manpage:`knot.conf(5)`, :manpage:`editrc(5)`. diff --git a/doc/man_knotd.rst b/doc/man_knotd.rst new file mode 100644 index 0000000..8adce89 --- /dev/null +++ b/doc/man_knotd.rst @@ -0,0 +1,48 @@ +.. highlight:: console + +knotd – Knot DNS server daemon +============================== + +Synopsis +-------- + +:program:`knotd` [*parameters*] + +Description +----------- + +Parameters +.......... + +**-c**, **--config** *file* + Use a textual configuration file (default is :file:`@config_dir@/knot.conf`). + +**-C**, **--confdb** *directory* + Use a binary configuration database directory (default is :file:`@storage_dir@/confdb`). + The default configuration database, if exists, has a preference to the default + configuration file. + +**-m**, **--max-conf-size** *MiB* + Set maximum configuration size (default is @conf_mapsize@ MiB, maximum 10000 MiB). + +**-s**, **--socket** *path* + Use a remote control UNIX socket path (default is :file:`@run_dir@/knot.sock`). + +**-d**, **--daemonize** [*directory*] + Run the server as a daemon. New root directory may be specified + (default is :file:`/`). + +**-v**, **--verbose** + Enable debug output. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +See Also +-------- + +:manpage:`knot.conf(5)`, :manpage:`knotc(8)`, :manpage:`keymgr(8)`, +:manpage:`kjournalprint(8)`. diff --git a/doc/man_knsec3hash.rst b/doc/man_knsec3hash.rst new file mode 100644 index 0000000..1c2c95b --- /dev/null +++ b/doc/man_knsec3hash.rst @@ -0,0 +1,49 @@ +.. highlight:: console + +knsec3hash – NSEC hash computation utility +========================================== + +Synopsis +-------- + +:program:`knsec3hash` *salt* *algorithm* *iterations* *name* + +Description +----------- + +This utility generates a NSEC3 hash for a given domain name and parameters of NSEC3 hash. + +Parameters +.......... + +*salt* + Specifies a binary salt encoded as a hexadecimal string. + +*algorithm* + Specifies a hashing algorithm by number. Currently, the only supported algorithm is SHA-1 (number 1). + +*iterations* + Specifies the number of additional iterations of the hashing algorithm. + +*name* + Specifies the domain name to be hashed. + +Examples +-------- + +:: + + $ knsec3hash c01dcafe 1 10 knot-dns.cz + 7PTVGE7QV67EM61ROS9238P5RAKR2DM7 (salt=c01dcafe, hash=1, iterations=10) + +:: + + $ knsec3hash - 1 0 net + A1RT98BS5QGC9NFI51S9HCI47ULJG6JH (salt=-, hash=1, iterations=0) + +See Also +-------- + +:rfc:`5155` – DNS Security (DNSSEC) Hashed Authenticated Denial of Existence. + +:manpage:`knotc(8)`, :manpage:`knotd(8)`. diff --git a/doc/man_knsupdate.rst b/doc/man_knsupdate.rst new file mode 100644 index 0000000..c93f48f --- /dev/null +++ b/doc/man_knsupdate.rst @@ -0,0 +1,164 @@ +.. highlight:: console + +knsupdate – Dynamic DNS update utility +====================================== + +Synopsis +-------- + +:program:`knsupdate` [*options*] [*filename*] + +Description +----------- + +This utility sends Dynamic DNS update messages to a DNS server. Update content +is read from a file (if the parameter *filename* is given) or from the standard +input. + +The format of updates is textual and is made up of commands. Every command is +placed on the separate line of the input. Lines starting with a semicolon are +comments and are not processed. + +Options +....... + +**-d** + Enable debug messages. + +**-h**, **--help** + Print the program help. + +**-k** *keyfile* + Use the TSIG key stored in a file *keyfile* to authenticate the request. The + file should contain the key in the same format, which is accepted by the + **-y** option. + +**-p** *port* + Set the port to use for connections to the server (if not explicitly specified + in the update). The default is 53. + +**-r** *retries* + The number of retries for UDP requests. The default is 3. + +**-t** *timeout* + The total timeout (for all UDP update tries) of the update request in seconds. + The default is 12. If set to zero, the timeout is infinite. + +**-v** + Use a TCP connection. + +**-V**, **--version** + Print the program version. + +**-y** [*alg*:]\ *name*:*key* + Use the TSIG key with a name *name* to authenticate the request. The *alg* + part specifies the algorithm (the default is hmac-sha256) and *key* specifies + the shared secret encoded in Base64. + +Commands +........ + +**server** *name* [*port*] + Specifies a receiving server of the dynamic update message. The *name* parameter + can be either a host name or an IP address. If the *port* is not specified, + the default port is used. The default port value can be controlled using + the **-p** program option. + +**local** *address* [*port*] + Specifies outgoing *address* and *port*. If no local is specified, the + address and port are set by the system automatically. The default port number + is 0. + +**zone** *name* + Specifies that all updates are done within a zone *name*. If not used, + the default zone is the root zone. + +**origin** *name* + Specifies fully qualified domain name suffix which is appended to non-fqd + owners in update commands. The default origin is the root zone. + +**class** *name* + Sets *name* as the default class for all updates. If not used, the default + class is IN. + +**ttl** *value* + Sets *value* as the default TTL (in seconds). If not used, the default value + is 0. + +**key** [*alg*:]\ *name* *key* + Specifies the TSIG *key* named *name* to authenticate the request. An optional + *alg* algorithm can be specified. This command has the same effect as + the program option **-y**. + +[**prereq**] **nxdomain** *name* + Adds a prerequisite for a non-existing record owned by *name*. + +[**prereq**] **yxdomain** *name* + Adds a prerequisite for an existing record owned by *name*. + +[**prereq**] **nxrrset** *name* [*class*] *type* + Adds a prerequisite for a non-existing record of the *type* owned by *name*. + Internet *class* is expected. + +[**prereq**] **yxrrset** *name* [*class*] *type* [*data*] + Adds a prerequisite for an existing record of the *type* owned by *name* + with optional *data*. Internet *class* is expected. + +[**update**] **add** *name* [*ttl*] [*class*] *type* *data* + Adds a request to add a new resource record into the zone. + Please note that if the *name* is not fully qualified domain name, the + current origin name is appended to it. + +[**update**] **del**\[**ete**] *name* [*ttl*] [*class*] [*type*] [*data*] + Adds a request to remove all (or matching *class*, *type* or *data*) + resource records from the zone. There is the same requirement for the *name* + parameter as in **update add** command. The *ttl* item is ignored. + +**show** + Displays current content of the update message. + +**send** + Sends the current update message and cleans the list of updates. + +**answer** + Displays the last answer from the server. + +**debug** + Enable debugging. This command has the same meaning as the **-d** program option. + +**quit** + Quit the program. + +Notes +----- + +Options **-k** and **-y** can not be used simultaneously. + +Dnssec-keygen keyfile format is not supported. Use :manpage:`keymgr(8)` instead. + +Zone name/server guessing is not supported if the zone name/server is not specified. + +Empty line doesn't send the update. + +Examples +-------- + +1. Send one update of the zone example.com to the server 192.168.1.1. The update + contains two new records:: + + $ knsupdate + > server 192.168.1.1 + > zone example.com. + > origin example.com. + > ttl 3600 + > add test1.example.com. 7200 A 192.168.2.2 + > add test2 TXT "hello" + > show + > send + > answer + > quit + +See Also +-------- + +:manpage:`kdig(1)`, :manpage:`khost(1)`, :manpage:`keymgr(8)`. diff --git a/doc/man_kzonecheck.rst b/doc/man_kzonecheck.rst new file mode 100644 index 0000000..1858bca --- /dev/null +++ b/doc/man_kzonecheck.rst @@ -0,0 +1,45 @@ +.. highlight:: console + +kzonecheck – Knot DNS zone file checking tool +============================================= + +Synopsis +-------- + +:program:`kzonecheck` [*options*] *filename* + +Description +----------- + +The utility checks zone file syntax and runs semantic checks on the zone +content. The executed checks are the same as the checks run by the Knot +DNS server. + +Please, refer to the ``semantic-checks`` configuration option in +:manpage:`knot.conf(5)` for the full list of available semantic checks. + +Options +....... + +**-o**, **--origin** *origin* + Zone origin. If not specified, the origin is determined from the file name + (possibly removing the ``.zone`` suffix). + +**-t**, **--time** *time* + Current time specification. Use UNIX timestamp, YYYYMMDDHHmmSS + format, or [+/-]\ *time*\ [unit] format, where unit can be **Y**, **M**, + **D**, **h**, **m**, or **s**. Default is current UNIX timestamp. + +**-v**, **--verbose** + Enable debug output. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +See Also +-------- + +:manpage:`knotd(8)`, :manpage:`knot.conf(5)`. |