225 lines
8.2 KiB
Plaintext
225 lines
8.2 KiB
Plaintext
General
|
|
*******
|
|
|
|
This software is a "DNS looking glass". The DNS (Domain Name System)
|
|
is the distributed database used to retrieve data (typically IP
|
|
addresses) from domain
|
|
names. <https://en.wikipedia.org/wiki/Domain_Name_System>
|
|
|
|
A "looking glass", among Internet engineers, typically refers to a
|
|
server on one network which serves information seen from this network
|
|
(two points of the Internet may see different things, that's why
|
|
looking glasses are important). Their main use, today, is to see BGP
|
|
<https://en.wikipedia.org/wiki/Border_Gateway_Protocol> routes from
|
|
another point of view
|
|
<https://en.wikipedia.org/wiki/Looking_Glass_servers>. But it is time
|
|
to extend them to the DNS.
|
|
|
|
The "DNS looking glass" allows you to get DNS data from another
|
|
server. This is useful to check site-dependent behavior. Among the
|
|
many reasons why the DNS data can be different in various places:
|
|
* cache poisoning, for instance by a Kaminsky attack
|
|
<https://en.wikipedia.org/wiki/DNS_cache_poisoning>,
|
|
* DNSSEC validation enabled at some places but not others,
|
|
* network problems making name servers unreachable from some places,
|
|
* caching effects (data in the cache at some places but not others),
|
|
* censorship making some names such as thepiratebay.org or
|
|
wikileaks.org unavailable in some sites.
|
|
|
|
License
|
|
*******
|
|
|
|
A simple, permissive, free software license, known as 2-clause BSD
|
|
license (or simplified BSD license; it is equivalent to the ISC
|
|
license). See LICENSE for the full text.
|
|
|
|
Usage
|
|
*****
|
|
|
|
We assume that someone installed the software. If you install it
|
|
yourself, see the next section.
|
|
|
|
The major usage of this program is through REST requests
|
|
<https://en.wikipedia.org/wiki/Representational_state_transfer> (if you
|
|
do not know REST, do not worry; basically, it means we use ordinary
|
|
HTTP requests). If the program is installed at
|
|
<https://dns.example.net/>, the URL for the requests will be
|
|
<https://dns.example.net/$DOMAIN[/$TYPE][/$CLASS]> where DOMAIN is the
|
|
domain name and TYPE a DNS record type (such as AAAA or MX).
|
|
|
|
More formally, following the language of URI Templates (RFC 6570), the
|
|
URLs of this service are
|
|
<https://dns.example.net/{+domain}/{querytype}/{queryclass}{?format,server,buffersize,dodnssec,tcp,reverse}>
|
|
|
|
There is a non-standard pseudo-querytype ADDR to request both A and
|
|
AAAA, specially for the links in the HTML output.
|
|
|
|
The default output format is determined by HTTP content negotiation,
|
|
so it depends on your client. You can use this program from an
|
|
ordinary Web browser, which will typically get HTML by default. With a
|
|
command-line client like curl, you can add the relevant header to get
|
|
the format you want;
|
|
|
|
curl -v -H 'Accept: application/json' $URLBASE/org/SOA
|
|
|
|
If content negotiation does not suit you, you can add in the URL the
|
|
option format=FORMAT where FORMAT is XML, HTML, TEXT, ZONE or JSON
|
|
(see next section). So, for instance, to get the IPv6 address of
|
|
www.example.com in XML, it will be
|
|
<https://dns.example.net/www.example.com/AAAA?format=XML>
|
|
|
|
You can add an option to select the name server to query (the default
|
|
one is chosen by the server, typically the default resolver(s) of the
|
|
machine). server=IP-ADDRESS (names are *not* supported)
|
|
|
|
To activate DNSSEC in the responses (to send the DO bit), use option
|
|
dodnssec=1 in the URL. This option will allow you (if the resolver
|
|
supports it) to see the AD (Authentic Data) flag.
|
|
|
|
To disable DNSSEC validation (if the resolver does it and you don't
|
|
want it), use option cd=1 (cd = Checking Disabled)
|
|
|
|
To use TCP (instead of UDP) for the request, use option tcp=1 in the
|
|
URL.
|
|
|
|
By default, the server queries the name servers with EDNS0 and a
|
|
buffer size of 4096 bytes. To change that, use the option buffersize
|
|
with the value you want. Setting it to 0 will disable EDNS.
|
|
|
|
For finding a domain name from an IP address, you can do requests with
|
|
the arpa domain name, for instance
|
|
<https://dns.example.net/1.2.0.192.in-addr.arpa/PTR> but you can also
|
|
use the option reverse to ask for the address to be turned into an
|
|
arpa domain name, for instance
|
|
<https://dns.example.net/192.0.2.1?reverse=1>.
|
|
|
|
There is a rate-limiter so, if you receive HTTP status code 429, it
|
|
means you have been too aggressive.
|
|
|
|
Format-specific things
|
|
**********************
|
|
|
|
The XML option follows partially the format of Internet-Draft
|
|
draft-mohan-dns-query-xml for the outer elements (plus some
|
|
extensions) and of draft-daley-dns-schema for the resource data. Note
|
|
that the query format does *not* follow the first draft's syntax.
|
|
|
|
The JSON option's format is documented in the file JSON.txt.
|
|
|
|
The HTML option's format is not documented. To style the output, a
|
|
sample CSS file is included in dnslg.css.
|
|
|
|
The Text option's format is not documented. It is intended for human
|
|
reading. If you need a structured format, use XML or JSON. If you
|
|
prefer text-based formats, for instance for processing with common
|
|
Unix CLI tools (awk, grep, etc), the best one is probably the Zone
|
|
format.
|
|
|
|
The Zone option's format follows section 5 of RFC 1035, with tabs as
|
|
separators.
|
|
|
|
Using it from a program
|
|
***********************
|
|
|
|
Of course, an important reason to have a structured output format is
|
|
to use it from a program. See the directory usages/ for sample
|
|
programs which query the DNS looking glass.
|
|
|
|
Requirements
|
|
************
|
|
|
|
Requires Python, then SimpleTAL, dnspython, webob and netaddr. If you
|
|
want to use the database of existing looking glasses, you will also
|
|
need the yaml module.
|
|
Debian/Ubuntu: packages "python-netaddr python-dnspython python-webob python-simpletal python-yaml"
|
|
|
|
Installation
|
|
************
|
|
|
|
python setup.py build
|
|
$SUDO-OR-SIMILAR python setup.py install
|
|
|
|
Then you have to configure a HTTP server to run this WSGI
|
|
script. Some configuration data can be sent by environment
|
|
variables. For instance, if you use Google Webmasters and have the
|
|
code (the cookie) "google1234baddcaf5678", *and* you want the program
|
|
to serve the file itself (it is not mandatory), then you need to
|
|
define the environment variable DNSLG_GOOGLE_WEBMASTERS_CODE to this
|
|
code.
|
|
|
|
For Apache, this is typically something like:
|
|
|
|
<VirtualHost *:80>
|
|
ServerName dns.example.net
|
|
DocumentRoot "/var/www/dns.example.net/root"
|
|
|
|
<Directory "/var/www/dns.example.net/scripts">
|
|
Options -Indexes FollowSymLinks +ExecCGI
|
|
SetHandler wsgi-script
|
|
Order allow,deny
|
|
Allow from all
|
|
</Directory>
|
|
WSGIScriptAlias / /var/www/dns.example.net/scripts/dnslg.py
|
|
WSGIDaemonProcess dns.example.net processes=5 threads=10 display-name=%{GROUP}
|
|
WSGIProcessGroup dns.example.net
|
|
</VirtualHost>
|
|
|
|
where dnslg.py is copied and adapted from sample-wsgi-dnslg.py or
|
|
sample-wsgi-dnslg-with-config-file.py.
|
|
|
|
The starters with a configuration file use the INI format. Use
|
|
sample-config-file.ini as an example.
|
|
|
|
There are many other possibilities, either with Apache or with another
|
|
HTTP server with WSGI support. Browse the Web!
|
|
|
|
The official source is at Framagit
|
|
<https://framagit.org/bortzmeyer/dns-lg>. The best place to report bugs,
|
|
submit patches and give opinions is through the Framagit issue tracker.
|
|
|
|
Tests
|
|
*****
|
|
|
|
To try it locally;
|
|
% python test-server.py
|
|
Then, from another window:
|
|
% curl http://localhost:8080/example.org/A
|
|
|
|
To test against running servers, see the script tests.sh. For
|
|
developer tests, see test_service.py, intended to be run from pytest
|
|
<https://pytest.org/>. By default, 'pytest' will run against
|
|
<http://localhost:8080/>, you can use another server with 'pytest
|
|
--url https://example.net/' (don't forget the trailing slash).
|
|
|
|
Other DNS looking glasses
|
|
*************************
|
|
|
|
http://live.icmynet.com/icmynet-dns/ No API, Web only
|
|
|
|
http://www.zonecut.net/dns/index.cgi No API, Web only
|
|
|
|
http://www.whatsmydns.net/ REST URLs but no API
|
|
|
|
See also a more up-to-date list at the end of
|
|
<https://www.bortzmeyer.org/dns-lg.html>
|
|
|
|
Other code for DNS looking glasses
|
|
**********************************
|
|
|
|
* <http://dns-lg.sidnlabs.nl/index.html> written in Go
|
|
|
|
Author
|
|
******
|
|
|
|
Written by Stephane Bortzmeyer <bortzmeyer+dnslg@nic.fr>. (To report
|
|
bugs and submit patches, I suggest that you use the Framagit issue
|
|
tracker instead of email.)
|
|
|
|
Favicon <http://www.favicon.cc/?action=icon&file_id=513990>,
|
|
by Philippe Regnauld <http://www.favicon.cc/?action=icon_list&user_id=155740>
|
|
|
|
Implementation details
|
|
**********************
|
|
|
|
See IMPLEMENTATION
|