desec

README

deSEC for libdns

This package implements the libdns interfaces for deSEC.

Authentication

Authentication performed using a token created on https://desec.io/tokens. A basic token without the permission to manage tokens is sufficient. For security reasons it's strongly recommended to not use tokens that allow token management.

Limitations and Caveats

• Concurrent updates from multiple processes can result in an inconsistent state
• The TTL attribute is not settable per record (zone, name, type, value), only per record set (zone, name, type). If different TTL values are specified, it's undefined which one wins.
• Large zones with more than 500 resource record sets only have limited support
• Rate limiting always results in retries if no context deadline is specified

Please refer to the Go reference for detailed documentation.

Documentation

Overview

Package desec implements a DNS record management client compatible with the libdns interfaces for deSEC.

Updates are not atomic

The deSEC API doesn't map 1:1 to the libdns API. The main issue with that is that it's not possible to update records atomically. The implementation here goes to great lengths to avoid interference of multiple concurrent requests, but that only works within a single process.

If multiple processes are modifying a deSEC zone concurrently, care must be taken that the different processes operate on different resource record sets. Otherwise multiple concurrent operations will override one another. The easiest way to protect against that is to use different names within the zone for different processes.

If multiple processes operate on the same resource record set, it's possible for two concurrently running writes to result in inconsistent records.

TTL attribute

For a the same reason as above, the TTL attribute cannot be set on the per record level. If multiple different TTLs are specified for different records of the same name and type, one of them wins. It's not defined which on that is.

Large zones (> 500 resource record sets)

deSEC requires the use of pagination for zones with more than 500 RRSets. This is a reasonable limit for a general purpose library like libdns and no effort is made to handle zones with more than 500 RRSets. Methods that can fail with more than 500 RRSets have a godoc comment explaining this.

Rate Limiting

deSEC applies rate limiting, this implementation will retry when running into a rate limit while observing context cancellation. In practice this means that calls to methods of this provider can take multiple seconds and longer. It's therefore very important to set a deadline in the context.

Index

• type Provider
  • func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)
  • func (p *Provider) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

Types

type Provider

type Provider struct {
	// Token is a token created on https://desec.io/tokens. A basic token without the permission
	// to manage tokens is sufficient.
	Token string `json:"token,omitempty"`
}

Provider facilitates DNS record manipulation with deSEC.

func (*Provider) AppendRecords

func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

AppendRecords adds records to the zone. It returns the records that were added.

func (*Provider) DeleteRecords

func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

DeleteRecords deletes the records from the zone. It returns the records that were deleted.

func (*Provider) GetRecords

func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)

GetRecords lists all the records in the zone.

Caveat: This method will fail if there are more than 500 RRsets in the zone. See package documentation for more detail.

func (*Provider) SetRecords

func (p *Provider) SetRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)

SetRecords sets the records in the zone, either by updating existing records or creating new ones. It returns the updated records.

Caveat: This method will fail if there are more than 500 RRsets in the zone. See package documentation for more detail.