Public | Automated Build

Last pushed: a day ago
Short Description
A simple node-base DNS server with a REST API.
Full Description


A DNS Server with an Web UI and using Redis a configuration store. Read further
for Docker instructions.


brew install redis
sudo npm install -g dns


/usr/local/opt/redis/bin/redis-server /usr/local/etc/redis.conf >& /tmp/redis.log &
sudo dns >& /tmp/dns.log &

Web UI

open http://localhost:8053


REDIS_PORT_6379_TCP_ADDR  (default:
REDIS_PORT_6379_TCP_PORT  (default: 6379)


DNSPORT      (default: 53 <- require root privilege to run)
DNSZONE      (default:
DNSTTL       (default: 3600 <- one hour)
DNSPREFIX    (default: "dns:" <- key prefix in redis)
DNSPRIMARY   (default:
DNSTIMEOUT   (default: 1000 <- 1 second)


* GET /dns/api/v1/name

    List all host to ip address mapping

* GET /dns/api/v1/name/{host}

    Return the ip address of only that host

* PUT /dns/api/v1/name/{host}

    Create or Modify the ip address for "host"

* DELETE /dns/api/v1/name/{host}

    Remove the host from the DNS

* DELETE /dns/api/v1/name?force=true

    Remove all host from the DNS

* GET /dns/api/v1/zone

    Return the DNS ZONE

* GET /dns/api/v1/status

    Return the DNS status

To create or modify a host in the DNS configuration

Single host
curl -X PUT -H 'Content-Type: application/json' -d '{"ipv4":[""], "ipv6":["2605:f8b0:4006:802:0:0:0:1010"]}' http://localhost:8053/dns/api/v1/name/

Multiple hosts
    curl -X PUT -H 'Content-Type: application/json' -d '{"ipv4":["",""], "ipv6":["2605:f8b0:4006:802:0:0:0:1010","2605:f8b0:4006:802:0:0:0:1011"]}' http://localhost:8053/dns/api/v1/name/

To query the address of a host

curl http://localhost:8053/dns/api/v1/name/
dig @
dig @ AAAA

To remove a host from the registry

curl -X DELETE http://localhost:8053/dns/api/v1/name/

UPGRADING from 0.0.9 or 0.1.0 to a version greater than 0.1.0

You will need to clear your redis configuration before running the new version.

curl -X DELETE http://localhost:8053/dns/api/v1/name\?force\=true
for key in `echo 'KEYS dns*' | redis-cli | awk '{print $1}'` ; do echo DEL $key ; done | redis-cli

Running in Docker

This DNS server is able to run as a docker container. To build the container,
run a command similar to the following (htdns is a shorthand for HTTP/DNS):

docker build -t efrecon/htdns .

To run, once you have your image, issue something similar to the following command:

docker run -it --rm -p 8053:8053 -p 53:53 --name=dns -e DNSTTL=1800 efrecon/htdns --level=debug

Note how the command above maps port 53, which requires root privileges and
also how it passes further the DNSTTL environment variable (one of the
optional variables documented above) and passes command-line arguments to the
DNS server (in this case, putting it in debug mode). The implementation
currently runs redis as a daemon before starting up the node-based DNS server.
This is for the sake of simplicity, but breaks the principle that there should
only be one container running in a container.

Docker Pull Command
Source Repository