powerdns package - github.com/joeig/go-powerdns/v3 - Go Packages (original) (raw)

Package powerdns is a Go client library for the PowerDNS API. It's a community project and not associated with the official PowerDNS product itself.

domain := fmt.Sprintf("%d.example.com.", rand.Int())

// Let's say // * PowerDNS Authoritative Server is listening on http://localhost:80, // * the virtual host is localhost and // * the API key is apipw. pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw"))

// All API interactions support a Go context, which allow you to pass cancellation signals and deadlines. // If you don't need a context, context.Background() would be the right choice for the following examples. // If you want to learn more about how context helps you to build reliable APIs, see: https://go.dev/blog/context ctx := context.Background()

// Create a native zone zone, err := pdns.Zones.AddNative(ctx, domain, false, "", false, "", "", true, []string{"localhost."}) if err != nil { log.Fatalf("%v", err) }

o, _ := json.MarshalIndent(zone, "", "\t") log.Printf("Zone: %s\n\n", o)

// Add and change an A record if err := pdns.Records.Add(ctx, domain, fmt.Sprintf("www.%s", domain), powerdns.RRTypeA, 1337, []string{"127.0.0.9"}); err != nil { log.Fatalf("%v", err) } if err := pdns.Records.Change(ctx, domain, fmt.Sprintf("www.%s", domain), powerdns.RRTypeA, 42, []string{"127.0.0.10"}); err != nil { log.Fatalf("%v", err) }

// update the existing record with a comment comment := powerdns.Comment{ Content: powerdns.String("Example comment"), Account: powerdns.String("example account"), ModifiedAt: powerdns.Uint64(uint64(time.Now().Unix())), } if err := pdns.Records.Change(ctx, domain, fmt.Sprintf("www.%s", domain), powerdns.RRTypeA, 42, []string{"127.0.0.10"}, powerdns.WithComments(comment)); err != nil { log.Fatalf("%v", err) }

// Add a MX record with multiple values if err := pdns.Records.Add(ctx, domain, domain, powerdns.RRTypeMX, 1337, []string{"10 mx1.example.com.", "20 mx2.example.com."}); err != nil { log.Fatalf("%v", err) }

// Add a TXT record if err := pdns.Records.Add(ctx, domain, fmt.Sprintf("www.%s", domain), powerdns.RRTypeTXT, 1337, []string{""foo1""}); err != nil { log.Fatalf("%v", err) }

// Create a TSIG Record exampleKey, err := pdns.TSIGKeys.Create(ctx, "examplekey", "hmac-sha256", "") if err != nil { log.Fatalf("%v", err) }

// Change a zone zoneChangeSet := &powerdns.Zone{ Account: powerdns.String("test"), DNSsec: powerdns.Bool(true), MasterTSIGKeyIDs: []string{*exampleKey.ID}, }

if err := pdns.Zones.Change(ctx, domain, zoneChangeSet); err != nil { log.Fatalf("%v", err) }

// Retrieve zone attributes changedZone, err := pdns.Zones.Get(ctx, domain) if err != nil { log.Fatalf("%v", err) }

o, _ = json.MarshalIndent(changedZone, "", "\t") log.Printf("Changed zone: %q\n\n", o) log.Printf("Account is %q and DNSsec is %t\n\n", powerdns.StringValue(changedZone.Account), powerdns.BoolValue(changedZone.DNSsec))

This section is empty.

This section is empty.

Bool is a helper function that allocates a new bool value to store v and returns a pointer to it.

BoolValue is a helper function that returns the value of a bool pointer or false.

String is a helper function that allocates a new string value to store v and returns a pointer to it.

StringValue is a helper function that returns the value of a bool pointer or "".

Uint32 is a helper function that allocates a new uint32 value to store v and returns a pointer to it.

Uint32Value is a helper function that returns the value of a bool pointer or 0.

Uint64 is a helper function that allocates a new uint64 value to store v and returns a pointer to it.

Uint64Value is a helper function that returns the value of a bool pointer or 0.

func WithComments(comments ...Comment) func(*RRset)

WithComments defines a function to create a comment option for Add and Change methods

type AxfrRetrieveResult struct { Result *string json:"result,omitempty" }

AxfrRetrieveResult structure with JSON API metadata

type CacheFlushResult struct { Count *uint32 json:"count,omitempty" Result *string json:"result,omitempty" }

CacheFlushResult structure with JSON API metadata

ChangeType represents a string-valued change type

