powerdns

README

PowerDNS 4.1 API bindings for Golang

This community project provides bindings for the currently latest version of PowerDNS.

Setup

Requirements

• PowerDNS 4.1 ("API v1")
  • --webserver=yes --api=yes --api-key=apipw --api-readonly=no
  • Note that API v1 is actively maintained. There are differences between 3.x, 4.0 and 4.1 and this client works only with 4.1.
• Tested with Go version 1.11/1.12/1.13, according to Go's version support policy (should work with other minor releases as well)

Install from source

go get -u github.com/joeig/go-powerdns

Usage

Initialize the handle

import "github.com/joeig/go-powerdns"

pdns := powerdns.NewClient("http://localhost:80", "localhost", map[string]string{"X-API-Key": "apipw"}, nil)

Assuming that the server is listening on http://localhost:80 for virtual host localhost, the API password is apipw and you want to edit the domain example.com.

Get/add/change/delete zones

zones, err := pdns.GetZones()
zone, err := pdns.GetZone("example.com")
export, err := zone.Export()
zone, err := pdns.AddNativeZone("example.com", true, "", false, "foo", "foo", true, []string{"ns.foo.tld."})
err := pdns.ChangeZone(&zone)
err := zone.DeleteZone()

Add/change/delete resource records

err := zone.AddRecord("www.example.com", "AAAA", 60, []string{"::1"})
err := zone.ChangeRecord("www.example.com", "AAAA", 3600, []string{"::1"})
err := zone.DeleteRecord("www.example.com", "A")
notifyResult, err := zone.Notify()

Request server information and statistics

statistics, err := pdns.GetStatistics()
servers, err := pdns.GetServers()
server, err := pdns.GetServer()

Handle DNSSEC cryptographic material

cryptokeys, err := zone.GetCryptokeys()
cryptokey, err := zone.GetCryptokey("1337")
err := cryptokey.ToggleCryptokey()
err := cryptokey.DeleteCryptokey()

Documentation

See GoDoc.

Contribution

This API client has not been completed yet, so feel free to contribute. The OpenAPI specification might be a good reference.

Start a PowerDNS authoritative server including a generic MySQL backend, DNSSEC support and some fixtures using Docker compose:

docker-compose up
docker-compose exec powerdns sh init_docker_fixtures.sh

It's also possible to target mocks against this server:

make test-without-mocks

Based on the work of jgreat and waynz0r.

Documentation

Index

• type Comment
• type Cryptokey
  • func (c *Cryptokey) DeleteCryptokey() error
  • func (c *Cryptokey) ToggleCryptokey() error
• type Error
  • func (e Error) Error() string
• type Export
• type NotifyResult
• type PowerDNS
  • func NewClient(baseURL string, vhost string, headers map[string]string, ...) *PowerDNS
  • func (p *PowerDNS) AddMasterZone(domain string, dnssec bool, nsec3Param string, nsec3Narrow bool, ...) (*Zone, error)
  • func (p *PowerDNS) AddNativeZone(domain string, dnssec bool, nsec3Param string, nsec3Narrow bool, ...) (*Zone, error)
  • func (p *PowerDNS) AddSlaveZone(domain string, masters []string) (*Zone, error)
  • func (p *PowerDNS) ChangeZone(zone *Zone) error
  • func (p *PowerDNS) DeleteZone(domain string) error
  • func (p *PowerDNS) GetServer() (*Server, error)
  • func (p *PowerDNS) GetServers() ([]Server, error)
  • func (p *PowerDNS) GetStatistics() ([]Statistic, error)
  • func (p *PowerDNS) GetZone(domain string) (*Zone, error)
  • func (p *PowerDNS) GetZones() ([]Zone, error)
• type RRset
• type RRsets
• type Record
• type Server
• type Statistic
• type Zone
  • func (z *Zone) AddRecord(name string, recordType string, ttl uint32, content []string) error
  • func (z *Zone) ChangeRecord(name string, recordType string, ttl uint32, content []string) error
  • func (z *Zone) DeleteCryptokey(id uint64) error
  • func (z *Zone) DeleteRecord(name string, recordType string) error
  • func (z *Zone) DeleteZone() error
  • func (z *Zone) Export() (Export, error)
  • func (z *Zone) GetCryptokey(id uint64) (*Cryptokey, error)
  • func (z *Zone) GetCryptokeys() ([]Cryptokey, error)
  • func (z *Zone) Notify() (*NotifyResult, error)
  • func (z *Zone) ToggleCryptokey(id uint64) error
