diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man/kdig.1in | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/doc/man/kdig.1in b/doc/man/kdig.1in new file mode 100644 index 0000000..714eaf9 --- /dev/null +++ b/doc/man/kdig.1in @@ -0,0 +1,460 @@ +.\" 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" "@RELEASE_DATE@" "@VERSION@" "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 +\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. 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. +.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]\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 4096 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. 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 libidn 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–2023, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. |