const (

ChangeTypeReplace [ChangeType](#ChangeType) = "REPLACE"

ChangeTypeDelete [ChangeType](#ChangeType) = "DELETE"

)

func ChangeTypePtr(v ChangeType) *ChangeType

ChangeTypePtr is a helper function that allocates a new ChangeType value to store v and returns a pointer to it.

type Client struct { BaseURL string VHost string

Config     *[ConfigService](#ConfigService)
Cryptokeys *[CryptokeysService](#CryptokeysService)
Metadata   *[MetadataService](#MetadataService)
Records    *[RecordsService](#RecordsService)
Servers    *[ServersService](#ServersService)
Statistics *[StatisticsService](#StatisticsService)
Zones      *[ZonesService](#ZonesService)

TSIGKey  *[TSIGKeysService](#TSIGKeysService)
TSIGKeys *[TSIGKeysService](#TSIGKeysService)

}

Client configuration structure

New initializes a new client instance.

_ = powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw"))

NewClient initializes a new client instance.

Deprecated: Use New with functional options instead. NewClient will be removed with the next major version.

type Comment struct { Content *string json:"content,omitempty" }

Comment structure with JSON API metadata

type ConfigService service

ConfigService handles communication with the zones related methods of the Client API

List retrieves a list of ConfigSettings

type ConfigSetting struct { Name *string json:"name,omitempty" Type *string json:"type,omitempty" Value *string json:"value,omitempty" }

ConfigSetting structure with JSON API metadata

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" }

Cryptokey structure with JSON API metadata

type CryptokeysService service

CryptokeysService handles communication with the cryptokeys related methods of the Client API

Delete removes a given Cryptokey

Get returns a certain Cryptokey instance of a given Zone

List retrieves a list of Cryptokeys that belong to a Zone

type Error struct { StatusCode int json:"-" Status string json:"-" Message string json:"error" }

Error structure with JSON API metadata

type Metadata struct { Kind *MetadataKind json:"kind,omitempty" Metadata []string json:"metadata,omitempty" }

Metadata structure with JSON API metadata

MetadataKind represents a string-valued metadata kind

const (

MetadataAllowAXFRFrom [MetadataKind](#MetadataKind) = "ALLOW-AXFR-FROM"


MetadataTSIGAllowAXFR [MetadataKind](#MetadataKind) = "TSIG-ALLOW-AXFR"


MetadataAXFRMasterTSIG [MetadataKind](#MetadataKind) = "AXFR-MASTER-TSIG"


MetadataSOAEdit [MetadataKind](#MetadataKind) = "SOA-EDIT"


MetadataSOAEditAPI [MetadataKind](#MetadataKind) = "SOA-EDIT-API"


MetadataNSEC3Param [MetadataKind](#MetadataKind) = "NSEC3PARAM"


MetadataPresigned [MetadataKind](#MetadataKind) = "PRESIGNED"


MetadataLuaAXFRScript [MetadataKind](#MetadataKind) = "LUA-AXFR-SCRIPT"


MetadataAPIRectify [MetadataKind](#MetadataKind) = "API-RECTIFY"


MetadataPublishCDNSKey [MetadataKind](#MetadataKind) = "PUBLISH-CDNSKEY"


MetadataPublishCDS [MetadataKind](#MetadataKind) = "PUBLISH-CDS"


MetadataSlaveRenotify [MetadataKind](#MetadataKind) = "SLAVE-RENOTIFY"


MetadataAXFRSource [MetadataKind](#MetadataKind) = "AXFR-SOURCE"


MetadataNotifyDNSUpdate [MetadataKind](#MetadataKind) = "NOTIFY-DNSUPDATE"


MetadataAlsoNotify [MetadataKind](#MetadataKind) = "ALSO-NOTIFY"


MetadataForwardDNSUpdate [MetadataKind](#MetadataKind) = "FORWARD-DNSUPDATE"


MetadataAllowDNSUpdateFrom [MetadataKind](#MetadataKind) = "ALLOW-DNSUPDATE-FROM"


MetadataTSIGAllowDNSUpdate [MetadataKind](#MetadataKind) = "TSIG-ALLOW-DNSUPDATE"


MetadataIXFR [MetadataKind](#MetadataKind) = "IXFR"

)

func MetadataKindPtr(v MetadataKind) *MetadataKind

MetadataKindPtr is a helper function that allocates a new MetadataKind value to store v and returns a pointer to it.

type MetadataService service

MetadataService handles communication with the metadata-related methods of the Client API

Create creates a new metadata entry for a zone

Delete removes a metadata kind from a zone

Get retrieves a specific metadata kind for a zone

List retrieves all metadata for a zone

Set creates or modifies a metadata kind for a zone (existing entries for the zone with the same kind are removed)

type NewOption func(*Client)

NewOption is a functional option for New.

WithAPIKey is an option for New to set the API key.

WithHTTPClient is an option for New to set an HTTP client.

WithHeaders is an option for New to set HTTP client headers.

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

NotifyResult structure with JSON API metadata

RRType represents a string-valued resource record type

const (

RRTypeA [RRType](#RRType) = "A"

RRTypeAAAA [RRType](#RRType) = "AAAA"

RRTypeA6 [RRType](#RRType) = "A6"

RRTypeAFSDB [RRType](#RRType) = "AFSDB"

RRTypeALIAS [RRType](#RRType) = "ALIAS"

RRTypeDHCID [RRType](#RRType) = "DHCID"

RRTypeDLV [RRType](#RRType) = "DLV"

RRTypeCAA [RRType](#RRType) = "CAA"

RRTypeCERT [RRType](#RRType) = "CERT"

RRTypeCDNSKEY [RRType](#RRType) = "CDNSKEY"

RRTypeCDS [RRType](#RRType) = "CDS"

RRTypeCNAME [RRType](#RRType) = "CNAME"

RRTypeDNSKEY [RRType](#RRType) = "DNSKEY"

RRTypeDNAME [RRType](#RRType) = "DNAME"

RRTypeDS [RRType](#RRType) = "DS"

RRTypeEUI48 [RRType](#RRType) = "EUI48"

RRTypeEUI64 [RRType](#RRType) = "EUI64"

RRTypeHINFO [RRType](#RRType) = "HINFO"

RRTypeIPSECKEY [RRType](#RRType) = "IPSECKEY"

RRTypeKEY [RRType](#RRType) = "KEY"

RRTypeKX [RRType](#RRType) = "KX"

RRTypeLOC [RRType](#RRType) = "LOC"

RRTypeLUA [RRType](#RRType) = "LUA"

RRTypeMAILA [RRType](#RRType) = "MAILA"

RRTypeMAILB [RRType](#RRType) = "MAILB"

RRTypeMINFO [RRType](#RRType) = "MINFO"

RRTypeMR [RRType](#RRType) = "MR"

RRTypeMX [RRType](#RRType) = "MX"

RRTypeNAPTR [RRType](#RRType) = "NAPTR"

RRTypeNS [RRType](#RRType) = "NS"

RRTypeNSEC [RRType](#RRType) = "NSEC"

RRTypeNSEC3 [RRType](#RRType) = "NSEC3"

RRTypeNSEC3PARAM [RRType](#RRType) = "NSEC3PARAM"

RRTypeOPENPGPKEY [RRType](#RRType) = "OPENPGPKEY"

RRTypePTR [RRType](#RRType) = "PTR"

RRTypeRKEY [RRType](#RRType) = "RKEY"

RRTypeRP [RRType](#RRType) = "RP"

RRTypeRRSIG [RRType](#RRType) = "RRSIG"

RRTypeSIG [RRType](#RRType) = "SIG"

RRTypeSOA [RRType](#RRType) = "SOA"

RRTypeSPF [RRType](#RRType) = "SPF"

RRTypeSSHFP [RRType](#RRType) = "SSHFP"

RRTypeSRV [RRType](#RRType) = "SRV"

RRTypeTKEY [RRType](#RRType) = "TKEY"

RRTypeTSIG [RRType](#RRType) = "TSIG"

RRTypeTLSA [RRType](#RRType) = "TLSA"

RRTypeSMIMEA [RRType](#RRType) = "SMIMEA"

RRTypeTXT [RRType](#RRType) = "TXT"

RRTypeURI [RRType](#RRType) = "URI"

RRTypeWKS [RRType](#RRType) = "WKS"

)

func RRTypePtr(v RRType) *RRType

RRTypePtr is a helper function that allocates a new RRType value to store v and returns a pointer to it.

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

RRset structure with JSON API metadata

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

RRsets structure with JSON API metadata

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

Record structure with JSON API metadata

type RecordsService service

RecordsService handles communication with the records related methods of the Client API

Add creates a new resource record

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if err := pdns.Records.Add(ctx, "example.com.", "www.example.com.", powerdns.RRTypeA, 1337, []string{"127.0.0.9"}); err != nil { log.Fatalf("%v", err) }

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if err := pdns.Records.Add(ctx, "example.com.", "www.example.com.", powerdns.RRTypeMX, 1337, []string{"10 mx1.example.com.", "20 mx2.example.com."}); err != nil { log.Fatalf("%v", err) }

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if err := pdns.Records.Add(ctx, "example.com.", "www.example.com.", powerdns.RRTypeTXT, 1337, []string{""foo1""}); err != nil { log.Fatalf("%v", err) }

Change replaces an existing resource record

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if err := pdns.Records.Change(ctx, "example.com.", "www.example.com.", powerdns.RRTypeA, 42, []string{"127.0.0.10"}); err != nil { log.Fatalf("%v", err) }

Delete removes an existing resource record

Get retrieves rrsets with name and recordType (if provided)

Patch method makes patch of already prepared rrsets

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 ServersService service

ServersService handles communication with the servers related methods of the Client API

CacheFlush flushes a cache-entry by name

Get returns a certain Server

List retrieves a list of Servers

type Statistic struct { Name *string json:"name,omitempty" Type *string json:"type,omitempty"

Size *[string](/builtin#string) `json:"size,omitempty"`


Value interface{} `json:"value,omitempty"`

}

Statistic structure with JSON API metadata

type StatisticsService service

StatisticsService handles communication with the statistics related methods of the Client API

Get retrieves certain Statistics

List retrieves a list of Statistics

type TSIGKey struct { Name *string json:"name,omitempty" ID *string json:"id,omitempty" Algorithm *string json:"algorithm,omitempty" Key *string json:"key,omitempty" Type *string json:"type,omitempty" }

TSIGKey structure with JSON API metadata

type TSIGKeysService service

TSIGKeysService handles communication with the tsigs related methods of the Client API

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if _, err := pdns.TSIGKeys.Change(ctx, *exampleTSIGKey.ID, exampleTSIGKey); err != nil { log.Fatalf("%v", err) }

Create a new TSIG Key setting empty string for key will generate it

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

_, err := pdns.TSIGKeys.Create(ctx, *exampleTSIGKey.Name, *exampleTSIGKey.Algorithm, "") if err != nil { log.Fatalf("%v", err) }

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if err := pdns.TSIGKeys.Delete(ctx, *exampleTSIGKey.ID); err != nil { log.Fatalf("%v", err) }

Get returns a certain TSIGKeys

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if _, err := pdns.TSIGKeys.Get(ctx, *exampleTSIGKey.ID); err != nil { log.Fatalf("%v", err) }

List retrieves a list of TSIGKeys

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

if _, err := pdns.TSIGKeys.List(ctx); err != nil { log.Fatalf("%v", err) }

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" EditedSerial *uint32 json:"edited_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" Catalog *string json:"catalog,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" }

Zone structure with JSON API metadata

ZoneKind string type

const (

NativeZoneKind [ZoneKind](#ZoneKind) = "Native"

MasterZoneKind [ZoneKind](#ZoneKind) = "Master"

SlaveZoneKind [ZoneKind](#ZoneKind) = "Slave"

ProducerZoneKind [ZoneKind](#ZoneKind) = "Producer"

ConsumerZoneKind [ZoneKind](#ZoneKind) = "Consumer"

)

func ZoneKindPtr(v ZoneKind) *ZoneKind

ZoneKindPtr is a helper function that allocates a new ZoneKind value to store v and returns a pointer to it.

ZoneType string type

const ZoneZoneType ZoneType = "Zone"

ZoneZoneType sets the zone's type to zone

func ZoneTypePtr(v ZoneType) *ZoneType

ZoneTypePtr is a helper function that allocates a new ZoneType value to store v and returns a pointer to it.

type ZonesService service

ZonesService handles communication with the zones related methods of the Client API

AddMaster creates a new master zone

AddNative creates a new native zone

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

zone, err := pdns.Zones.AddNative(ctx, "example.com.", false, "", false, "", "", true, []string{"localhost."}) if err != nil { log.Fatalf("%v", err) }

log.Printf("Zone: %v", zone)

AddSlave creates a new slave zone

AxfrRetrieve requests a axfr transfer from the master to requesting slave

Change modifies an existing zone

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background() zoneChangeSet := &powerdns.Zone{ Account: powerdns.String("test"), DNSsec: powerdns.Bool(true), }

if err := pdns.Zones.Change(ctx, "example.com.", zoneChangeSet); err != nil { log.Fatalf("%v", err) }

Delete removes a certain Zone for a given domain

Export returns a BIND-like Zone file

Get returns a certain Zone for a given domain

pdns := powerdns.New("http://localhost:8080", "localhost", powerdns.WithAPIKey("apipw")) ctx := context.Background()

zone, err := pdns.Zones.Get(ctx, "example.com.") if err != nil { log.Fatalf("%v", err) }

log.Printf("Zone: %v", zone)

List retrieves a list of Zones

Notify sends a DNS notify packet to all slaves