• type ZoneKind
• type ZoneType

Types

type Comment

type Comment struct {
	Content    string `json:"content,omitempty"`
	Account    string `json:"account,omitempty"`
	ModifiedAt uint64 `json:"modified_at,omitempty"`
}

Comment structure with JSON API metadata

type Cryptokey

type Cryptokey struct {
	Type       string   `json:"type,omitempty"`
	ID         uint64   `json:"id,omitempty"`
	KeyType    string   `json:"keytype,omitempty"`
	Active     bool     `json:"active,omitempty"`
	DNSkey     string   `json:"dnskey,omitempty"`
	DS         []string `json:"ds,omitempty"`
	Privatekey string   `json:"privatekey,omitempty"`
	Algorithm  string   `json:"algorithm,omitempty"`
	Bits       uint64   `json:"bits,omitempty"`
	ZoneHandle *Zone    `json:"-"`
}

Cryptokey structure with JSON API metadata

func (*Cryptokey) DeleteCryptokey

func (c *Cryptokey) DeleteCryptokey() error

DeleteCryptokey removes a given Cryptokey

func (*Cryptokey) ToggleCryptokey

func (c *Cryptokey) ToggleCryptokey() error

ToggleCryptokey enables/disables a given Cryptokey

type Error

type Error struct {
	Status  string
	Message string `json:"error"`
}

Error structure with JSON API metadata

func (Error) Error

func (e Error) Error() string

type Export

type Export string

Export string type

type NotifyResult

type NotifyResult struct {
	Result string `json:"result,omitempty"`
}

NotifyResult structure with JSON API metadata

type PowerDNS

type PowerDNS struct {
	Scheme   string
	Hostname string
	Port     string
	VHost    string
	Headers  map[string]string
	// contains filtered or unexported fields
}

PowerDNS configuration structure

func NewClient

func NewClient(baseURL string, vhost string, headers map[string]string, httpClient *http.Client) *PowerDNS

NewClient initializes a new PowerDNS client configuration

func (*PowerDNS) AddMasterZone

func (p *PowerDNS) AddMasterZone(domain string, dnssec bool, nsec3Param string, nsec3Narrow bool, soaEdit string, soaEditApi string, apiRectify bool, nameservers []string) (*Zone, error)

AddMasterZone creates a new master zone

func (*PowerDNS) AddNativeZone

func (p *PowerDNS) AddNativeZone(domain string, dnssec bool, nsec3Param string, nsec3Narrow bool, soaEdit string, soaEditApi string, apiRectify bool, nameservers []string) (*Zone, error)

AddNativeZone creates a new native zone

func (*PowerDNS) AddSlaveZone

func (p *PowerDNS) AddSlaveZone(domain string, masters []string) (*Zone, error)

AddSlaveZone creates a new slave zone

func (*PowerDNS) ChangeZone

func (p *PowerDNS) ChangeZone(zone *Zone) error

ChangeZone modifies an existing zone

func (*PowerDNS) DeleteZone

func (p *PowerDNS) DeleteZone(domain string) error

DeleteZone removes a certain Zone for a given domain

func (*PowerDNS) GetServer

func (p *PowerDNS) GetServer() (*Server, error)

GetServer returns a certain Server

func (*PowerDNS) GetServers

func (p *PowerDNS) GetServers() ([]Server, error)

GetServers retrieves a list of Servers

func (*PowerDNS) GetStatistics

func (p *PowerDNS) GetStatistics() ([]Statistic, error)

GetStatistics retrieves a list of Statistics

func (*PowerDNS) GetZone

func (p *PowerDNS) GetZone(domain string) (*Zone, error)

GetZone returns a certain Zone for a given domain

func (*PowerDNS) GetZones

func (p *PowerDNS) GetZones() ([]Zone, error)

GetZones retrieves a list of Zones

type RRset

type RRset struct {
	Name       string    `json:"name,omitempty"`
	Type       string    `json:"type,omitempty"`
	TTL        uint32    `json:"ttl,omitempty"`
	ChangeType string    `json:"changetype,omitempty"`
	Records    []Record  `json:"records,omitempty"`
	Comments   []Comment `json:"comments,omitempty"`
}

RRset structure with JSON API metadata

type RRsets

type RRsets struct {
	Sets []RRset `json:"rrsets,omitempty"`
}

