netnod

README

netnod-primary-dns-client

Go client for Netnod Primary DNS API.

Installation

go get github.com/netnod/netnod-primary-dns-client

Use

package main

import (
    "fmt"
    "log"

    netnod "github.com/netnod/netnod-primary-dns-client"
)

func main() {
    client := netnod.NewClient("", "your-api-token") // empty URL = default

    // List all zones
    zones, err := client.ListZones()

    // List zones filtered by end customer
    zones, err = client.ListZones(netnod.WithEndCustomerName("customer123"))
    if err != nil {
        log.Fatal(err)
    }
    for _, z := range zones {
        fmt.Printf("%s (serial: %d)\n", z.Name, z.NotifiedSerial)
    }

    // Fetch a zone with all records
    zone, err := client.GetZone("example.com.")
    if err != nil {
        log.Fatal(err)
    }
    for _, rrset := range zone.RRsets {
        fmt.Printf("%s %s\n", rrset.Name, rrset.Type)
    }

    // Create / update RR
    ttl := int64(3600)
    err = client.PatchZoneRRsets("example.com.", []netnod.RRset{
        {
            Name:       "www.example.com.",
            Type:       "A",
            TTL:        &ttl,
            ChangeType: "REPLACE",
            Records: []netnod.Record{
                {Content: "192.0.2.1", Disabled: false},
            },
        },
    })

    // Create zone from BIND zone file
    created, err := client.CreateZoneFromBIND(&netnod.ZoneCreateBIND{
        Name:       "example.com.",
        Zone:       "example.com.\t3600\tIN\tSOA\tns1.example.com. hostmaster.example.com. 2025110401 10800 3600 604800 3600\nexample.com.\t3600\tIN\tNS\tns1.example.com.",
        AlsoNotify: []string{"1.2.3.4"},
    })

    // Export zone in BIND format
    bindData, err := client.ExportZone("example.com.")

    // Trigger immediate DNS NOTIFY
    _, err = client.NotifyZone("example.com.")

    // DynDNS management
    labels, err := client.ListDynDNS("example.com.")
    dyndns, err := client.CreateDynDNS("example.com.", "home")
    fmt.Println(dyndns.Token) // save this token
    err = client.DeleteDynDNS("example.com.", "home")

    // ACME DNS-01 challenge management
    acmeLabels, err := client.ListACME("example.com.")
    acme, err := client.CreateACME("example.com.", "www")
    fmt.Println(acme.Token) // save this token
    err = client.DeleteACME("example.com.", "www")
}

API

Client

// Create a client (empty baseURL = https://primarydnsapi.netnod.se)
client := netnod.NewClient(baseURL, token)

Zones

Method	Description
ListZones(options...)	List all zones; optionally pass WithEndCustomerName(name) to filter
GetZone(zoneID)	Get zone with all RRsets
CreateZone(zone)	Create new zone with RRsets
CreateZoneFromBIND(zone)	Create new zone from BIND zone file data
UpdateZone(zoneID, zone)	Update zone configuration
DeleteZone(zoneID)	Delete zone
ExportZone(zoneID)	Export zone in BIND zone file format
NotifyZone(zoneID)	Trigger immediate DNS NOTIFY

Records

Method	Description
PatchZoneRRsets(zoneID, rrsets)	Create/update/delete records
GetRRset(zoneID, name, type)	Get specific RRset

DynDNS

Method	Description
ListDynDNS(zoneID)	List DynDNS-enabled labels
CreateDynDNS(zoneID, label)	Enable DynDNS for a label (returns token)
DeleteDynDNS(zoneID, label)	Disable DynDNS for a label

ACME DNS-01

Method	Description
ListACME(zoneID)	List ACME-enabled labels
CreateACME(zoneID, label)	Enable ACME for a label (returns token)
DeleteACME(zoneID, label)	Disable ACME for a label

ChangeType for PatchZoneRRsets

Value	Description
REPLACE	Replace all records in RRset
DELETE	Delete RRset
EXTEND	Add records if not already present
PRUNE	Remove specific records from RRset

License

BSD 3-Clause License, see LICENSE.

Documentation

Overview

