Thu 14 Jul 2016  



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


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


getdns_query is built and installed by default

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


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>

    +sit=<cookie>        Send along cookie OPT with value <cookie>
    +0            Clear all extensions

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

    -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
# UDP only stub mode query for A record
getdns_query @<serverIP> -s -a -A
# TCP only stub mode query for A record
getdns_query @<serverIP> -s -a -A  -l T
# TLS only stub mode query for A record
getdns_query @<serverIP> -s -a -A  -l L
# TLS only stub mode query for A record
getdns_query @<serverIP> -s -a -A -l LT
# 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

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.


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: [, 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:
      , tls_auth_name: ""
      , tls_pubkey_pinset:
        [ { digest: "sha256"
          , value: 0x7e8c59467221f606695a797ecc488a6b4109dab7421aba0c5a6d3681ac5273d4
        } ]
     } ]
     , tls_authentication: GETDNS_AUTHENTICATION_REQUIRED
     , listen_addresses: [, 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 }
    } ]

Other by Sara Dickinson

  DNS Privacy
  Sun 16 Jul 2017
  Tutorial @ IETF99
  Sara Dickinson   DNS Privacy
DNS Privacy tutorial at the IETF99 in Prague
  DNS Privacy
  Thu 06 Jul 2017
  Sara Dickinson   DNS Privacy
DNS Privacy tutorial at the JCSA17 in Paris
  Hands on getdns
  Thu 06 Jul 2017
  Sara Dickinson   Willem Toorop
Tutorial at the JCSA17 in Paris
  IETF98 Hackathon results
  Sun 26 Mar 2017
  Hackathon @ IETF98
  Sara Dickinson   Hackathon   1.1.0 release
Overview of the DNS hackathon projects at the IETF98
  DNS Privacy
  Sun 13 Nov 2016
  Tutorial @ IETF97
  Sara Dickinson   Stubby   DNS Privacy
DNS Privacy tutorial mentioning stubby at the IETF97 in Seoul
  DNSSEC for Legacy Applications
  Wed 21 Oct 2015
  Sara Dickinson
Presentation about an experimental nsswitch getdns component
  getdns API
  Thu 26 Mar 2015
  Bits-n-Bites @ IETF92
  Sara Dickinson   Gowri Visweswaran   Willem Toorop
Poster presentation at the Bits-n-Bites of the IETF92