RRsets structure with JSON API metadata

type Record

type Record struct {
	Content  string `json:"content,omitempty"`
	Disabled bool   `json:"disabled"`
	SetPTR   bool   `json:"set-ptr,omitempty"`
}

Record structure with JSON API metadata

type Server

type Server struct {
	Type       string `json:"type,omitempty"`
	ID         string `json:"id,omitempty"`
	DaemonType string `json:"daemon_type,omitempty"`
	Version    string `json:"version,omitempty"`
	URL        string `json:"url,omitempty"`
	ConfigURL  string `json:"config_url,omitempty"`
	ZonesURL   string `json:"zones_url,omitempty"`
}

Server structure with JSON API metadata

type Statistic

type Statistic struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value"`
}

Statistic structure with JSON API metadata

type Zone

type Zone struct {
	ID               string    `json:"id,omitempty"`
	Name             string    `json:"name,omitempty"`
	Type             ZoneType  `json:"type,omitempty"`
	URL              string    `json:"url,omitempty"`
	Kind             ZoneKind  `json:"kind,omitempty"`
	RRsets           []RRset   `json:"rrsets,omitempty"`
	Serial           uint32    `json:"serial,omitempty"`
	NotifiedSerial   uint32    `json:"notified_serial,omitempty"`
	Masters          []string  `json:"masters,omitempty"`
	DNSsec           bool      `json:"dnssec,omitempty"`
	Nsec3Param       string    `json:"nsec3param,omitempty"`
	Nsec3Narrow      bool      `json:"nsec3narrow,omitempty"`
	Presigned        bool      `json:"presigned,omitempty"`
	SOAEdit          string    `json:"soa_edit,omitempty"`
	SOAEditAPI       string    `json:"soa_edit_api,omitempty"`
	APIRectify       bool      `json:"api_rectify,omitempty"`
	Zone             string    `json:"zone,omitempty"`
	Account          string    `json:"account,omitempty"`
	Nameservers      []string  `json:"nameservers,omitempty"`
	MasterTSIGKeyIDs []string  `json:"master_tsig_key_ids,omitempty"`
	SlaveTSIGKeyIDs  []string  `json:"slave_tsig_key_ids,omitempty"`
	PowerDNSHandle   *PowerDNS `json:"-"`
}

Zone structure with JSON API metadata

func (*Zone) AddRecord

func (z *Zone) AddRecord(name string, recordType string, ttl uint32, content []string) error

AddRecord creates a new resource record

func (*Zone) ChangeRecord

func (z *Zone) ChangeRecord(name string, recordType string, ttl uint32, content []string) error

ChangeRecord replaces an existing resource record

func (*Zone) DeleteCryptokey

func (z *Zone) DeleteCryptokey(id uint64) error

DeleteCryptokey removes a given Cryptokey

func (*Zone) DeleteRecord

func (z *Zone) DeleteRecord(name string, recordType string) error

DeleteRecord removes an existing resource record

func (*Zone) DeleteZone

func (z *Zone) DeleteZone() error

DeleteZone removes a certain Zone for a given domain

func (*Zone) Export

func (z *Zone) Export() (Export, error)

Export returns a BIND-like Zone file

func (*Zone) GetCryptokey

func (z *Zone) GetCryptokey(id uint64) (*Cryptokey, error)

GetCryptokey returns a certain Cryptokey instance of a given Zone

func (*Zone) GetCryptokeys

func (z *Zone) GetCryptokeys() ([]Cryptokey, error)

GetCryptokeys retrieves a list of Cryptokeys that belong to a Zone

func (*Zone) Notify

func (z *Zone) Notify() (*NotifyResult, error)

Notify sends a DNS notify packet to all slaves

func (*Zone) ToggleCryptokey

func (z *Zone) ToggleCryptokey(id uint64) error

ToggleCryptokey enables/disables a given Cryptokey

type ZoneKind

type ZoneKind string

ZoneKind string type

const (
	// NativeZoneKind sets the zone's kind to native
	NativeZoneKind ZoneKind = "Native"
	// MasterZoneKind sets the zone's kind to master
	MasterZoneKind ZoneKind = "Master"
	// SlaveZoneKind sets the zone's kind to slave
	SlaveZoneKind ZoneKind = "Slave"
)

type ZoneType

type ZoneType string

ZoneType string type

const ZoneZoneType ZoneType = "Zone"

ZoneZoneType sets the zone's type to zone