Background

getdns_query was originally developed as a test tool for the getdns API. In 1.0 it is used as such, but in the 1.1 it will be build by default. It can be considered as a command line wrapper for getdns exposing the features of this implementation (both in the official API and the additional API functions).

Building getdns_query

1.0

either include the --with-getdns_query option when running configure or build separately using make getdns_query

Executable is found in the build directory under src/test

1.1

getdns_query is built and installed by default

Executable is found in the build directory under src/tools and installed by default.

Usage

usage: getdns_query [<option> ...] \
    [@<upstream> ...] [+<extension> ...] ['{ <settings> }'] [<name>] [<type>]

default mode: recursive, synchronous resolution of NS record
        using UDP with TCP fallback

upstreams: @<ip>[%<scope_id>][@<port>][#<tls port>][~<tls name>][^<tsig spec>]
            <ip>@<port> may be given as <IPv4>:<port>
                  or '['<IPv6>[%<scope_id>]']':<port> too

tsig spec: [<algorithm>:]<name>:<secret in Base64>

extensions:
    +add_warning_for_bad_dns
    +dnssec_return_status
    +dnssec_return_only_secure
    +dnssec_return_all_statuses
    +dnssec_return_validation_chain
    +dnssec_return_full_validation_chain
    +dnssec_roadblock_avoidance
    +edns_cookies
    +return_both_v4_and_v6
    +return_call_reporting
    +sit=<cookie>        Send along cookie OPT with value <cookie>
    +specify_class=<class>
    +0            Clear all extensions

settings in json dict format (like outputted by -i option).

options:
    -a    Perform asynchronous resolution (default = synchronous)
    -A    address lookup (<type> is ignored)
    -B    Batch mode. Schedule all messages before processing responses.
    -b <bufsize>    Set edns0 max_udp_payload size
    -c    Send Client Subnet privacy request
    -C    <filename>
        Read settings from config file <filename>
        The getdns context will be configured with these settings
        The file must be in json dict format.
    -D    Set edns0 do bit
    -d    clear edns0 do bit
    -e <idle_timeout>    Set idle timeout in miliseconds
    -F <filename>    read the queries from the specified file
    -f <filename>    Read DNSSEC trust anchors from <filename>
    -G    general lookup
    -H    hostname lookup. (<name> must be an IP address; <type> is ignored)
    -h    Print this help
    -i    Print api information
    -I    Interactive mode (> 1 queries on same context)
    -j    Output json response dict
    -J    Pretty print json response dict
    -k    Print root trust anchors
    -K <pin>    Pin a public key for TLS connections (can repeat)
        (should look like 'pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="')
    -n    Set TLS authentication mode to NONE (default)
    -m    Set TLS authentication mode to REQUIRED
    -p    Pretty print response dict
    -P <blocksize>    Pad TLS queries to a multiple of blocksize
    -q    Quiet mode - don't print response
    -r    Set recursing resolution type
    -R <filename>    Read root hints from <filename>
    -s    Set stub resolution type (default = recursing)
    -S    service lookup (<type> is ignored)
    -t <timeout>    Set timeout in miliseconds
    -x    Do not follow redirects
    -X    Follow redirects (default)
    -0    Append suffix to single label first (default)
    -W    Append suffix always
    -1    Append suffix only to single label after failure
    -M    Append suffix only to multi label name after failure
    -N    Never append a suffix
    -Z <suffixes>    Set suffixes with the given comma separed list
    -T    Set transport to TCP only
    -O    Set transport to TCP only keep connections open
    -L    Set transport to TLS only keep connections open
    -E    Set transport to TLS with TCP fallback only keep connections open
    -u    Set transport to UDP with TCP fallback (default)
    -U    Set transport to UDP only
    -l <transports>    Set transport list. List can contain 1 of each of the characters
             U T L S for UDP, TCP or TLS e.g 'UT' or 'LTU' 
    -z <listen address>
        Listen for DNS requests on the given IP address
        <listen address> is in the same format as upstreams.
        This option can be given more than once.

Example queries

# UDP only recursive query for A record
getdns_query @<serverIP>      -a -A       example.com
# UDP only stub mode query for A record
getdns_query @<serverIP> -s -a -A         example.com
# TCP only stub mode query for A record
getdns_query @<serverIP> -s -a -A  -l T   example.com
# TLS only stub mode query for A record
getdns_query @<serverIP> -s -a -A  -l L   example.com
# TLS only stub mode query for A record
getdns_query @<serverIP> -s -a -A -l LT   example.com
# TLS only stub mode query for A record in Strict mode using server hostname for authentication)
getdns_query @<serverIP>~<hostname> -s -a -A -l L -m example.com

Adding the +return_call_reporting option provides and extra section in the response dict that reports details of the transport and authentication used for the transport the query was actually performed over. Note that recursive mode does not support TLS.

Updates

New in 1.0.0b2

getdns_query can now listen for and answer DNS requests through the library configured with the normal command line options, by providing the IP(6) addresses to listen on with the -z option. The getdns_context used by getdns_query can now also be configured with the help of a configuration file (given with the -C option). The configuration file format is the JSON like format that it is returned by the getdns_pretty_print_*() functions. The pretty printed version of the getdns_dict returned by getdns_context_get_api_information() can be used as a configuration file directly, but a less verbose form is also accepted. Below a few examples:

• To configure getdns_query to listen on localhost port 53, and use the local default upstream, but fall back to full recursion when DNSSEC validation fails (i.e. roadblock avoidance)

  { resolution_type: GETDNS_RESOLUTION_STUB
  , dnssec_roadblock_avoidance: GETDNS_EXTENSION_TRUE
  , listen_addresses: [ 127.0.0.1, 0::1 ]
  }
  

• To configure getdns_query to listen on localhost port 53, and operate as a stub resolver to a remote authenticated TLS upstream:

  { resolution_type: GETDNS_RESOLUTION_STUB
  , dns_transport_list: [ GETDNS_TRANSPORT_TLS ]
  , upstream_recursive_servers:
  [ { address_data: 185.49.141.38
    , tls_auth_name: "getdnsapi.net"
    , tls_pubkey_pinset:
      [ { digest: "sha256"
        , value: 0x7e8c59467221f606695a797ecc488a6b4109dab7421aba0c5a6d3681ac5273d4
      } ]
   } ]
   , tls_authentication: GETDNS_AUTHENTICATION_REQUIRED
   , listen_addresses: [ 127.0.0.1, 0::1 ]
  }
  

• To setup getdns_query with the root servers and trust anchor for the yeti domain name space:

  { dns_root_servers:
  [ 240c:f:1:22::6, 2001:559:8000::6, 2001:200:1d9::35
  , 2a02:cdc5:9715:0:185:5:203:53, 2001:4b98:dc2:45:216:3eff:fe4b:8c5b
  , 2a02:2810:0:405::250, 2001:6d0:6d06::53, 2a01:4f8:161:6106:1::10
  , 2001:e30:1c1e:1::333, 2001:1608:10:167:32e::53
  , 2604:6600:2000:11::4854:a010, 2001:67c:217c:6::2, 2a02:ec0:200::1
  , 2001:620:0:ff::29, 2001:1398:1:21::8001, 2001:da8:a3:a027::6
  , 2001:da8:268:4200::6, 2400:a980:30ff::6, 2c0f:f530::6, 2803:80:1004:63::1
  , 2400:8901:e001:39::6, 2a05:78c0:0:2::3:6, 2401:c900:1401:3b:c::6
  , 2001:e30:1c1e:10::333, 2001:e30:187d::333
  ]
  , dnssec_trust_anchors:
  [ { name : ., type: GETDNS_RRTYPE_DS
    , rdata:
      { key_tag: 55954, algorithm: 8, digest_type: 2
      , digest : 0x88ff12f948bfbe666ac91b1256bb5b77b51150991a5e50f80a9fab73945ba2aa }
  } ]
  }