Package netnod provides a Go client for the Netnod Primary DNS API.

Index

• Constants
• func WithEndCustomerName(endCustomerName string) listZonesOption
• type ACMECreateResponse
• type ACMELabel
• type ACMEListResponse
• type Client
  • func NewClient(baseURL, token string) *Client
  • func (c *Client) CreateACME(zoneID, label string) (*ACMECreateResponse, error)
  • func (c *Client) CreateDynDNS(zoneID, label string) (*DynDNSCreateResponse, error)
  • func (c *Client) CreateZone(zone *Zone) (*Zone, error)
  • func (c *Client) CreateZoneFromBIND(zone *ZoneCreateBIND) (*Zone, error)
  • func (c *Client) DeleteACME(zoneID, label string) error
  • func (c *Client) DeleteDynDNS(zoneID, label string) error
  • func (c *Client) DeleteZone(zoneID string) error
  • func (c *Client) ExportZone(zoneID string) (string, error)
  • func (c *Client) GetRRset(zoneID, name, rrType string) (*RRset, error)
  • func (c *Client) GetZone(zoneID string) (*Zone, error)
  • func (c *Client) ListACME(zoneID string) ([]ACMELabel, error)
  • func (c *Client) ListDynDNS(zoneID string) ([]DynDNSLabel, error)
  • func (c *Client) ListZones(options ...listZonesOption) ([]Zone, error)
  • func (c *Client) NotifyZone(zoneID string) (*NotifyResponse, error)
  • func (c *Client) PatchZoneRRsets(zoneID string, rrsets []RRset) error
  • func (c *Client) SetHTTPClient(httpClient *http.Client)
  • func (c *Client) UpdateZone(zoneID string, zone *Zone) error
• type DynDNSCreateResponse
• type DynDNSLabel
• type DynDNSListResponse
• type ErrorResponse
• type NotifyResponse
• type RRset
• type Record
• type Zone
• type ZoneCreateBIND
• type ZoneListResponse

Constants

const DefaultAPIURL = "https://primarydnsapi.netnod.se"

DefaultAPIURL is the default Netnod Primary DNS API endpoint

Functions

func WithEndCustomerName

func WithEndCustomerName(endCustomerName string) listZonesOption

WithEndCustomerName filters ListZones results to the given end customer.

Types

type ACMECreateResponse

type ACMECreateResponse struct {
	Hostname          string `json:"hostname"`
	ChallengeHostname string `json:"challenge_hostname"`
	Token             string `json:"token"`
}

ACMECreateResponse represents the response from enabling ACME

type ACMELabel

type ACMELabel struct {
	Label             string `json:"label"`
	Hostname          string `json:"hostname"`
	ChallengeHostname string `json:"challenge_hostname"`
}

ACMELabel represents an ACME-enabled label

type ACMEListResponse

type ACMEListResponse struct {
	Labels []ACMELabel `json:"labels"`
}

ACMEListResponse represents the response from listing ACME labels

type Client

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

Client is a client for the Netnod Primary DNS API

func NewClient

func NewClient(baseURL, token string) *Client

NewClient creates a new Netnod Primary DNS API client

func (*Client) CreateACME

func (c *Client) CreateACME(zoneID, label string) (*ACMECreateResponse, error)

CreateACME enables ACME DNS-01 challenges for a label in a zone

func (*Client) CreateDynDNS

func (c *Client) CreateDynDNS(zoneID, label string) (*DynDNSCreateResponse, error)

CreateDynDNS enables DynDNS for a label in a zone

func (*Client) CreateZone

func (c *Client) CreateZone(zone *Zone) (*Zone, error)

CreateZone creates a new zone

func (*Client) CreateZoneFromBIND

func (c *Client) CreateZoneFromBIND(zone *ZoneCreateBIND) (*Zone, error)

CreateZoneFromBIND creates a new zone using BIND zone file format

func (*Client) DeleteACME

func (c *Client) DeleteACME(zoneID, label string) error

DeleteACME disables ACME for a label in a zone

func (*Client) DeleteDynDNS

func (c *Client) DeleteDynDNS(zoneID, label string) error

