atlas

Atlas

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.

Installation

Docker

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).

Examples

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

Manual

• 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

Usage

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

Example

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

Add a Record

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

List Records

You can list all records in the Atlas store:

$> actl list
NAME                TYPE                VALUE               OPTIONS
foo.int             A                   127.0.0.1

Delete Records

You can delete records from Atlas as well:

$> actl remove foo.int
removed foo.int

Metrics

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