Commit 58650b62 authored by Alexandre's avatar Alexandre

Update README file accordingly

parent 23cc6ea3
# Homer
# Remoh
Homer is a DoH (DNS-over-HTTPS) and DoT (DNS-over-TLS) client. Its
main purpose is to test DoH and DoT resolvers.
Remoh (formerly Homer) is a DoH (DNS-over-HTTPS) and DoT (DNS-over-TLS) client.
Its main purpose is to test DoH and DoT resolvers.
With the proliferation of public DoH and DoT resolvers, and the implementation
of clients inside OS or applications such as web browsers, we wanted to have an
easy to use command line client to make DoT and DoH queries. Homer also aims to
easy to use command line client to make DoT and DoH queries. Remoh also aims to
assess if a DoT or DoH resolver is compliant with the RFCs (
[RFC 7858](https://www.rfc-editor.org/rfc/rfc7858) for DoT and
[RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) for DoH).
Homer is a Python3 script using the [dnspython](http://www.dnspython.org/)
Remoh is a Python3 script using the [dnspython](http://www.dnspython.org/)
library to generate and parse DNS messages, [netaddr](https://github.com/netaddr/netaddr)
to manipulate IP addresses, [PycURL](http://pycurl.io/) to perform the HTTPs
transfers in DoH and [pyOpenSSL](https://www.pyopenssl.org/en/stable/) to
......@@ -35,13 +35,13 @@ establish TLS session in DoT.
## 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
the DoT resolver), and a domain name to query. By default, Remoh 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
% remoh https://doh.powerdns.org/ framagit.org
id 0
opcode QUERY
rcode NOERROR
......@@ -54,7 +54,7 @@ framagit.org. 10800 IN AAAA 2a01:4f8:200:1302::42
;ADDITIONAL
Total elapsed time: 0.40 seconds (402.28 ms/request)
% homer --dot 9.9.9.9 cocca.fr A
% remoh --dot 9.9.9.9 cocca.fr A
id 42545
opcode QUERY
rcode NOERROR
......@@ -69,9 +69,9 @@ cocca.fr. 43200 IN A 185.17.236.69
Total elapsed time: 0.07 seconds (66.72 ms/request )
```
When using DoT, Homer first resolves the domain name of the resolver into a
When using DoT, Remoh first resolves the domain name of the resolver into a
list of IPv4 and IPv6 addresses (or only one subset when using `-4` or `-6`)
and will loop on each of them until a response is received. Hence if Homer gets
and will loop on each of them until a response is received. Hence if Remoh gets
an answer, this mean that at least one DoT resolver is up and running. To check
all the IPs, use `--check`.
......@@ -128,7 +128,7 @@ 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
% remoh --repeat 3 https://doh.bortzmeyer.fr ça.fr SOA
Test 0
...
Test 1
......@@ -138,11 +138,11 @@ 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
Remoh 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 `-f FILE`, where
Homer reads the domain names (and types) to query. Here is a sample
Remoh reads the domain names (and types) to query. Here is a sample
file:
```
......@@ -157,7 +157,7 @@ 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
% remoh --repeat 4 --file list.txt https://doh.42l.fr/dns-query
```
When repeating tests, you can add a delay between tests, with `--delay
......@@ -171,20 +171,20 @@ connection. This can be used to test the compliance of the servers with the
RFCs. DoT is standardized in [RFC 7858](https://www.rfc-editor.org/rfc/rfc7858)
and DoH in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484).
If all the tests passed, Homer displays `OK`. Otherwise if at least
on test failed, Homer outputs `KO`. When a test fails, an error message
If all the tests passed, Remoh displays `OK`. Otherwise if at least
on test failed, Remoh outputs `KO`. When a test fails, an error message
is displayed.
```
% homer --check https://doh.bortzmeyer.fr framagit.org
% remoh --check https://doh.bortzmeyer.fr framagit.org
OK
% homer --dot --check dnsotls.lab.nic.cl wikipedia.org
% remoh --dot --check dnsotls.lab.nic.cl wikipedia.org
Could not connect to "dnsotls.lab.nic.cl" on 200.1.123.46
KO
```
When used with an URL for DoH or a domain name for DoT, Homer loops
When used with an URL for DoH or a domain name for DoT, Remoh loops
on all the resolved IPs. All the tests are then run for each connection.
Each test is marked with a level of compliance. There are three
......@@ -216,7 +216,7 @@ the choosen level is lower than the level of the test.
### Multistreams
When using Homer with DoH, the option `--multistreams` can be used
When using Remoh 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.
......@@ -227,12 +227,12 @@ the file.
For example :
```
% homer --multistreams --file input_file --repeat 5 https://doh.powerdns.org
% remoh --multistreams --file input_file --repeat 5 https://doh.powerdns.org
...
Total elapsed time: 0.11 seconds (22.60 ms/request)
```
When dealing with multistreams, Homer relies on the multi interface
When dealing with multistreams, Remoh relies on the multi interface
from PycURL (and libcurl). By default all the queries are attached to
the multi object before performing the transfers. For a better use of
the multi interface, see the branch [homer-perf](-/tree/homer-perf).
......@@ -263,27 +263,27 @@ the root NS.
It is possible to pipeline multiple DoT queries with the option `--pipelining`.
The queries are created based on the provided input file. Up to `N` lines are
read from the file, with `N` defined by the option `--repeat N`. By default
Homer sends up to 20 requests in parallel before listening for responses.
Remoh sends up to 20 requests in parallel before listening for responses.
This value can be changed with `--max-in-flight`.
After sending the first query, Homer is configured to stop after 10 seconds
After sending the first query, Remoh is configured to stop after 10 seconds
has elapsed. This mean that if more queries need to be sent or received 10
seconds after the beginning of the first transfer, they will all be dropped.
To increase this value, update the variable `MAX_DURATION`.
Homer will display all the DNS response as they arrive. To suppress
Remoh will display all the DNS response as they arrive. To suppress
this output, use `--no-display-results`.
If not all the queries got a response in `MAX_DURATION` seconds, Homer
If not all the queries got a response in `MAX_DURATION` seconds, Remoh
outputs `KO` instead of `OK`.
```
% homer --dot --pipelining -f input_file -r 5 dns.switch.ch
% remoh --dot --pipelining -f input_file -r 5 dns.switch.ch
...
Total elapsed time: 0.56 seconds (111.67 ms/request)
OK
% homer --dot --pipelining -f huge_file -r 1000 127.0.0.1
% remoh --dot --pipelining -f huge_file -r 1000 127.0.0.1
...
Elapsed time too long, 42 requests never got a reply
Total elapsed time: 10.29 seconds (10.29 ms/request)
......@@ -292,7 +292,7 @@ KO
### A note on the SNI
By default, Homer sends a SNI when establishing the TLS session with DoT. The
By default, Remoh sends a SNI when establishing the TLS session with DoT. The
SNI value is extracted from the name or address of the DoT resolver. If a
literal IP address is used, the SNI will then be set with the IP address.
......@@ -396,7 +396,7 @@ You need Python 3, [DNSpython](http://www.dnspython.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`).
script `remoh` (or `remoh.py`).
On Debian, if you prefer regular operating system packages to pip,
`apt install python3 python3-dnspython python3-openssl python3-netaddr
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment