README.md 3.32 KB
Newer Older
1
# pgeodns - geo-aware authoriative domain nameserver
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

pgeodns is an authoritative DNS server that can give different replies
to each client, taking into account the country of origin of the
client and do weighted responses so some records are returned more
than others.

It's used to give IPs of "nearby" servers among the almost 2000
servers registered in the NTP Pool.  The responses are also weighted
by the available bandwidth for each IP (as configued by the server
admins).

It's also used by apache.org for svn.apache.org to send European users
to their European SVN mirror and North American ones to the US based
server. They are providing their configuration as a minimal example:
https://svn.apache.org/repos/infra/infrastructure/trunk/dns/zones/pgeodns.conf
https://svn.apache.org/repos/infra/infrastructure/trunk/dns/zones/geo.apache.org.json

19
## Installation
20 21 22 23 24 25 26 27 28 29 30

   perl Makefile.PL  # will warn if any dependencies are missing
   make 
   make test         # optional
   make install

You'll need the following modules installed, all available from CPAN:
Net::DNS, Geo::IP, List::Util, JSON.  It's optional, but if you
install JSON::XS loading large zone data files will be ever so
slightly faster.

31
## Configuration
32 33 34 35 36 37 38 39 40 41 42

pgeodns needs two configuration files; one simple text file to define
the zones served and some options, and then for each zone a JSON
formatted data file with the zone data.

JSON is relatively easy to read and write for humans, and extremely
easy for computers to use, practically in any language: http://json.org/

The pgeodns.conf file should look like the following.  Only one or
more "base" lines are required.

43
    # global options
44

45 46
    base some.zone.example.com data/some.file.json
    # options for this zone
47

48 49
    # base another.example.com data/some.file.json
    # options for this zone
50

51
## Data file format
52 53 54 55

See t/example.com.json for a small example for now.


56
## Command line options
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92

* --config=[ configuration file ]

Name of the configuration file to load; defaults to pgeodns.conf in
the current directory.

* --interface=[ ip | host ]

IP or hostname to listen on (for example 192.168.10.10)

* --user=[ username | userid ]

Username or ID to change to after binding to the port.

* --verbose

Provide lots of details for each incoming and outgoing packet.

* --configtest

Load the config and exit.  Exits with 0 as the return value if all is
well.

* --port=[ 53 ]

Specify which port to listen on. Defaults to 53. Only use this in
development or if you are behind a NAT/SNAT device that forwards
queries to a different port.

* --development

This will enable a query to shutdown.$domain to make pgeodns
exit. Obviously not a good idea in production, but can be handy in a
development/testing environment.


93
## Configuration Options
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

The options allowed in the 'base' configuration file are

* ns name.server.tld

Add `name.server.tld` as a nameserver for this zone (or globally).  If
you specify one or more NS'es for a zone, it'll override the global
configuration.  You can also specify the ns records in the JSON data,
but doing it in the configuration gives some flexibility for re-using
the data under different namespaces.

* serial 123

Set the serial number of the zone; generally this is better done in
the JSON data.

* ttl 300

Set the default time-to-live for the zone in seconds.

* include filename

Include another filename.