/shaman

Small, lightweight, api-driven dns server.

Primary LanguageGoMIT LicenseMIT

shaman logo
Build Status GoDoc Go Report Card

Shaman

Small, clusterable, lightweight, api-driven dns server.

Quickstart:

# Start shaman with defaults (requires admin privileges (port 53))
shaman -s

# register a new domain
shaman add -d nanopack.io -A 127.0.0.1

# perform dns lookup
# OR `nslookup -port=53 nanopack.io 127.0.0.1`
dig @localhost nanopack.io +short
# 127.0.0.1

# Congratulations!

Usage:

As a CLI

Simply run shaman <COMMAND>

shaman or shaman -h will show usage and a list of commands:

shaman - api driven dns server

Usage:
  shaman [flags]
  shaman [command]

Available Commands:
  add         Add a domain to shaman
  delete      Remove a domain from shaman
  list        List all domains in shaman
  get         Get records for a domain
  update      Update records for a domain
  reset       Reset all domains in shaman

Flags:
  -C, --api-crt string            Path to SSL crt for API access
  -a, --api-domain string         Domain of generated cert (if none passed) (default "shaman.nanobox.io")
  -k, --api-key string            Path to SSL key for API access
  -p, --api-key-password string   Password for SSL key
  -H, --api-listen string         Listen address for the API (ip:port) (default "127.0.0.1:1632")
  -c, --config-file string        Configuration file to load
  -O, --dns-listen string         Listen address for DNS requests (ip:port) (default "127.0.0.1:53")
  -d, --domain string             Parent domain for requests (default ".")
  -f, --fallback-dns              Fallback dns server address (ip:port), if not specified fallback is not used
  -i, --insecure                  Disable tls key checking (client) and listen on http (api). Also disables auth-token
  -2, --l2-connect string         Connection string for the l2 cache (default "scribble:///var/db/shaman")
  -l, --log-level string          Log level to output [fatal|error|info|debug|trace] (default "INFO")
  -s, --server                    Run in server mode
  -t, --token string              Token for API Access (default "secret")
  -T, --ttl int                   Default TTL for DNS records (default 60)
  -v, --version                   Print version info and exit

Use "shaman [command] --help" for more information about a command.

For usage examples, see api and/or cli readme

As a Server

To start shaman as a server run:
shaman --server
An optional config file can also be passed on startup:
shaman -c config.json

config.json

{
 "api-domain": "shaman.nanobox.io",
 "api-crt": "",
 "api-key": "",
 "api-key-password": "",
 "api-listen": "127.0.0.1:1632",
 "token": "secret",
 "insecure": false,
 "l2-connect": "scribble:///var/db/shaman",
 "ttl": 60,
 "domain": ".",
 "dns-listen": "127.0.0.1:53",
 "log-level": "info",
 "server": true
}

L2 connection strings

Scribble Cacher

The connection string looks like scribble://localhost/path/to/data/store.

API:

Route Description Payload Output
POST /records Adds the domain and full record json domain object json domain object
PUT /records Update all domains and records (replaces all) json array of domain objects json array of domain objects
GET /records Returns a list of domains we have records for nil string array of domains
PUT /records/{domain} Update domain's records (replaces all) json domain object json domain object
GET /records/{domain} Returns the records for that domain nil json domain object
DELETE /records/{domain} Delete a domain nil success message

note: The API requires a token to be passed for authentication by default and is configurable at server start (--token). The token is passed in as a custom header: X-AUTH-TOKEN.

For examples, see the api's readme

Overview

+------------+     +----------+     +-----------------+
|            +----->          +----->                 |
| API Server |     |          |     |   Short-Term    |
|            <-----+ Caching  <-----+   (in-memory)   |
+------------+     | And      |     +-----------------+
                   | Database |
+------------+     | Manager  |     +-----------------+
|            +----->          +----->                 |
| DNS Server |     |          |     | Long-Term (L2)  |
|            <-----+          <-----+                 |
+------------+     +----------+     +-----------------+

Data types:

Domain (Resource):

json:

{
  "domain": "nanopack.io.",
  "records": [
    {
      "ttl": 60,
      "class": "IN",
      "type": "A",
      "address": "127.0.0.1"
    },
    {
      "ttl": 60,
      "class": "IN",
      "type": "A",
      "address": "127.0.0.2"
    }
  ]
}

Fields:

  • domain: Domain name to resolve
  • records: Array of address records
    • ttl: Seconds a client should cache for
    • class: Record class
    • type: Record type
      • A - Address record
      • CNAME - Canonical name record
      • MX - Mail exchange record
      • Many more - may or may not work as is
    • address: Address domain resolves to
      • note: Special rules apply in some cases. E.g. MX records require a number "10 mail.google.com"

Error:

json:

{
  "err": "exit status 2: unexpected argument"
}

Fields:

  • err: Error message

Message:

json:

{
  "msg": "Success"
}

Fields:

  • msg: Success message

Todo

  • atomic local cache updates
  • export in hosts file format
  • improve scribble add (adding before stored in cache overwrites)

Changelog

  • v0.0.2 (May 11, 2016)
    • Refactor to allow multiple records per domain and more fully utilize dns library
  • v0.0.3 (May 12, 2016)
    • Tests for DNS server
    • Start Server Insecure
  • v0.0.4 (Aug 16, 2016)
    • Postgresql as a backend

Contributing

Contributions to shaman are welcome and encouraged. Shaman is a Nanobox project and contributions should follow the Nanobox Contribution Process & Guidelines.

oss logo