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.
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://0.0.0.0:53
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://0.0.0.0:53 --upstream-dns 8.8.8.8:53 --cache-ttl 30s
- 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 atlas-linux-latest.zip
- FreeBSD:
unzip -d /usr/local/bin atlas-freebsd-latest.zip
- Windows:
unzip -d C:\Windows\system32 atlas-windows-latest.zip
- Linux:
NAME:
atlas - simple dns service
USAGE:
atlas [global options] command [command options] [arguments...]
VERSION:
0.1.0 (c568ab98) linux/amd64
AUTHOR:
@stellarproject
COMMANDS:
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--debug, -D enable debug logging
--bind value, -b value bind address for the DNS service (default: "udp://0.0.0.0:53")
--datastore value, -d value uri for datastore backend (default: "localdb:///etc/atlas/atlas.db")
--address value, -a value grpc address (default: "tcp://127.0.0.1:9000")
--upstream-dns value upstream dns server (default: "9.9.9.9:53")
--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.
NAME:
actl create - create nameserver record
USAGE:
actl create [command options] [arguments...]
OPTIONS:
--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 foo.int -r A:127.0.0.1
added 1 record
This will create a new A
record for foo.int
that resolves to 127.0.0.1
. You
can use dig
to query Atlas:
$> dig @127.0.0.1 foo.int
; <<>> DiG 9.11.5-P1-1ubuntu2.5-Ubuntu <<>> @localhost foo.int
; (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
;; QUESTION SECTION:
;foo.int. IN A
;; ANSWER SECTION:
foo.int. 10 IN A 127.0.0.1
;; Query time: 5 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Sat Aug 17 01:06:36 EDT 2019
;; MSG SIZE rcvd: 52
You can list all records in the Atlas store:
$> actl list
NAME TYPE VALUE OPTIONS
foo.int A 127.0.0.1
You can delete records from Atlas as well:
$> actl delete foo.int
removed foo.int
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. http://127.0.0.1:9090/metrics
) 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