pdns

README

PowerDNS client library for Go

This package contains a Go library for accessing the PowerDNS Authoritative API.

Supported features

• Servers
• Zones
• Cryptokeys
• Metadata
• TSIG Keys
• Searching
• Statistics
• Cache

Installation

Install using go get:

> go get github.com/mittwald/go-powerdns

Usage

First, instantiate a client using pdns.New:

client, err := pdns.New(
    pdns.WithBaseURL("http://localhost:8081"),
    pdns.WithAPIKeyAuthentication("supersecret"),
)

The client then offers more specialiced sub-clients, for example for managing server and zones. Have a look at this library's documentation for more information.

Complete example

package main

import "context"
import "github.com/mittwald/go-powerdns"
import "github.com/mittwald/go-powerdns/apis/zones"

func main() {
    client, err := pdns.New(
        pdns.WithBaseURL("http://localhost:8081"),
        pdns.WithAPIKeyAuthentication("supersecret"),
    )
	
    if err != nil {
    	panic(err)
    }
    
    client.Zones().CreateZone(context.Background(), "localhost", zones.Zone{
        Name: "mydomain.example.",
        Type: zones.ZoneTypeZone,
        Kind: zones.ZoneKindNative,
        Nameservers: []string{
            "ns1.example.com.",
            "ns2.example.com.",
        },
        ResourceRecordSets: []zones.ResourceRecordSet{
            {Name: "foo.mydomain.example.", Type: "A", TTL: 60, Records: []zones.Record{{Content: "127.0.0.1"}}},
        },
    })
}

Documentation

Overview

This package contains a client library used for connecting to the PowerDNS API.

Index

• type Client
  • func New(opt ...ClientOption) (Client, error)
• type ClientOption
  • func WithAPIKeyAuthentication(key string) ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithDebuggingOutput(out io.Writer) ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
  • func WithTLSAuthentication(caFile string, clientCertFile string, clientKeyFile string) ClientOption

Examples

• Client (CreateZone)
• Client (GetServer)
• Client (ListServers)
• Client (WaitUntilUp)
• New (WithAPIKeyAuthentication)
• New (WithDebugging)

Types

type Client

type Client interface {

	// Status checks if the PowerDNS API is reachable. This does a simple HTTP connection check;
	// it will NOT check if your authentication is set up correctly (except you're using TLS client
	// authentication.
	Status() error

	// WaitUntilUp will block until the PowerDNS API accepts HTTP requests. You can use the "ctx"
	// parameter to make this method wait only for (or until) a certain time (see examples).
	WaitUntilUp(ctx context.Context) error

	// Servers returns a specialized API for interacting with PowerDNS servers
	Servers() servers.Client

	// Zones returns a specialized API for interacting with PowerDNS zones
	Zones() zones.Client

	// Search returns a specialized API for searching
	Search() search.Client

	// Cache returns a specialized API for caching
	Cache() cache.Client

	// Cryptokeys returns a specialized API for cryptokeys
	Cryptokeys() cryptokeys.Client
}

Client is the root-level interface for interacting with the PowerDNS API. You can instantiate an implementation of this interface using the "New" function.

Example (CreateZone)

This example uses the "Zones()" sub-client to create a new zone.

client, _ := New(
	WithBaseURL("http://localhost:8081"),
	WithAPIKeyAuthentication("secret"),
)

input := zones.Zone{
	Name: "mydomain.example.",
	Type: zones.ZoneTypeZone,
	Kind: zones.ZoneKindNative,
	Nameservers: []string{
		"ns1.example.com.",
		"ns2.example.com.",
	},
	ResourceRecordSets: []zones.ResourceRecordSet{
		{Name: "foo.mydomain.example.", Type: "A", TTL: 60, Records: []zones.Record{{Content: "127.0.0.1"}}},
	},
}

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

zone, err := client.Zones().CreateZone(ctx, "localhost", input)
if err != nil {
	panic(err)
}

fmt.Printf("zone ID: %s\n", zone.ID)

Output:

zone ID: mydomain.example.

Example (GetServer)

client, _ := New(
	WithBaseURL("http://localhost:8081"),
	WithAPIKeyAuthentication("secret"),
)

server, err := client.Servers().GetServer(context.Background(), "localhost")
if err != nil {
	if pdnshttp.IsNotFound(err) {
		// handle not found
	} else {
		panic(err)
	}
}

fmt.Printf("found server: %s\n", server.ID)

Example (ListServers)

client, _ := New(
	WithBaseURL("http://localhost:8081"),
	WithAPIKeyAuthentication("secret"),
)

servers, err := client.Servers().ListServers(context.Background())
if err != nil {
	panic(err)
}
for i := range servers {
	fmt.Printf("found server: %s\n", servers[i].ID)
}

Example (WaitUntilUp)

This example uses the "context.WithTimeout" function to wait until the PowerDNS API is reachable up until a given timeout is reached. After that, the "WaitUntilUp" method will return with an error.

client, _ := New(
	WithBaseURL("http://localhost:8081"),
	WithAPIKeyAuthentication("secret"),
)

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

err := client.WaitUntilUp(ctx)
if err != nil {
	panic(err)
}

func New

func New(opt ...ClientOption) (Client, error)

New creates a new PowerDNS client. Various client options can be used to configure the PowerDNS client (see examples).

Example (WithAPIKeyAuthentication)

This example uses with WithAPIKeyAuthentication function to add API-key based authentication to the PowerDNS client.

client, err := New(
	WithBaseURL("http://your-dns-server.example:8081"),
	WithAPIKeyAuthentication("super-secret"),
)

if err != nil {
	panic(err)
}

client.Status()

Example (WithDebugging)

This example uses the WithDebuggingOutput function; this will cause all HTTP requests and responses to be logged to the io.Writer that is supplied to WithDebuggingOutput.

client, err := New(
	WithBaseURL("http://your-dns-server.example:8081"),
	WithAPIKeyAuthentication("super-secret"),
	WithDebuggingOutput(os.Stdout),
)

if err != nil {
	panic(err)
}

client.Status()

type ClientOption

type ClientOption func(c *client) error

func WithAPIKeyAuthentication

func WithAPIKeyAuthentication(key string) ClientOption

WithAPIKeyAuthentication adds API-key based authentication to the PowerDNS client. In effect, each HTTP request will have an additional header that contains the API key supplied to this function:

X-API-Key: {{ key }}

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets a client's base URL

func WithDebuggingOutput

func WithDebuggingOutput(out io.Writer) ClientOption

WithDebuggingOutput can be used to supply an io.Writer to the client into which all outgoing HTTP requests and their responses will be logged. Useful for debugging.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient can be used to override a client's HTTP client. Otherwise, the default HTTP client will be used

func WithTLSAuthentication

func WithTLSAuthentication(caFile string, clientCertFile string, clientKeyFile string) ClientOption

WithTLSAuthentication configures TLS-based authentication for the PowerDNS client. This is not a feature that is provided by PowerDNS natively, but might be implemented when the PowerDNS API is run behind a reverse proxy.