README.md

# Homer

Homer is a DoH (DNS-over-HTTPS) and DoT (DNS-over-TLS) client. Its
main purpose is to test DoH and DoT resolvers.

It is currently quite experimental.

## Usage

Two mandatory arguments, the URL of the DoH server (or name/address of
the DoT resolver), and a domain name to query. By default, Homer uses
DoH. Also by defaut, the type of data is AAAA (IP address). You can
add a third argument to use another type, as in the second example
below.

```
% homer https://doh.powerdns.org/ framagit.org
id 0
opcode QUERY
rcode NOERROR
flags QR RD RA
;QUESTION
framagit.org. IN AAAA
;ANSWER
framagit.org. 10800 IN AAAA 2a01:4f8:200:1302::42
;AUTHORITY
;ADDITIONAL
Total elapsed time: 0.40 seconds (402.28 ms/request)

% homer --dot 9.9.9.9 cocca.fr A
id 42545
opcode QUERY
rcode NOERROR
flags QR RD RA
;QUESTION
cocca.fr. IN A
;ANSWER
cocca.fr. 43200 IN A 185.17.236.69
;AUTHORITY
;ADDITIONAL

Total elapsed time: 0.07 seconds (66.72 ms/request )
```

Possible options, besides `--dot`:

* --verbose or -v: Makes the program more talkative
* --debug: Makes the program very talkative (sets verbose to true)
* --head or -e: (DoH) Uses only the HEAD HTTP method. Since the RFC
  does not mention it, result is probably indefinite.
* --POST or -P: (DoH) Uses the POST HTTP method (default is GET)
* --insecure or -k: Does not check the certificate
* -4: Uses only IPv4
* -6: Uses only IPv6
* --dnssec: requests DNSSEC data (signatures)
* --noedns: no EDNS (default is to indicate EDNS support)
* --ecs: send ECS, my subnet to auth. servers (default is to refuse
  it)
* --key KEYINBASE64: authentifies a DoT resolver with its public
  key. Example: `homer.py --key "62lKu9HsDVbyiPenApnc4sfmSYTHOVfFgL3pyB+cBL4=" --dot 145.100.185.15 IN NS`
* --check: Run a set of tests (see below)
* --pipelining: on DoT, send several requests even before getting the
  reply to the first one (may increase performance when you have
  several requests)
* --multistreams: (DoH) Uses HTTP/2 streams (requires the --file option)
* --file INPUT_FILE: provide an input file with a list of domain name to query
  (read the first line only, use --repeat N to read up to N lines of the file)
* --repeat N: repeat a test N times or read up to N lines of a file
* --no-display-results: do not output DNS response

### Check

The `--check` option allows to run several defined tests on a connection.

Homer displays `OK` on success and `KO` on failure.
The program stops after the first failed test.

```
% homer --check https://doh.bortzmeyer.fr framagit.org
OK
```

Each test is marked with a level of compliance. There are three
levels, "legal" (compliant with the strict requirments of the RFCs),
"necessary" (in a typical setup) and "nicetohave". The default level
is "necessary" but you can change it with option
`--mandatory-check`. For instance, sending a reply when the request
uses the HEAD method is "nicetohave" for a DoH server (the RFC does
not mandate it). The tests are always performed but are not fatal if
the choosen level is lower than the level of the test.

### Repetition of tests

You can repeat the tests several times, for instance for performance
measurements. This is done with option `--repeat N` where N is the
number of repetitions.

```
% homer --repeat 3 https://doh.bortzmeyer.fr ça.fr SOA
Test 0
...
Test 1
...
Test 2

Total elapsed time: 0.10 seconds (33.56 ms/request , 7.88 ms/request if we ignore the first one)
```

Homer reuses the same connection for all requests, both for DoH and
DoT, which explains why the first request is often longer.

Repetition is often combined with the use of an external file, where
Homer reads the domain names (and types) to query. Here is a sample
file:

```
truc.fr
chose.fr
machin.fr
trucmachin.fr NS
```

Assuming the file is named `list.txt`, this command will run four
tests, with the above names (and the query type `NS` for the last
one):

