Skip to content
Simple DNS Service
Go Makefile Other
Branch: master
Clone or download
ehazlett Merge pull request #6 from theycallmemac/master
changed remove to delete in
Latest commit 45410b4 Sep 9, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows update action Aug 20, 2019
api add export Aug 27, 2019
client add export Aug 27, 2019
cmd support env var for configuration Sep 7, 2019
contrib support env var for configuration Sep 7, 2019
ds add export Aug 27, 2019
script update package script Aug 20, 2019
server fix srv lookup bug Aug 28, 2019
vendor metrics: add emitter for ops Aug 21, 2019
version ehazlett -> stellarproject Aug 23, 2019
.gitignore updated build action Aug 19, 2019
Dockerfile update dockerfile Aug 23, 2019
LICENSE ehazlett -> stellarproject Aug 23, 2019
Makefile update makefile for release Sep 7, 2019
Protobuild.toml dns server with forwarding and wildcard lookups Aug 16, 2019 changed remove to delete in Sep 8, 2019
atlas.go ehazlett -> stellarproject Aug 23, 2019
ds.go ehazlett -> stellarproject Aug 23, 2019
go.mod ehazlett -> stellarproject Aug 23, 2019
go.sum metrics: add emitter for ops Aug 21, 2019
proto.go ehazlett -> stellarproject Aug 23, 2019


The Atlas Nameserver service provides a simple programmable DNS service. Atlas uses the same core library that CoreDNS uses (miekg/dns). It contains a GRPC API and a client that can be used for programmatic control. For an example on using the GRPC API see the CLI. Atlas also has builtin metrics that can be enabled for monitoring queries, lookups, etc.

Go Report Card Docs Build Status



Docker Image

A Docker image is built upon every merge to master. The latest is stellarproject/atlas:latest

To run with Docker, you will need to map ports (-p) for all ports you want to expose (at least 53/udp and 9000/tcp).


Run Atlas in Docker publishing on default ports:

$> docker run -ti -d \
	--name atlas \
	-p 53:53/udp \
	-p 9000:9000 \
	stellarproject/atlas:latest -b udp://

Run Atlas using Google DNS for upstream with a 30s cache:

$> docker run -ti -d \
	--name atlas \
	-p 53:53/udp \
	-p 9000:9000 \
	stellarproject/atlas:latest -b udp:// --upstream-dns --cache-ttl 30s


Linux Latest Build FreeBSD Latest Build Windows Latest Build

  • Download a release either from the "latest" builds above or from the Releases.
  • Extract the release to your PATH:
    • Linux: unzip -d /usr/local/bin
    • FreeBSD: unzip -d /usr/local/bin
    • Windows: unzip -d C:\Windows\system32


   atlas - simple dns service

   atlas [global options] command [command options] [arguments...]

   0.1.0 (c568ab98) linux/amd64


   help, h  Shows a list of commands or help for one command

   --debug, -D                  enable debug logging
   --bind value, -b value       bind address for the DNS service (default: "udp://")
   --datastore value, -d value  uri for datastore backend (default: "localdb:///etc/atlas/atlas.db")
   --address value, -a value    grpc address (default: "tcp://")
   --upstream-dns value         upstream dns server (default: "")
   --cache-ttl value            builtin cache ttl (default: disabled) (default: 0s)
   --help, -h                   show help
   --version, -v                print the version


Atlas has a GRPC api that enables remote management of the internal DNS store.

Add a Record

   actl create - create nameserver record

   actl create [command options] [arguments...]

   --name value, -n value    record name
   --record value, -r value  record to add (format: <TYPE>:<VALUE>)

To add a new A record:

$> actl create -n -r A:
added 1 record

This will create a new A record for that resolves to You can use dig to query Atlas:

$> dig @

; <<>> DiG 9.11.5-P1-1ubuntu2.5-Ubuntu <<>> @localhost
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 2425
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;                     IN      A

;; ANSWER SECTION:              10      IN      A

;; Query time: 5 msec
;; WHEN: Sat Aug 17 01:06:36 EDT 2019
;; MSG SIZE  rcvd: 52

List Records

You can list all records in the Atlas store:

$> actl list
NAME                TYPE                VALUE               OPTIONS             A         

Delete Records

You can delete records from Atlas as well:

$> actl delete


Atlas has the ability to expose Prometheus compatible metrics. By default, the endpoint is disabled. To enable, add the --metrics-addr flag:

You can then scrape the <metrics-addr>/metrics (i.e. endpoint. You will see something like this:

# HELP atlas_dns_create_total Total number of record creates
# TYPE atlas_dns_create_total counter
atlas_dns_create_total 2
# HELP atlas_dns_delete_total Total number of record deletes
# TYPE atlas_dns_delete_total counter
atlas_dns_delete_total 1
# HELP atlas_dns_lookup_a_total Total number of A record lookups
# TYPE atlas_dns_lookup_a_total counter
atlas_dns_lookup_a_total 201
# HELP atlas_dns_lookup_cname_total Total number of CNAME record lookups
# TYPE atlas_dns_lookup_cname_total counter
atlas_dns_lookup_cname_total 201
# HELP atlas_dns_lookup_forward_total Total number of upstream lookups
# TYPE atlas_dns_lookup_forward_total counter
atlas_dns_lookup_forward_total 452
# HELP atlas_dns_query_milliseconds Duration of query in milliseconds
# TYPE atlas_dns_query_milliseconds histogram
atlas_dns_query_milliseconds_bucket{le="1"} 402
atlas_dns_query_milliseconds_bucket{le="5"} 402
atlas_dns_query_milliseconds_bucket{le="10"} 402
atlas_dns_query_milliseconds_bucket{le="25"} 837
atlas_dns_query_milliseconds_bucket{le="50"} 851
atlas_dns_query_milliseconds_bucket{le="100"} 854
atlas_dns_query_milliseconds_bucket{le="250"} 854
atlas_dns_query_milliseconds_bucket{le="500"} 854
atlas_dns_query_milliseconds_bucket{le="1000"} 854
atlas_dns_query_milliseconds_bucket{le="+Inf"} 854
atlas_dns_query_milliseconds_sum 6565.383260999997
atlas_dns_query_milliseconds_count 854
You can’t perform that action at this time.