DeleteDynDNS disables DynDNS for a label in a zone

func (*Client) DeleteZone

func (c *Client) DeleteZone(zoneID string) error

DeleteZone deletes a zone

func (*Client) ExportZone

func (c *Client) ExportZone(zoneID string) (string, error)

ExportZone exports a zone in BIND zone file format

func (*Client) GetRRset

func (c *Client) GetRRset(zoneID, name, rrType string) (*RRset, error)

GetRRset finds a specific RRset in a zone

func (*Client) GetZone

func (c *Client) GetZone(zoneID string) (*Zone, error)

GetZone returns a specific zone with all RRsets

func (*Client) ListACME

func (c *Client) ListACME(zoneID string) ([]ACMELabel, error)

ListACME lists all ACME-enabled labels for a zone

func (*Client) ListDynDNS

func (c *Client) ListDynDNS(zoneID string) ([]DynDNSLabel, error)

ListDynDNS lists all DynDNS-enabled labels for a zone

func (*Client) ListZones

func (c *Client) ListZones(options ...listZonesOption) ([]Zone, error)

ListZones returns all zones, automatically paginating through all results.

func (*Client) NotifyZone

func (c *Client) NotifyZone(zoneID string) (*NotifyResponse, error)

NotifyZone triggers an immediate DNS NOTIFY for a zone

func (*Client) PatchZoneRRsets

func (c *Client) PatchZoneRRsets(zoneID string, rrsets []RRset) error

PatchZoneRRsets updates specific RRsets in a zone

func (*Client) SetHTTPClient

func (c *Client) SetHTTPClient(httpClient *http.Client)

SetHTTPClient allows setting a custom HTTP client (useful for testing)

func (*Client) UpdateZone

func (c *Client) UpdateZone(zoneID string, zone *Zone) error

UpdateZone updates zone configuration. The zone's Name is never sent: the API rejects a "name" key in the request body, so it's stripped here regardless of what the caller passes (e.g. a Zone round-tripped from GetZone, which always has Name populated).

type DynDNSCreateResponse

type DynDNSCreateResponse struct {
	Hostname string `json:"hostname"`
	Token    string `json:"token"`
}

DynDNSCreateResponse represents the response from enabling DynDNS

type DynDNSLabel

type DynDNSLabel struct {
	Label    string `json:"label"`
	Hostname string `json:"hostname"`
}

DynDNSLabel represents a DynDNS-enabled label

type DynDNSListResponse

type DynDNSListResponse struct {
	Labels []DynDNSLabel `json:"labels"`
}

DynDNSListResponse represents the response from listing DynDNS labels

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse represents an API error

type NotifyResponse

type NotifyResponse struct {
	Result string `json:"result"`
}

NotifyResponse represents the response from a notify request

type RRset

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

RRset represents a resource record set

type Record

type Record struct {
	Content  string `json:"content"`
	Disabled bool   `json:"disabled"`
}

Record represents a single DNS record

type Zone

type Zone struct {
	ID                string   `json:"id,omitempty"`
	Name              string   `json:"name,omitempty"`
	NotifiedSerial    int64    `json:"notified_serial,omitempty"`
	AlsoNotify        []string `json:"also_notify,omitempty"`
	AllowTransferKeys []string `json:"allow_transfer_keys,omitempty"`
	EndCustomer       string   `json:"endcustomer,omitempty"`
	RRsets            []RRset  `json:"rrsets,omitempty"`
}

Zone represents a DNS zone

type ZoneCreateBIND

type ZoneCreateBIND struct {
	Name              string   `json:"name"`
	Zone              string   `json:"zone"`
	AlsoNotify        []string `json:"also_notify,omitempty"`
	AllowTransferKeys []string `json:"allow_transfer_keys,omitempty"`
	EndCustomer       string   `json:"endcustomer,omitempty"`
}

ZoneCreateBIND represents a zone creation request using BIND zone file format

type ZoneListResponse

type ZoneListResponse struct {
	Data   []Zone `json:"data"`
	Offset int    `json:"offset"`
	Limit  int    `json:"limit"`
	Total  int    `json:"total"`
}

ZoneListResponse represents the paginated zone list response