distributed-dig

Quick Start

Installation

Install globally:

npm install -g distributed-dig

Usage

Lookup a single domain:

ddig domain

Overview

A utility which makes DNS lookup requests across multiple DNS resolvers and collates the results.

Useful for checking if a DNS record has been fully propagated, or for querying the origins behind an AWS Route 53 / Azure Traffic Manager record (or any other DNS-based load balancing solution).

Installation

Installing globally is recommended:

npm install -g distributed-dig

Usage

ddig domain [domain [domain] ...] [options]

Options

The following options are available:

--port <number>                  Specify the DNS port [53]
--protocol <upd|tcp>             Specify the DNS protocol [udp]
--timeout <number>               Specify the DNS timeout in milliseconds [2500]
--edns <true|false>              Enable or disable EDNS(0) [false]
--config <filename>              Specify an alternative configuration file
--list-resolvers                 List resolvers configured in config file
--list-options                   List DNS request options configured in config file
--list-defaults                  Print json of default config file settings
--verbose                        Outputs more information
--no-color                       Switches off colour output
--version                        Display version number
--help                           Display this help

port

Specify the TCP/UDP port tro use when connecting to the DNS resolver. Default: 53

protocol

Specify whether to use UDP or TCP when connecting to the DNS resolver. Default: udp

timeout

Specifies the timeout in milliseconds to wait for a response from each DNS resolver. Default: 2500 (2.5 seconds)

edns

Enables EDNS(0) Default: false (disabled)

With EDNS(0) enabled, if an upstream resolver doesn't support it then the standard DNS will be used as a fallback. Even though EDNS is support by ~90% of resolvers on the internet [^1], it is disabled by default in ddig as it may cause the resolver to return the IP address it considers closest to you, which is counter-productive to the purpose of querying many geographically distributed DNS resolvers.

[^1]: Internet Systems Consortium - Partial EDNS Compliance Hampers Deployment of New DNS Features

config

Specifies an alternative configuration file.

To create a custom config you can:

1. pipe --list-defaults to a new file: ddig --list-defaults > custom.json
2. Edit custom.json
3. Use the new configuration file: ddig --config [path]custom.json example.com

list-resolvers

Lists the resolvers configured in the distributed-dig.json config file:

list-options

Lists the options configured in the distributed-dig.json config file:

list-defaults

Prints out a sample default config file in raw json. Pipe it to a file for an initial customised configuration file.

verbose

Switches on verbose mode which outputs the following additional fields:

• Full recursive answer (i.e. nested cname records)
• Resolver IP Address
• Response time

--verbose also modifies the --list-resolvers and --list-options switches.

no-color

If your terminal has problems rendering the colour output then you can switch it off by using --no-color.

version

Prints out distributed-dig's version number.

help

Displays the help screen:

Examples

Lookup a single domain

• List the IP address returned for www.asos.com from each of the configured resolver:

ddig www.asos.com

Lookup a single domain with verbose enabled

• List the IP address and full recursive path returned for www.asos.com from each of the configured resolver:

ddig www.asos.com --verbose

Lookup multiple domains with an increased timeout

• List the IP addresses returned for both www.asos.com & secure.asos.com from each of the configured resolver with a 5 second timeout:

ddig www.asos.com my.asos.com secure.asos.com --timeout 5000

Features

Lookup a domain from a URL

As of version 1.8.0 you can provide a URL and the domain will be extracted. This is handy when performing a copy/paste from a browser's address bar.

ddig https://www.example.com

Unique IP Address Identifier

The first occurrence of each unique IP address is marked by a bullet point:

Unicode Support detection for Unique Address Identifier character

The bullet point character used is U+2022 • BULLET (HTML •). If it is detected that the output is being piped (to a file or to more | cat) then the ascii character 42 * Asterisk (HTML *)

Filtering out just unique addresses

As of version 1.7.0 there is an option to provide a --unique switch which lists only the first occurrence of each distinct IP address returned. N.B. It will not filter out errors

Column Width Warning

If you use the --verbose switch and have a terminal window that's narrower than 130 columns you'll see a warning:

Configuration File

All Options and Resolvers are configured in distributed-dig.json file. This file can exist in any of the following locations:

• The current working directory - node -p process.cwd()
• The home directory - node -p require('os').homedir()
• The application's root directory (i.e. the same directory as distributed-dig.js)

Request Options

The default options are:

"options": {
    "request": {
      "port": 53,
      "type": "udp",
      "timeout": 2500,
      "try_edns": false,
      "cache": false
    },
    "question": {
      "type": "A"
    }
}

DNS Resolvers

Resolvers are configured in an array with each resolver having a nameServer element which should be the IPv4 or IPv6 address, and a provider element which is just a free-form text label:

"resolvers": [
    {
      "nameServer": "208.67.222.222",
      "provider": "OpenDNS (Primary)"
    },
    {
      "nameServer": "208.67.220.220",
      "provider": "OpenDNS (Secondary)"
    },
    {
      "nameServer": "217.199.173.113",
      "provider": "United Kingdom"
    }
]

You can find a list of public DNS servers on publicdnsserver.com, and tailor the configured list for your own requirements.

Debugging

distributed-dig uses the npm package debug. If you set the environment variable debug to ddig you'll see full debug output.

Windows

set debug=ddig

Linux

DEBUG=ddig

Powershell

$env:debug="ddig"