Documentation

Index

Constants

View Source
const DefaultTTL = uint32(300)

    DefaultTTL is applied to any DNS record without an explicit TTL.

    Variables

    This section is empty.

    Functions

    func IsQuoted

    func IsQuoted(s string) bool

      IsQuoted returns true if the string starts and ends with a double quote.

      func ParseQuotedTxt

      func ParseQuotedTxt(s string) []string

        ParseQuotedTxt returns the individual strings of a combined quoted string. `foo` -> []string{"foo"} `"foo"` -> []string{"foo"} `"foo" "bar"` -> []string{"foo", "bar"} NOTE: it is assumed there is exactly one space between the quotes.

        func PostProcessRecords

        func PostProcessRecords(recs []*RecordConfig)

          PostProcessRecords does any post-processing of the downloaded DNS records.

          func StripQuotes

          func StripQuotes(s string) string

            StripQuotes returns the string with the starting and ending quotes removed.

            Types

            type Correction

            type Correction struct {
            	F   func() error `json:"-"`
            	Msg string
            }

              Correction is anything that can be run. Implementation is up to the specific provider.

              type DNSConfig

              type DNSConfig struct {
              	Registrars         []*RegistrarConfig            `json:"registrars"`
              	DNSProviders       []*DNSProviderConfig          `json:"dns_providers"`
              	Domains            []*DomainConfig               `json:"domains"`
              	RegistrarsByName   map[string]*RegistrarConfig   `json:"-"`
              	DNSProvidersByName map[string]*DNSProviderConfig `json:"-"`
              }

                DNSConfig describes the desired DNS configuration, usually loaded from dnsconfig.js.

                func (*DNSConfig) DomainContainingFQDN

                func (config *DNSConfig) DomainContainingFQDN(fqdn string) *DomainConfig

                  DomainContainingFQDN finds the best domain from the dns config for the given record fqdn. It will chose the domain whose name is the longest suffix match for the fqdn.

                  func (*DNSConfig) FindDomain

                  func (config *DNSConfig) FindDomain(query string) *DomainConfig

                    FindDomain returns the *DomainConfig for domain query in config.

                    type DNSProvider

                    type DNSProvider interface {
                    	GetNameservers(domain string) ([]*Nameserver, error)
                    	GetDomainCorrections(dc *DomainConfig) ([]*Correction, error)
                    }

                      DNSProvider is an interface for DNS Provider plug-ins.

                      type DNSProviderConfig

                      type DNSProviderConfig struct {
                      	Name     string          `json:"name"`
                      	Type     string          `json:"type"`
                      	Metadata json.RawMessage `json:"meta,omitempty"`
                      }

                        DNSProviderConfig describes a DNS service provider.

                        type DNSProviderInstance

                        type DNSProviderInstance struct {
                        	ProviderBase
                        	Driver              DNSProvider
                        	NumberOfNameservers int
                        }

                          DNSProviderInstance is a single DNS provider.

                          type DomainConfig

                          type DomainConfig struct {
                          	Name             string         `json:"name"` // NO trailing "."
                          	RegistrarName    string         `json:"registrar"`
                          	DNSProviderNames map[string]int `json:"dnsProviders"`
                          
                          	Metadata      map[string]string `json:"meta,omitempty"`
                          	Records       Records           `json:"records"`
                          	Nameservers   []*Nameserver     `json:"nameservers,omitempty"`
                          	KeepUnknown   bool              `json:"keepunknown,omitempty"`
                          	IgnoredLabels []string          `json:"ignored_labels,omitempty"`
                          
                          	// These fields contain instantiated provider instances once everything is linked up.
                          	// This linking is in two phases:
                          	// 1. Metadata (name/type) is availible just from the dnsconfig. Validation can use that.
                          	// 2. Final driver instances are loaded after we load credentials. Any actual provider interaction requires that.
                          	RegistrarInstance    *RegistrarInstance     `json:"-"`
                          	DNSProviderInstances []*DNSProviderInstance `json:"-"`
                          }

                            DomainConfig describes a DNS domain (tecnically a DNS zone).

                            func (*DomainConfig) Copy

                            func (dc *DomainConfig) Copy() (*DomainConfig, error)

                              Copy returns a deep copy of the DomainConfig.

                              func (*DomainConfig) Filter

                              func (dc *DomainConfig) Filter(f func(r *RecordConfig) bool)

                                Filter removes all records that don't match the filter f.

                                func (*DomainConfig) HasRecordTypeName

                                func (dc *DomainConfig) HasRecordTypeName(rtype, name string) bool

                                  HasRecordTypeName returns True if there is a record with this rtype and name.

                                  func (*DomainConfig) Punycode

                                  func (dc *DomainConfig) Punycode() error

                                    Punycode will convert all records to punycode format. It will encode: - Name - NameFQDN - Target (CNAME and MX only)

                                    type Nameserver

                                    type Nameserver struct {
                                    	Name string `json:"name"` // Normalized to a FQDN with NO trailing "."
                                    }

                                      Nameserver describes a nameserver.

                                      func StringsToNameservers

                                      func StringsToNameservers(nss []string) []*Nameserver

                                        StringsToNameservers constructs a list of *Nameserver structs using a list of FQDNs.

                                        func (*Nameserver) String

                                        func (n *Nameserver) String() string

                                        type ProviderBase

                                        type ProviderBase struct {
                                        	Name         string
                                        	IsDefault    bool
                                        	ProviderType string
                                        }

                                          ProviderBase describes providers.

                                          type RecordConfig

                                          type RecordConfig struct {
                                          	Type             string            `json:"type"`   // All caps rtype name.
                                          	Name             string            `json:"name"`   // The short name. See above.
                                          	NameFQDN         string            `json:"-"`      // Must end with ".$origin". See above.
                                          	Target           string            `json:"target"` // If a name, must end with "."
                                          	TTL              uint32            `json:"ttl,omitempty"`
                                          	Metadata         map[string]string `json:"meta,omitempty"`
                                          	MxPreference     uint16            `json:"mxpreference,omitempty"`
                                          	SrvPriority      uint16            `json:"srvpriority,omitempty"`
                                          	SrvWeight        uint16            `json:"srvweight,omitempty"`
                                          	SrvPort          uint16            `json:"srvport,omitempty"`
                                          	CaaTag           string            `json:"caatag,omitempty"`
                                          	CaaFlag          uint8             `json:"caaflag,omitempty"`
                                          	TlsaUsage        uint8             `json:"tlsausage,omitempty"`
                                          	TlsaSelector     uint8             `json:"tlsaselector,omitempty"`
                                          	TlsaMatchingType uint8             `json:"tlsamatchingtype,omitempty"`
                                          	TxtStrings       []string          `json:"txtstrings,omitempty"` // TxtStrings stores all strings (including the first). Target stores only the first one.
                                          	R53Alias         map[string]string `json:"r53_alias,omitempty"`
                                          
                                          	Original interface{} `json:"-"` // Store pointer to provider-specific record object. Used in diffing.
                                          }

                                            RecordConfig stores a DNS record. Valid types:

                                            Official:
                                              A
                                              AAAA
                                              ANAME  // Technically not an official rtype yet.
                                              CAA
                                              CNAME
                                              MX
                                              NS
                                              PTR
                                              SRV
                                              TLSA
                                              TXT
                                            Pseudo-Types:
                                              ALIAS
                                              CF_REDIRECT
                                              CF_TEMP_REDIRECT
                                              FRAME
                                              IMPORT_TRANSFORM
                                              NAMESERVER
                                              NO_PURGE
                                              PAGE_RULE
                                              PURGE
                                              URL
                                              URL301
                                            

                                            Notes about the fields:

                                            Name:

                                            This is the shortname i.e. the NameFQDN without the origin suffix.
                                            It should never have a trailing "."
                                            It should never be null. The apex (naked domain) is stored as "@".
                                            If the origin is "foo.com." and Name is "foo.com", this literally means
                                                the intended FQDN is "foo.com.foo.com." (which may look odd)
                                            

                                            NameFQDN:

                                            This is the FQDN version of Name.
                                            It should never have a trailiing ".".
                                            NOTE: Eventually we will unexport Name/NameFQDN. Please start using
                                              the setters (SetLabel/SetLabelFromFQDN) and getters (GetLabel/GetLabelFQDN).
                                              as they will always work.
                                            

                                            Target:

                                            This is the host or IP address of the record, with
                                              the other related paramters (weight, priority, etc.) stored in individual
                                              fields.
                                            NOTE: Eventually we will unexport Target. Please start using the
                                              setters (SetTarget*) and getters (GetTarget*) as they will always work.
                                            

                                            Idioms:

                                            rec.Label() == "@"   // Is this record at the apex?
                                            

                                            func (*RecordConfig) Copy

                                            func (rc *RecordConfig) Copy() (*RecordConfig, error)

                                              Copy returns a deep copy of a RecordConfig.

                                              func (*RecordConfig) GetLabel

                                              func (rc *RecordConfig) GetLabel() string

                                                GetLabel returns the shortname of the label associated with this RecordConfig. It will never end with "." It does not need further shortening (i.e. if it returns "foo.com" and the

                                                domain is "foo.com" then the FQDN is actually "foo.com.foo.com").
                                                

                                                It will never be "" (the apex is returned as "@").

                                                func (*RecordConfig) GetLabelFQDN

                                                func (rc *RecordConfig) GetLabelFQDN() string

                                                  GetLabelFQDN returns the FQDN of the label associated with this RecordConfig. It will not end with ".".

                                                  func (*RecordConfig) GetTargetCombined

                                                  func (rc *RecordConfig) GetTargetCombined() string

                                                    GetTargetCombined returns a string with the various fields combined. For example, an MX record might output `10 mx10.example.tld`.

                                                    func (*RecordConfig) GetTargetDebug

                                                    func (rc *RecordConfig) GetTargetDebug() string

                                                      GetTargetDebug returns a string with the various fields spelled out.

                                                      func (*RecordConfig) GetTargetField

                                                      func (rc *RecordConfig) GetTargetField() string

                                                        GetTargetField returns the target. There may be other fields (for example an MX record also has a .MxPreference field.

                                                        func (*RecordConfig) GetTargetIP

                                                        func (rc *RecordConfig) GetTargetIP() net.IP

                                                          GetTargetIP returns the net.IP stored in Target.

                                                          func (*RecordConfig) GetTargetSortable

                                                          func (rc *RecordConfig) GetTargetSortable() string

                                                            GetTargetSortable returns a string that is sortable.

                                                            func (*RecordConfig) Key

                                                            func (rc *RecordConfig) Key() RecordKey

                                                              Key converts a RecordConfig into a RecordKey.

                                                              func (*RecordConfig) PopulateFromString

                                                              func (r *RecordConfig) PopulateFromString(rtype, contents, origin string) error

                                                                PopulateFromString populates a RecordConfig given a type and string. Many providers give all the parameters of a resource record in one big string (all the parameters of an MX, SRV, CAA, etc). Rather than have each provider rewrite this code many times, here's a helper function to use.

                                                                At this time, the idiom is to panic rather than continue with potentially misunderstood data. We do this panic() at the provider level. Therefore the typical calling sequence is:

                                                                if err := rc.PopulateFromString(rtype, value, origin); err != nil {
                                                                    panic(errors.Wrap(err, "unparsable record received from provider"))
                                                                }
                                                                

                                                                func (*RecordConfig) SetLabel

                                                                func (rc *RecordConfig) SetLabel(short, origin string)

                                                                  SetLabel sets the .Name/.NameFQDN fields given a short name and origin. origin must not have a trailing dot: The entire code base

                                                                  maintains dc.Name without the trailig dot. Finding a dot here means
                                                                  something is very wrong.
                                                                  

                                                                  short must not have a training dot: That would mean you have

                                                                  a FQDN, and shouldn't be using SetLabel().  Maybe SetLabelFromFQDN()?
                                                                  

                                                                  func (*RecordConfig) SetLabelFromFQDN

                                                                  func (rc *RecordConfig) SetLabelFromFQDN(fqdn, origin string)

                                                                    SetLabelFromFQDN sets the .Name/.NameFQDN fields given a FQDN and origin. fqdn may have a trailing "." but it is not required. origin may not have a trailing dot.

                                                                    func (*RecordConfig) SetTarget

                                                                    func (rc *RecordConfig) SetTarget(target string) error

                                                                      SetTarget sets the target, assuming that the rtype is appropriate.

                                                                      func (*RecordConfig) SetTargetCAA

                                                                      func (rc *RecordConfig) SetTargetCAA(flag uint8, tag string, target string) error

                                                                        SetTargetCAA sets the CAA fields.

                                                                        func (*RecordConfig) SetTargetCAAString

                                                                        func (rc *RecordConfig) SetTargetCAAString(s string) error

                                                                          SetTargetCAAString is like SetTargetCAA but accepts one big string. Ex: `0 issue "letsencrypt.org"`

                                                                          func (*RecordConfig) SetTargetCAAStrings

                                                                          func (rc *RecordConfig) SetTargetCAAStrings(flag, tag, target string) error

                                                                            SetTargetCAAStrings is like SetTargetCAA but accepts strings.

                                                                            func (*RecordConfig) SetTargetIP

                                                                            func (rc *RecordConfig) SetTargetIP(ip net.IP) error

                                                                              SetTargetIP sets the target to an IP, verifying this is an appropriate rtype.

                                                                              func (*RecordConfig) SetTargetMX

                                                                              func (rc *RecordConfig) SetTargetMX(pref uint16, target string) error

                                                                                SetTargetMX sets the MX fields.

                                                                                func (*RecordConfig) SetTargetMXString

                                                                                func (rc *RecordConfig) SetTargetMXString(s string) error

                                                                                  SetTargetMXString is like SetTargetMX but accepts one big string.

                                                                                  func (*RecordConfig) SetTargetMXStrings

                                                                                  func (rc *RecordConfig) SetTargetMXStrings(pref, target string) error

                                                                                    SetTargetMXStrings is like SetTargetMX but accepts strings.

                                                                                    func (*RecordConfig) SetTargetSRV

                                                                                    func (rc *RecordConfig) SetTargetSRV(priority, weight, port uint16, target string) error

                                                                                      SetTargetSRV sets the SRV fields.

                                                                                      func (*RecordConfig) SetTargetSRVPriorityString

                                                                                      func (rc *RecordConfig) SetTargetSRVPriorityString(priority uint16, s string) error

                                                                                        SetTargetSRVPriorityString is like SetTargetSRV but accepts priority as an uint16 and the rest of the values joined in a string that needs to be parsed. This is a helper function that comes in handy when a provider re-uses the MX preference field as the SRV priority.

                                                                                        func (*RecordConfig) SetTargetSRVString

                                                                                        func (rc *RecordConfig) SetTargetSRVString(s string) error

                                                                                          SetTargetSRVString is like SetTargetSRV but accepts one big string to be parsed.

                                                                                          func (*RecordConfig) SetTargetSRVStrings

                                                                                          func (rc *RecordConfig) SetTargetSRVStrings(priority, weight, port, target string) (err error)

                                                                                            SetTargetSRVStrings is like SetTargetSRV but accepts all parameters as strings.

                                                                                            func (*RecordConfig) SetTargetTLSA

                                                                                            func (rc *RecordConfig) SetTargetTLSA(usage, selector, matchingtype uint8, target string) error

                                                                                              SetTargetTLSA sets the TLSA fields.

                                                                                              func (*RecordConfig) SetTargetTLSAString

                                                                                              func (rc *RecordConfig) SetTargetTLSAString(s string) error

                                                                                                SetTargetTLSAString is like SetTargetTLSA but accepts one big string.

                                                                                                func (*RecordConfig) SetTargetTLSAStrings

                                                                                                func (rc *RecordConfig) SetTargetTLSAStrings(usage, selector, matchingtype, target string) (err error)

                                                                                                  SetTargetTLSAStrings is like SetTargetTLSA but accepts strings.

                                                                                                  func (*RecordConfig) SetTargetTXT

                                                                                                  func (rc *RecordConfig) SetTargetTXT(s string) error

                                                                                                    SetTargetTXT sets the TXT fields when there is 1 string.

                                                                                                    func (*RecordConfig) SetTargetTXTString

                                                                                                    func (rc *RecordConfig) SetTargetTXTString(s string) error

                                                                                                      SetTargetTXTString is like SetTargetTXT but accepts one big string, which must be parsed into one or more strings based on how it is quoted. Ex: foo << 1 string

                                                                                                      foo bar         << 1 string
                                                                                                      "foo" "bar"     << 2 strings
                                                                                                      

                                                                                                      func (*RecordConfig) SetTargetTXTs

                                                                                                      func (rc *RecordConfig) SetTargetTXTs(s []string) error

                                                                                                        SetTargetTXTs sets the TXT fields when there are many strings.

                                                                                                        func (*RecordConfig) ToRR

                                                                                                        func (rc *RecordConfig) ToRR() dns.RR

                                                                                                          ToRR converts a RecordConfig to a dns.RR.

                                                                                                          func (*RecordConfig) UnsafeSetLabelNull

                                                                                                          func (rc *RecordConfig) UnsafeSetLabelNull()

                                                                                                            UnsafeSetLabelNull sets the label to "". Normally the FQDN is denoted by .Name being "@" however this can be used to violate that assertion. It should only be used on copies of a RecordConfig that is being used for non-standard things like Marshalling yaml.

                                                                                                            type RecordKey

                                                                                                            type RecordKey struct {
                                                                                                            	NameFQDN string
                                                                                                            	Type     string
                                                                                                            }

                                                                                                              RecordKey represents a resource record in a format used by some systems.

                                                                                                              type Records

                                                                                                              type Records []*RecordConfig

                                                                                                                Records is a list of *RecordConfig.

                                                                                                                func (Records) Grouped

                                                                                                                func (r Records) Grouped() map[RecordKey]Records

                                                                                                                  Grouped returns a map of keys to records.

                                                                                                                  func (Records) GroupedByLabel

                                                                                                                  func (r Records) GroupedByLabel() ([]string, map[string]Records)

                                                                                                                    GroupedByLabel returns a map of keys to records, and their original key order.

                                                                                                                    type Registrar

                                                                                                                    type Registrar interface {
                                                                                                                    	GetRegistrarCorrections(dc *DomainConfig) ([]*Correction, error)
                                                                                                                    }

                                                                                                                      Registrar is an interface for Registrar plug-ins.

                                                                                                                      type RegistrarConfig

                                                                                                                      type RegistrarConfig struct {
                                                                                                                      	Name     string          `json:"name"`
                                                                                                                      	Type     string          `json:"type"`
                                                                                                                      	Metadata json.RawMessage `json:"meta,omitempty"`
                                                                                                                      }

                                                                                                                        RegistrarConfig describes a registrar.

                                                                                                                        type RegistrarInstance

                                                                                                                        type RegistrarInstance struct {
                                                                                                                        	ProviderBase
                                                                                                                        	Driver Registrar
                                                                                                                        }

                                                                                                                          RegistrarInstance is a single registrar.