```
% homer --repeat 4 --file list.txt https://doh.42l.fr/dns-query
```

When repeating tests, you can add a delay between tests, with `--delay
N` or `-d N`, where N is the (possibly fractional) number of seconds
to wait.

### Mulitstreams

When using Homer with DoH, the option `--multistreams` can be used
to specify that you want to take advantage of the HTTP/2 streams
when sending several requests.

This option requires an input file provided with the `--file` option.
By default only the first line of the file is read. You need to
specify a number of line with `--repeat` to read more lines from
the file.

For example :
```
% ./homer.py --multistreams --file input_file --repeat 5 https://doh.powerdns.org
```

In order to focus on the time per request, you can suppress the
output by using the option `--no-display-results`.

Two modes are available. By default each response is read,
checked and displayed as soon as it is received.
You can use `--sync` to delay this processing after the last transfer.
In that case the DNS responses are displayed in the same order as they
were sent.

An option `--time` allows to display the time taken by each transfer.
This is based on [libcurl time values](https://curl.haxx.se/libcurl/c/curl_easy_getinfo.html#TIMES)
[CURLINFO_TOTAL_TIME](https://curl.haxx.se/libcurl/c/curl_easy_getinfo.html#CURLINFOTOTALTIME)
and [CURLINFO_PRETRANSFER_TIME](https://curl.haxx.se/libcurl/c/curl_easy_getinfo.html#CURLINFOPRETRANSFERTIME)

```
% ./homer.py  --multistreams --file input_file --repeat 5 --no-display-results --time https://doh.powerdns.org
  0   (200)     41.995 ms    51.409 ms     9.414 ms
  1   (200)      0.156 ms     8.648 ms     8.492 ms
  2   (200)      0.121 ms     8.494 ms     8.373 ms
  3   (200)      0.120 ms    11.185 ms    11.065 ms
  4   (200)      0.103 ms    11.922 ms    11.819 ms

Total elapsed time: 0.07 seconds (9.83 ms/request)
```


### Monitoring with Nagios, Icinga, or similar software

If the program is named `check_doh` or ` check_dot` (either from
copying or symbolic linking), it will behave as a [monitoring
plugin](https://www.monitoring-plugins.org/), suitable to be used from monitoring program like Nagios
or [Icinga](https://icinga.com/). The options are different in that case, and follow the
monitoring plugins conventions:

* -H: host name or address to monitor
* -V: virtual hostname (the certificate check will be based on that)
* -n: domain name to lookup
* -t: DNS type to query
* -p: (DoH) path in the URLx
* -e: a string to expect in the result
* -P: uses the HTTP method POST
* -h: uses the HTTP method HEAD
* -i: insecure (do not check the certificate)
* -k:  authenticated the DoT server with this public key

For Icinga, the following definition enables the plugin:

```
object CheckCommand "doh_monitor" {
  command = [ PluginContribDir + "/check_doh" ]

  arguments = {
      "-H" = "$address6$",
	  "-n" = "$doh_lookup$",
	  "-p" = "$doh_path$",
	  "-e" = "$doh_expect$",
	  "-V" = "$doh_vhost$",
	  "-t" = "$doh_type$",
	  "-P" = "$doh_post$",
	  "-i" = "$doh_insecure$",
	  "-h" = "$doh_head$"	
	  }
}

object CheckCommand "dot_monitor" {
  command = [ PluginContribDir + "/check_dot" ]

  arguments = {
      "-H" = "$address6$",
	  "-n" = "$dot_lookup$",
	  "-p" = "$dot_path$",
	  "-e" = "$dot_expect$",
	  "-V" = "$dot_vhost$",
	  "-t" = "$dot_type$",
	  "-P" = "$dot_post$",
	  "-i" = "$dot_insecure$",
	  "-h" = "$dot_head$",
	  "-k" = "$dot_key$"
	}
}

```

And a possible use is:

```
apply Service "doh" {
  import "generic-service"
  check_command = "doh_monitor"
    assign where (host.address || host.address6) && host.vars.doh
      vars.doh_lookup = "fr.wikipedia.org"

}

apply Service "dot" {
  import "generic-service"
  check_command = "dot_monitor"
    assign where (host.address || host.address6) && host.vars.dot
      vars.dot_lookup = "fr.wikipedia.org"

}

```

```
object Host "myserver" {
...
  vars.dot = true
  vars.dot_vhost = "dot.me.example"

  vars.doh = true
  vars.doh_vhost = "doh.me.example"
  vars.doh_post = true

```

## Installation

You need Python 3, [DNSpython](http://www.dnspython.org/),
[PyOpenSSL](https://www.pyopenssl.org/),
[netaddr](https://github.com/drkjam/netaddr/) and
[pycurl](http://pycurl.io/docs/latest). You can install them with pip
`pip3 install dnspython pyOpenSSL netaddr pycurl`. Then, just run the
script `homer` (or `homer.py`).

On Debian, if you prefer regular operating system packages to pip,
`apt install python3 python3-dnspython python3-openssl python3-netaddr
python3-pycurl` will install everything you need.

### Testing

The tests configured in `tests.yaml` require
https://framagit.org/feth/test_exe_matrix. Then, just `test_exe_matrix
tests.yaml`.

## Public servers

(Managed by non-profit organisations. I may trim this list in the
future, to remove servers that do not validate with DNSSEC.)

### DoH

* `https://doh.powerdns.org/`
* `https://doh.bortzmeyer.fr/` ([Documentation](https://doh.bortzmeyer.fr/about)) 
* `https://doh.42l.fr/dns-query` ([Documentation](https://42l.fr/DoH-service))
* `https://odvr.nic.cz/doh` ([Documentation](https://www.nic.cz/odvr/))
* `https://dns.hostux.net/dns-query`
  ([Documentation](https://dns.hostux.net/))
* `https://ldn-fai.net/dns-query` ([Documentation in french](https://ldn-fai.net/serveur-dns-recursif-ouvert/))
* `https://dns.digitale-gesellschaft.ch/dns-query` ([Documentation in german](https://www.digitale-gesellschaft.ch/dns/))
* `https://doh.ffmuc.net`
  ([Documentation](https://ffmuc.net/wiki/doku.php?id=knb:dohdot_en))
* `https://doh.libredns.gr/dns-query`
  ([Documentation](https://libredns.gr/); Also,
  `https://doh.libredns.gr/ads` is a lying resolver, blocking ads and trackers)
* `https://dns.switch.ch/dns-query` ([Documentation](https://www.switch.ch/security/info/public-dns/))
* `https://nat64.tuxis.nl`
  ([Documentation](https://www.tuxis.nl/blog/public-doh-dot-dns64-nat64-service-20191021/);
  NAT64, and no IPv4 address)

### DoT

* `dot.bortzmeyer.fr` ([Documentation](https://doh.bortzmeyer.fr/about)) 
* `dns.digitale-gesellschaft.ch` ([Documentation in german](https://www.digitale-gesellschaft.ch/dns/))
* `dot.ffmuc.net` ([Documentation](https://ffmuc.net/wiki/doku.php?id=knb:dohdot_en)) 
* `ns0.ldn-fai.net` ([Documentation in french](https://ldn-fai.net/serveur-dns-recursif-ouvert/))
* `dot.libredns.gr` ([Documentation](https://libredns.gr/))
* `dns.switch.ch` ([Documentation](https://www.switch.ch/security/info/public-dns/))
* `nat64.tuxis.net`
  ([Documentation](https://www.tuxis.nl/blog/public-doh-dot-dns64-nat64-service-20191021/);
  NAT64, and no IPv4 address)
* `anycast.censurfridns.dk` ([Documentation](https://blog.uncensoreddns.org/))
  
## License 

GPL. See LICENSE.

## Author

Stéphane Bortzmeyer <stephane+framagit@bortzmeyer.org> and Alexandre Pion

## Reference site

https://framagit.org/bortzmeyer/homer/ Use the Gitlab issue tracker to
report bugs or wishes.

## See also

* A [simple DoH client](https://github.com/curl/doh), from the author
  of curl.