realm

README

Realm

A simple non-recursive DNS server written in go.

Installation

Go get

go get -u github.com/brettlangdon/realm/cmd/...

Build

git clone https://github.com/brettlangdon/realm
cd ./realm
make

Usage

$ realm --help
usage: realm [--bind BIND] [ZONE [ZONE ...]]

positional arguments:
  zone                   DNS zone files to serve from this server

options:
  --bind BIND            [<host>]:<port> to bind too [default: :53]
  --help, -h             display this help and exit

Zone file

To run a server you must have a DNS zone file.

A simple example looks like the following:

$ORIGIN example.com.     ; designates the start of this zone file in the namespace
$TTL 1h                  ; default expiration time of all resource records without their own TTL value
example.com.  IN  SOA   ns.example.com. username.example.com. ( 2007120710 1d 2h 4w 1h )
example.com.  IN  NS    ns                    ; ns.example.com is a nameserver for example.com
example.com.  IN  NS    ns.somewhere.example. ; ns.somewhere.example is a backup nameserver for example.com
example.com.  IN  MX    10 mail.example.com.  ; mail.example.com is the mailserver for example.com
@             IN  MX    20 mail2.example.com. ; equivalent to above line, "@" represents zone origin
@             IN  MX    50 mail3              ; equivalent to above line, but using a relative host name
example.com.  IN  A     192.0.2.1             ; IPv4 address for example.com
              IN  AAAA  2001:db8:10::1        ; IPv6 address for example.com
ns            IN  A     192.0.2.2             ; IPv4 address for ns.example.com
              IN  AAAA  2001:db8:10::2        ; IPv6 address for ns.example.com
www           IN  CNAME example.com.          ; www.example.com is an alias for example.com
wwwtest       IN  CNAME www                   ; wwwtest.example.com is another alias for www.example.com
mail          IN  A     192.0.2.3             ; IPv4 address for mail.example.com
mail2         IN  A     192.0.2.4             ; IPv4 address for mail2.example.com
mail3         IN  A     192.0.2.5             ; IPv4 address for mail3.example.com

Example taken from here.

Starting the server

realm ./domain.zone

By default realm binds to port 53, which usually requires root, so you may need to run sudo realm ./domain.zone.

You can also specify any number of zone files by providing multiple zone files.

realm ./first.domain.zone ./second.domain.zone

Documentation

Overview

Package realm implements a simple non-recursive DNS server.

INSTALLATION

To install realm:

go get -u github.com/brettlangdon/realm/cmd/...

USAGE

Realm will parse your server configuration from a DNS zone file see https://en.wikipedia.org/wiki/Zone_file for more information.

To start a server:

realm ./domain.zone
realm --bind "127.0.0.1:1053" ./first.domain.zone ./second.domain.zone

Full command usage:

usage: realm [--bind BIND] [ZONE [ZONE ...]]

positional arguments:
  zone                   DNS zone files to serve from this server

options:
  --bind BIND            [<host>]:<port> to bind too [default: :53]
  --help, -h             display this help and exit

Index

• type DomainEntry
  • func (entry DomainEntry) AddEntry(record dns.RR)
  • func (entry DomainEntry) GetEntries(rrClass uint16) []RecordsEntry
• type RecordsEntry
  • func (entry RecordsEntry) GetRecords(rrType uint16) []dns.RR
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) AddZone(z *Zone)
  • func (r *Registry) Lookup(name string, reqType uint16, reqClass uint16) []dns.RR
• type Server
  • func NewServer(listen string, registry *Registry, statsdHost string) (*Server, error)
  • func (s *Server) ListenAndServe() error
  • func (s *Server) ServeDNS(w dns.ResponseWriter, request *dns.Msg)
• type Zone
  • func ParseZone(filename string) (*Zone, error)
  • func (zone *Zone) Records() []dns.RR

Types

type DomainEntry

type DomainEntry map[uint16]RecordsEntry

DomainEntry is used to hold a mapping of DNS request classes to RecordEntrys

func (DomainEntry) AddEntry

func (entry DomainEntry) AddEntry(record dns.RR)

AddEntry is used to add a new DNS record to this mapping

func (DomainEntry) GetEntries

func (entry DomainEntry) GetEntries(rrClass uint16) []RecordsEntry

GetEntries is used to find the appropriate RecordEntrys for the requested DNS class

type RecordsEntry

type RecordsEntry map[uint16][]dns.RR

RecordsEntry is used to hold a mapping of DNS request types to DNS records

func (RecordsEntry) GetRecords

func (entry RecordsEntry) GetRecords(rrType uint16) []dns.RR

GetRecords will fetch the appropriate DNS records to the requested type

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry is a container for looking up DNS records for any request

func NewRegistry

func NewRegistry() *Registry

NewRegistry will allocate and return a new *Registry

func (*Registry) AddZone

func (r *Registry) AddZone(z *Zone)

AddZone is used to add the records from a *Zone into this *Registry

func (*Registry) Lookup

func (r *Registry) Lookup(name string, reqType uint16, reqClass uint16) []dns.RR

Lookup will find all records which we should respond with for the given name, request type, and request class.

type Server

type Server struct {
	// contains filtered or unexported fields
}

A Server listens for DNS requests over UDP and responds with answers from the provided Zone.

func NewServer

func NewServer(listen string, registry *Registry, statsdHost string) (*Server, error)

NewServer returns a new initialized *Server that will bind to listen and will look up answers from zone.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe will start the nameserver on the configured address.

func (*Server) ServeDNS

func (s *Server) ServeDNS(w dns.ResponseWriter, request *dns.Msg)

ServeDNS will be called for every DNS request to this server. It will attempt to provide answers to all questions from the configured zone.

type Zone

type Zone struct {
	// contains filtered or unexported fields
}

A Zone a container for records parsed from a zone file.

func ParseZone

func ParseZone(filename string) (*Zone, error)

ParseZone will attempt to parse a zone file from the provided filename and return a Zone. ParseZone will return an error if the file provided does not exist or could not be properly parsed.

func (*Zone) Records

func (zone *Zone) Records() []dns.RR

Records will retrieve the DNS records for this zone