diff options
Diffstat (limited to 'doc/man_kdig.rst')
| -rw-r--r-- | doc/man_kdig.rst | 396 |
1 files changed, 396 insertions, 0 deletions
diff --git a/doc/man_kdig.rst b/doc/man_kdig.rst new file mode 100644 index 0000000..4457b68 --- /dev/null +++ b/doc/man_kdig.rst @@ -0,0 +1,396 @@ +.. highlight:: none + +``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. A value which begins + with '/' character is considered an absolute UNIX socket path. 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 SOA serial number + (i.e. all zone updates since the specified zone version are to be returned). + +**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 base64, 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**\ ]\ **opttext** + Try to show unknown EDNS options as text. + +**+**\ [\ **no**\ ]\ **optpresent** + Show EDNS in presentation format according to the specification in version + `draft-peltan-edns-presentation-format-01 <https://www.ietf.org/archive/id/draft-peltan-edns-presentation-format-01.html>`_. + +**+**\ [\ **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. + +**+**\ [\ **no**\ ]\ **ignore** + Don't use TCP automatically if a truncated reply is received. + +**+**\ [\ **no**\ ]\ **keepopen** + 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. + +**+**\ [\ **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**\ ]\ **tls-keyfile**\ =\ *FILE* + Use TLS with a client keyfile. + +**+**\ [\ **no**\ ]\ **tls-certfile**\ =\ *FILE* + Use TLS with a client certfile. + +**+**\ [\ **no**\ ]\ **tls-ocsp-stapling**\[\ =\ *H*\] + 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. + +**+**\ [\ **no**\ ]\ **https**\[\ =\ *URL*\] + Use HTTPS (DNS-over-HTTPS) in wire format (:rfc:`1035#section-4.2.1`). + 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 *server* (using the parameter `@`). + If *path* is specified and *authority* is missing, then the *server* + is used as authority together with the specified *path*. + Library *libnghttp2* is required. + +**+**\ [\ **no**\ ]\ **https-get** + Use HTTPS with HTTP/GET method instead of the default HTTP/POST method. + Library *libnghttp2* is required. + +**+**\ [\ **no**\ ]\ **quic** + Use QUIC (DNS-over-QUIC). + +**+**\ [\ **no**\ ]\ **nsid** + Request the nameserver identifier (NSID). + +**+**\ [\ **no**\ ]\ **bufsize**\ =\ *B* + Set EDNS buffer size in bytes (default is 4096 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. Zero value or *notimeout* is interpreted as + infinity. + +**+**\ [\ **no**\ ]\ **retry**\ =\ *N* + Set the number (>=0) of UDP retries (default is 2). This doesn't apply to + AXFR/IXFR. + +**+**\ [\ **no**\ ]\ **expire** + Sets the EXPIRE EDNS option. + +**+**\ [\ **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. + +**+**\ [\ **no**\ ]\ **proxy**\ =\ *SRC_ADDR*\[#\ *SRC_PORT*\]-*DST_ADDR*\[#\ *DST_PORT*\] + Add PROXYv2 header with the specified source and destination addresses to the query. + The default source port is 0 and destination port 53. + +**+**\ [\ **no**\ ]\ **json** + Use JSON for output encoding (RFC 8427). + +**+noidn** + Disable the IDN transformation to ASCII and vice versa. IDN support depends + on libidn availability during project building! If used in *common-settings*, + all IDN transformations are disabled. If used in the individual query *settings*, + transformation from ASCII is disabled on output for the particular query. Note + that IDN transformation does not preserve domain name letter case. + +Notes +----- + +Options **-k** and **-y** can not be used simultaneously. + +Dnssec-keygen keyfile format is not supported. Use :manpage:`keymgr(8)` instead. + +Exit values +----------- + +Exit status of 0 means successful operation. Any other exit status indicates +an error. + +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 + +5. DNS over HTTPS examples (various DoH implementations):: + + $ 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. + +6. More queries share one DoT connection:: + + $ kdig @1.1.1.1 +tls +keepopen abc.example.com A mail.example.com AAAA + +Files +----- + +:file:`/etc/resolv.conf` + +See Also +-------- + +:manpage:`khost(1)`, :manpage:`knsupdate(1)`, :manpage:`keymgr(8)`. |