Description

Small DNS service to support local development. The server listens by default on port 5053. iptables is used to forward requests to localhost:53 to localhost:5053 instead.

The DNS service provides recursive queries, so you can continue to use DNS as usual.

You can then set new authoritative domains and A records that are available locally.

For example:

$ minidns start
$ host www.example.com
www.example.com has address 93.184.216.119
www.example.com has IPv6 address 2606:2800:220:6d:26bf:1447:1097:aa7
$ minidns add example.com
$ minidns record example.com a www 192.168.0.10
$ minidns show example.com
www 192.168.0.10
$ host www.example.com
www.example.com has address 192.168.0.10
$ minidns stop
$ host www.example.com
www.example.com has address 93.184.216.119
www.example.com has IPv6 address 2606:2800:220:6d:26bf:1447:1097:aa7

Usage:

Usage: minidns [options] command

daemon control commands:
    start  start the minidns server and forward localhost:53 to it
    stop   stop the minidns server and remove iptables rules

zone commands:
    add name  add a new local authoritative zone "name"
    del name  delete the local authoritative zones "name"
    list      list all authoritative zones
    show name list records for the zone "name"

record commands:
    record zone a host [data]   create A record
    record zone del host        delete record

    e.g. record example.com a www 192.168.0.1

Options:
  -h, --help            show this help message and exit
  -c CONFIG, --config=CONFIG
                        path to configuration file
  -n, --no-divert       Do not use iptables to divert port DNS locally

iptables

As part of starting and stopping (unless the -n switch is provided), minidns makes some changes to your iptables nat configuration. This only works as-is if you are using localhost as your nameserver (which is quite a common configuration).

iptables commands are issued to reroute localhost:53 to the minidns ports, so that it can transparently commandeer your local DNS.

This mechanism was chosen as the least intrusive way of doing this, in particular it makes no changes to the files in /etc.

API

MiniDNS is designed primarily to be used by automated deployment systems, and provides a simple REST API for these systems.

In general you should expect the following response codes on a successful request:

• GET requests return 200 on success

• PUT requests return 201 on success

• DELETE requests return 204 on success

The resources available on the web port are:

GET /

200 OK
example.com
foo.com

GET /example.com

200 OK
A www 192.168.0.1

PUT /example.com

201 Created

DELETE /example.com

204 No Content

GET /example.com/www

200 OK
A 192.168.0.1

PUT /example.com/www
A 192.168.0.1

201 Created

DELETE /example.com/www

204 No Content

Configuration file

A configuration file is not required - sensible defaults are provided. Note that Google’s DNS servers are used as forwarders by default.

If you wish, you can provide a file with the following format:

[minidns]
forwarders = 8.8.8.8 8.8.4.4
udp_port = 5053
tcp_port = 5053
www_port = 5080
pidfile = minidns.pid
logfile = minidns.log

LICENSE

Copyright 2013 Isotoma Limited

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.