A successor to VegaDNS, this is a REST API for managing DNS records in MySQL for use with tinydns.
Python Shell Makefile
Latest commit a7b71cd Feb 14, 2017 Bill Shupp Removed print statement added in 80c8011
Failed to load latest commit information.
docker Remove iptools and use just netaddr Feb 12, 2017
lib backout style change in 3rd party lib Apr 20, 2015
sql First pass at location support. Jun 16, 2016
swagger Added /domains/<domain_id>/create_default_soa endpoint Feb 2, 2017
tests Added missing validation for CNAME values Nov 28, 2016
vegadns Removed print statement added in 80c8011 Feb 14, 2017
Makefile Fixed bug in start.sh script, broke up make targets for image building Jul 14, 2015
requirements.txt Remove iptools and use just netaddr Feb 12, 2017
run.py Added /domains/<domain_id>/create_default_soa endpoint Feb 2, 2017



VegaDNS API, the successor to VegaDNS, is a REST API for managing DNS records in MySQL for use with tinydns. Written in python, it relies on flask, flask_restful, and peewee. It generally is run using uwsgi and supervisor behind nginx. (See the docker/templates directory for example configuration files). It currently supports basic auth, cookies, and OAuth2 (section 4.4) for authentication.

Supported Clients

There are two supported API clients at this time:

  • VegaDNS-UI - a JavaScript only UI, similar to the old VegaDNS.
  • VegaDNS-CLI - a command line interface that includes a reusable client library written in python.


Manual setup from a git checkout

If you want to get this up and running from a git checkout quickly, you'll want to use python 2.7.9 or later (3 is not yet tested), and have pip and virtualenv installed. This assumes you have a mysql server with a database called vegadns created, and write privileges granted. From there, you can do the following to set up your virtual environment:

virtualenv venv
. venv/bin/activate
pip install -r requirements.txt

You'll also need to set up your vegadns/api/config/local.ini file with the following, replacing values with credentials for your mysql database:

user = vegadns
password = secret
database = vegadns
host = localhost

Have a look at default.ini for a full list of configuration items you may want to override.

Lastly, you need to create your database contents. You can apply the following an empty database:

mysql -u vegadns -p -h localhost vegadns < sql/create_tables.sql
mysql -u vegadns -p -h localhost vegadns < sql/data.sql

If you are testing a copy of a legacy VegaDNS database, you can just run this instead:

mysql -u vegadns -p -h localhost vegadns < sql/new_tables_only.sql
mysql -u vegadns -p -h localhost vegadns < alter-01.sql
mysql -u vegadns -p -h localhost vegadns < alter-02.sql
mysql -u vegadns -p -h localhost vegadns < alter-03.sql
mysql -u vegadns -p -h localhost vegadns < sql/data_api_keys_only.sql

Now that the environment is setup, you can start the built-in flask web server to test below:

$ DEBUG=true python run.py
 * Running on (Press CTRL+C to quit)
  * Restarting with stat

Setup using docker

If you have docker setup, you can build a docker container with the cli and ui built in. There are scripts in the docker directory to help with this, build_docker_image.sh and run_docker.sh. Note that to build the image, you must have a checkout of this repository, as it gets added during build time. Remote Dockerfile use is not supported. Further, by default it expects the vegadns-ui and vegadns-cli directories to be checked out. See build_docker_image.sh for further info.

Note: If your docker machine is on a different IP, you'll want to us slightly different syntax. For example, if your docker IP is, you'll want to run the following (alternate port of 8000 is optional depending on your available ports):

docker run \
    -p 8000:80 \
    -p 53:53/udp \
    -e API_URL= \

Then you can point your browser to to get VegaDNS-UI.


Once installation is complete, you'll probably want to use one of the supported clients above for accessing the api. If this is a clean install, the test account is test@test.com with a password of "test". If you're using existing accounts, they should work as well.


First you'll need to activate your virtual environment:

. venv/bin/activate

Then, to run unit tests and check pep8 compliance, run the following:


You can also check code coverage:

make coverage


make coverage-html
open coverage/index.html

You can also run integration tests in a container:

make test-integration
# this builds the image first

Changes from legacy VegaDNS

  • New permissions structure. Instead of 3 tiers (senior_admin, group_admin, user), there is only senior_admin and user tiers (type). Users can own domains and privileges can now be granted to groups. This should be a much more flexible architecture. Currently there is no migration tool for people using the legacy group_admin tier. If there is much of a need, I can put one together.
  • Added tinydns location support. If you want to do split horizon dns, you can specify locations and network prefixes for those locations, and then bind records to those locations to serve up different results based on the network the request came from. If you want to use IPv6 network prefixes, note that djbdns needs to be patched for IPv6. (If on debian/ubuntu, you can alternately use the already patched dbndns package instead of the djbdns package)
  • REST API only, a JavaScript only UI is available separately here
  • API is written in python rather than PHP


For comments or support, please use the issue tracker on Github. You may use the Google Group as well for discussions.