README
¶
- dns-api-go
- Installation
- Rate Limiting
- Metrics
- Docker deployment
- Heroku deployment
- Notes
- Hacking
- Production Deployment
- Github Setup
dns-api-go
This is a golang port of the old perl-based DNS-API.org site.
- Still allows the same lookups.
- Still has rate-limiting.
Installation
There are two ways to install this project from source, which depend on the version of the go version you're using.
If you don't have a golang environment configured you should be able to download a binary release from the github project.
Source Installation go <= 1.11
If you're using go before 1.11 then the following command should fetch/update the project and install it upon your system:
$ go get -u github.com/skx/dns-api-go
Source installation go >= 1.12
If you're using a more recent version of go (which is highly recommended), you need to clone to a directory which is not present upon your GOPATH:
git clone https://github.com/skx/dns-api-go
cd dns-api-go
go install
Rate Limiting
The server has support for rate-limiting, you can enable this by passing the address of a redis server to the binary:
$ dns-api-go -redis-server localhost:6379
If this flag is not present then rate-limiting will be disabled. If a client
makes too many requests they will be returned a HTTP 429 status-code. Each request made will return a series of headers
prefixed with X-RateLimit to allow clients to see how many requests they
have made, and have remaining.
Metrics
If you have a graphite-host you can point the environmental-variable METRICS
at it. This will then receive metrics:
- Counts of DNS-queries by type.
- Count of success/failure responses.
- System-metrics.
- via golang-metrics
Docker deployment
If you've cloned this repository you'll notice there is an existing Dockerfile which can be used to build a container. Create your image like so:
skx@frodo ~/go/src/github.com/skx/dns-api-go $ docker build -t dns-api:latest .
Sending build context to Docker daemon 301.1kB
Step 1/10 : FROM alpine
latest: Pulling from library/alpine
..
..
Step 10/10 : ENTRYPOINT ["/root/dns-api-go", "-host","0.0.0.0" , "-port 3001" ]
..
Successfully built
Once you have your container you can launch it like so:
$ docker run -d -p 9999:9999/tcp dns-api:latest
And test it via:
$ curl http://localhost:9999/txt/steve.fi
Deploying with a redis image too, to allow rate-limiting, is left as an exercise.
Heroku deployment
Get into the cloned git repository ($GOPATH/src/github.com/skx/dns-api-go) and run:
$ heroku create
$ git push heroku master
Notes
- The main page dynamically includes the domain-name under which it was reached, so we can deploy it automatically even on other sites.
- PTR (reverse-DNS) requests must be submitted in reverse-format, for example:
Hacking
If you alter the template-files beneath data/ you will need to rebuild the static.go file before those changes will become visible. (i.e. They are pre-processed and included inline in our generated binary, rather than being read at run-time.)
You'll need to install the implant tool.
Now you can regenerate the static.go file using that:
$ implant -input data/ -output static.go
And rebuild the main binary:
$ go build .
Production Deployment
Surprisingly hosting this service publicly results in a ton of:
- Bandwidth usage.
- Support requests.
The former I tried to handle via cloudflare, but caching DNS data means the service doesn't run in a useful way, as you might expect.
To avoid further support-request and abuse complaints I'm taking the main service dns-api.org offline. The code here will always be open, and available for use though.
The current codebase will serve a "We're retired - unless you pay" message if the file /tmp/retired exists. This will be checked every 30 seconds or so.
Github Setup
This repository is configured to run tests upon every commit, and when pull-requests are created/updated. The testing is carried out via .github/run-tests.sh which is used by the github-action-tester action.
Releases are automated in a similar fashion via .github/build, and the github-action-publish-binaries action.
Documentation
Source Files