Thu 14 Jul 2016  

getdns_query

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.

Updates

New in 1.1.0a1

The version of getdns_query in 1.1.0a1 is suitable to run getdns locally as a DNS-over-TLS stub resolver (see: https://portal.sinodun.com/wiki/display/TDNS/DNS+Privacy+daemon )

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 }
    } ]
    }
    

Other by Sara Dickinson

  IETF98 Hackathon results
  Sun 26 Mar 2017
  Hackathon @ IETF98
  Sara Dickinson   Hackathon   1.1.0 release
Overview of the DNS hackthon projects at the IETF98
  DNS Privacy
  Sun 13 Nov 2016
  Tutorial @ IETF97
  Sara Dickinson   Stubby
DNS Privacy tutorial mentioning stubby at the IETF97 in Seoul
  DNSSEC for Legacy Applications
  Wed 21 Oct 2015
  DNSSEC-WS @ ICANN54
  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