Adding upstream version 3.4.0.upstream/3.4.0upstream

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

1 files changed, 465 insertions, 0 deletions

diff --git a/doc/man/kdig.1 b/doc/man/kdig.1
new file mode 100644
index 0000000..207c8c8
--- /dev/null
+++ b/doc/man/kdig.1
@@ -0,0 +1,465 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.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
+..
+.TH "KDIG" "1" "2024-09-02" "3.4.0" "Knot DNS"
+.SH NAME
+kdig \- Advanced DNS lookup utility
+.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
+.B \fIquery\fP
+\fIname\fP | \fB\-q\fP \fIname\fP | \fB\-x\fP \fIaddress\fP | \fB\-G\fP \fItapfile\fP
+.TP
+.B \fIcommon\-settings\fP, \fIsettings\fP
+[\fIquery_class\fP] [\fIquery_type\fP] [\fB@\fP\fIserver\fP]... [\fIoptions\fP]
+.TP
+.B \fIname\fP
+Is a domain name that is to be looked up.
+.TP
+.B \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. A value which begins
+with \(aq/\(aq character is considered an absolute UNIX socket path. 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 SOA serial number
+(i.e. all zone updates since the specified zone version are to be returned).
+.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. The option \fB\-VV\fP makes the program
+print the compile time configuration summary.
+.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 base64, 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]\fBopttext\fP
+Try to show unknown EDNS options as text.
+.TP
+\fB+\fP[\fBno\fP]\fBoptpresent\fP
+Show EDNS in presentation format according to the specification in version
+\fI\%draft\-peltan\-edns\-presentation\-format\-01\fP\&.
+.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.
+.TP
+\fB+\fP[\fBno\fP]\fBignore\fP
+Don\(aqt use TCP automatically if a truncated reply is received.
+.TP
+\fB+\fP[\fBno\fP]\fBkeepopen\fP
+Keep TCP connection open for the following query if it has the same connection
+configuration. This applies to +tcp, +tls, and +https operations. The connection
+is considered in the context of a single kdig call only.
+.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]\fBtls\-keyfile\fP=\fIFILE\fP
+Use TLS with a client keyfile.
+.TP
+\fB+\fP[\fBno\fP]\fBtls\-certfile\fP=\fIFILE\fP
+Use TLS with a client certfile.
+.TP
+\fB+\fP[\fBno\fP]\fBtls\-ocsp\-stapling\fP[=\fIH\fP]
+Use TLS with a valid stapled OCSP response for the server certificate
+(%u or specify hours). OCSP responses older than the specified period are
+considered invalid.
+.TP
+\fB+\fP[\fBno\fP]\fBhttps\fP[=\fIURL\fP]
+Use HTTPS (DNS\-over\-HTTPS) in wire format (\fI\%RFC 1035#section\-4.2.1\fP).
+It is also possible to specify URL=[authority][/path] where request
+will be sent to. Any leading scheme and authority indicator (i.e. //) are ignored.
+Authority might also be specified as the \fIserver\fP (using the parameter \fI@\fP).
+If \fIpath\fP is specified and \fIauthority\fP is missing, then the \fIserver\fP
+is used as authority together with the specified \fIpath\fP\&.
+Library \fIlibnghttp2\fP is required.
+.TP
+\fB+\fP[\fBno\fP]\fBhttps\-get\fP
+Use HTTPS with HTTP/GET method instead of the default HTTP/POST method.
+Library \fIlibnghttp2\fP is required.
+.TP
+\fB+\fP[\fBno\fP]\fBquic\fP
+Use QUIC (DNS\-over\-QUIC).
+.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 1232 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). EDNS(0) is enabled by default.
+.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. Zero value or \fInotimeout\fP is interpreted as
+infinity.
+.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]\fBexpire\fP
+Sets the EXPIRE EDNS option.
+.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+\fP[\fBno\fP]\fBproxy\fP=\fISRC_ADDR\fP[#\fISRC_PORT\fP]\-\fIDST_ADDR\fP[#\fIDST_PORT\fP]
+Add PROXYv2 header with the specified source and destination addresses to the query.
+The default source port is 0 and destination port 53.
+.TP
+\fB+\fP[\fBno\fP]\fBjson\fP
+Use JSON for output encoding (RFC 8427).
+.TP
+\fB+noidn\fP
+Disable the IDN transformation to ASCII and vice versa. IDN support depends
+on libidn2 availability during project building! If used in \fIcommon\-settings\fP,
+all IDN transformations are disabled. If used in the individual query \fIsettings\fP,
+transformation from ASCII is disabled on output for the particular query. Note
+that IDN transformation does not preserve domain name letter case.
+.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 EXIT VALUES
+.sp
+Exit status of 0 means successful operation. Any other exit status indicates
+an error.
+.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
+.IP 5. 3
+DNS over HTTPS examples (various DoH implementations):
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ kdig @1.1.1.1 +https example.com.
+$ kdig @193.17.47.1 +https=/doh example.com.
+$ kdig @8.8.4.4 +https +https\-get example.com.
+$ kdig @8.8.8.8 +https +tls\-hostname=dns.google +fastopen example.com.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 6. 3
+More queries share one DoT connection:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ kdig @1.1.1.1 +tls +keepopen abc.example.com A mail.example.com AAAA
+.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–2024, CZ.NIC, z.s.p.o.
+.\" Generated by docutils manpage writer.
+.