technitium

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package technitium is a client for the Technitium DNS Server HTTP API, the one its own web console uses. It is written by hand from the server's APIDOCS.md, which is the only description of the API there is (see api-defs/README.md), and knows nothing of MCP: everything above this package works with the typed values here and never sees a raw answer.

One Client talks to one server. Every call names its API path as a string literal handed to read, readWhole, readFile, write, writeWhole or upload, which is what lets the tests hold the package against the vendored document path by path.

Index

Constants

View Source
const (
	MinPasswordIterations = 100000
	MaxPasswordIterations = 1000000
)

The fewest and the most rounds a password may be hashed with.

View Source
const (
	NodePrimary   = "Primary"
	NodeSecondary = "Secondary"

	// NodeSelf is the node that was asked
	NodeSelf        = "Self"
	NodeConnected   = "Connected"
	NodeUnreachable = "Unreachable"
)

The roles a node has in a cluster, and the states one node sees another in.

View Source
const (
	AlgorithmRSA   = "RSA"
	AlgorithmECDSA = "ECDSA"
	AlgorithmEDDSA = "EDDSA"

	ProofNSEC  = "NSEC"
	ProofNSEC3 = "NSEC3"

	KeySigningKey  = "KeySigningKey"
	ZoneSigningKey = "ZoneSigningKey"
)

The ways a zone is signed, and the two proofs that a name is not there.

View Source
const (
	// ResolveThisServer asks the server itself, as a client of it would:
	// its own zones first, then its cache, its forwarders or recursion, with
	// its block lists applied
	ResolveThisServer = "this-server"
	// ResolveRecursively has the server resolve from the root, past its own
	// zones, cache, forwarders and block lists
	ResolveRecursively = "recursive-resolver"
)

Who a server can be asked to put a query to.

View Source
const (
	BlockedZone = "blocked-zone"
	BlockList   = "block-list-zone"
)

Where a blocked name's entry is.

View Source
const (
	StatsLastHour  = "LastHour"
	StatsLastDay   = "LastDay"
	StatsLastWeek  = "LastWeek"
	StatsLastMonth = "LastMonth"
	StatsLastYear  = "LastYear"
)

The windows a server keeps its statistics by.

View Source
const (
	TopClients        = "TopClients"
	TopDomains        = "TopDomains"
	TopBlockedDomains = "TopBlockedDomains"
)

The lists a server keeps of who asked most and what was asked for most.

View Source
const (
	// PolicyDeny is nobody, and PolicyAllow anybody
	PolicyDeny  = "Deny"
	PolicyAllow = "Allow"
	// NotifyNone is a zone telling nobody when it changes
	NotifyNone = "None"
)

The ways a zone's options say who may do something with it. Each of a zone's three policies - who may transfer it, who is told when it changes, who may update it - takes its own set of these.

View Source
const (
	ZonePrimary            = "Primary"
	ZoneSecondary          = "Secondary"
	ZoneStub               = "Stub"
	ZoneForwarder          = "Forwarder"
	ZoneSecondaryForwarder = "SecondaryForwarder"
	ZoneCatalog            = "Catalog"
	ZoneSecondaryCatalog   = "SecondaryCatalog"
)

The zone types the server hosts.

View Source
const APIVersion = "15.6.0"

APIVersion is the server version the vendored API document describes, and so the one this client was written against. A server ahead of it may answer with fields the client does not read; one behind it may lack a call.

View Source
const DefaultTSIGAlgorithm = "hmac-sha256"

DefaultTSIGAlgorithm is the algorithm a transfer key is made with when none is asked for.

View Source
const MinVersion = "15.0"

MinVersion is the oldest server this client can talk to: it sends its token in the Authorization header, which the API reads from 15.0.

View Source
const SessionAPIToken = "ApiToken"

SessionAPIToken is the type of a session that is an API token.

Variables

View Source
var SettingNames = []string{}/* 130 elements not displayed */

SettingNames are the settings the server takes, by the names its API knows them under: what SetSettings may be given. The tests hold the list against the API document.

View Source
var SettingsNeverRead = []string{"webServiceTlsCertificatePassword", "dnsTlsCertificatePassword", "proxyType", "proxyAddress", "proxyPort", "proxyUsername", "proxyPassword", "proxyBypass"}

SettingsNeverRead are the settings the server takes and never gives back under the name it takes them by: the two certificate passwords, which it does not give at all, and the proxy, which it gives as one thing under proxy. Any other setting a server does not answer with is one its version does not have, as 15.5 does not have enableCachePrefetch.

ZoneTypes are every type a zone can be, as the API spells them.

Functions

func IsInvalidToken

func IsInvalidToken(err error) bool

IsInvalidToken reports whether err is the server refusing the token.

func OptionNames

func OptionNames(recordType string) []string

OptionNames are what a record of a type may have beside its value, by the names the API takes them under: glue for an NS, how a forwarder is reached for a FWD, what an APP record tells its app.

func ParseTime

func ParseTime(s string) (time.Time, bool)

ParseTime reads a time as the server writes one, and reports false for one that is no time: it writes UTC with a Z, and for "never" the zero time with no zone at all.

func SetOption

func SetOption(data RData, recordType, option, value string) error

SetOption sets one option of a record's data, by the name the API takes it under: a type that has no such option is refused.

func WritableTypes

func WritableTypes() []string

WritableTypes are the record types the server has a layout of its own for, which this client adds, changes and deletes by their fields. Any other type but the ones a server keeps for itself is written too, as bytes in hex.

Types

type APIError

type APIError struct {
	// Path is the API call, zones/records/get say
	Path string
	// Status is what the server called the outcome: error, invalid-token or
	// 2fa-required
	Status string
	// Message is the server's own words
	Message string
	// Inner is the error under it, when the server gives one
	Inner string
	// Node is the server's name for itself, when it says
	Node string
}

APIError is the server refusing a call: the API answers every request it understands with HTTP 200 and says how it went in the body.

func (*APIError) Error

func (e *APIError) Error() string

type Access

type Access struct {
	Section string `json:"section"`
	// SubItem is the zone the permissions are for, "" for a whole section's
	SubItem string        `json:"subItem"`
	Users   []UserAccess  `json:"userPermissions"`
	Groups  []GroupAccess `json:"groupPermissions"`
	// AllUsers and AllGroups are every account and every group there is, for
	// choosing among, when they were asked for
	AllUsers  []string `json:"users"`
	AllGroups []string `json:"groups"`
}

Access is who may do what in one section of the server - Zones, Settings, Logs and the rest - or, with SubItem, with one zone.

type AccessChange

type AccessChange struct {
	Users  []UserAccess
	Groups []GroupAccess
}

AccessChange is who may do what from now on. Each list given replaces the one there is, whole: nil leaves one as it is.

type App

type App struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	// Parts are what the app adds to the server, each by its class
	Parts []struct {
		ClassPath string `json:"classPath"`
		// IsQueryLogger is the part being given every query to log, and
		// IsQueryLogs its log being one that can be searched
		IsQueryLogger bool `json:"isQueryLogger"`
		IsQueryLogs   bool `json:"isQueryLogs"`
	} `json:"dnsApps"`
}

App is a DNS app installed on the server.

func (*App) LogsQueries

func (a *App) LogsQueries() bool

LogsQueries reports whether the app keeps a log of queries that can be searched.

func (*App) QueryLog

func (a *App) QueryLog() (classPath string, ok bool)

QueryLog is the class of the app's part that keeps a searchable log of queries, which a search of the log names it by; false for an app with none.

type BackupItems

type BackupItems struct {
	// AuthConfig is the accounts, groups, permissions and tokens
	AuthConfig bool
	// ClusterConfig is the server's place in a cluster
	ClusterConfig bool
	// WebServiceSettings is how the console is served
	WebServiceSettings bool
	// DNSSettings is the DNS settings, with the certificates kept in the
	// server's own folder
	DNSSettings bool
	LogSettings bool
	Zones       bool
	// AllowedZones and BlockedZones are the server's own two lists, and
	// BlockLists what it has fetched of the lists it follows
	AllowedZones bool
	BlockedZones bool
	BlockLists   bool
	Apps         bool
	// Scopes is the DHCP scopes with their leases
	Scopes bool
	Stats  bool
	Logs   bool
}

BackupItems are the parts of a server a backup can hold, and a restore can put back.

func Everything

func Everything() BackupItems

Everything is every part of a server a backup can hold.

type Block

type Block struct {
	// Source is where the entry is: BlockedZone for the server's own list
	// of blocked names, BlockList for a list it fetches, and for anything
	// else - an app's - the server's own word
	Source string
	// List is the address of the list the entry is on, for a fetched one
	List string
	// Entry is the name that is blocked: the name asked for, or one above it
	Entry string
	// Text is the whole of what the server said
	Text string
}

Block is why a name server refused a name, as its answer says: a Technitium server says which of its lists the name is on.

type Cached

type Cached struct {
	// Domain is the name the answer is for. Asked for a name it holds
	// nothing at, the server answers for the nearest name below it that it
	// does, so this is not always the name asked for
	Domain string `json:"domain"`
	// Zones are the names directly under Domain that hold something
	Zones   []string       `json:"zones"`
	Records []CachedRecord `json:"records"`
}

Cached is what a server's cache holds at a name: the answers it keeps for the name itself, and the names under it that it holds something for.

type CachedRecord

type CachedRecord struct {
	Name string `json:"name"`
	Type string `json:"type"`
	// TTLText is how long the answer is kept for yet, with its length in
	// words: 283 (4 mins 43 sec)
	TTLText string `json:"ttl"`
	// Data is the record's data, laid out as a zone's record's is; a
	// negative answer has its own two fields (see Negative)
	Data RData `json:"rData"`
	// Source is the name server the answer came from
	Source struct {
		NameServer string `json:"nameServer"`
	} `json:"responseMetadata"`
	LastUsedOn string `json:"lastUsedOn"`
}

CachedRecord is one answer a server is keeping.

func (*CachedRecord) Negative

func (r *CachedRecord) Negative() (string, bool)

Negative is what a negative answer says - that the name does not exist, or has no record of the type - and false for a record that is an answer.

func (*CachedRecord) TTL

func (r *CachedRecord) TTL() int

TTL is how many seconds the answer is kept for yet.

func (*CachedRecord) Used

func (r *CachedRecord) Used() (time.Time, bool)

Used is when the answer was last given to a client.

func (*CachedRecord) Value

func (r *CachedRecord) Value() string

Value is the record's data on one line, as a zone's record's is written; for a negative answer, what it says.

type Client

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

Client talks to one Technitium DNS server.

func New

func New(baseURL, token string, opts ...Option) (*Client, error)

New returns a client for the server whose web console answers at baseURL, http://nas:5380 say, authenticating with an API token (web console, Administration, Sessions, Create Token). The token is sent as a bearer header and never in an address.

func (*Client) AddRecord

func (c *Client) AddRecord(ctx context.Context, rec NewRecord) (*Record, error)

AddRecord adds a record to a zone and returns it as the server now holds it.

func (*Client) AddReservation

func (c *Client) AddReservation(ctx context.Context, scope string, r Reservation) error

AddReservation has a scope keep an address for one machine. The server takes nearly anything: an address outside the scope, one another machine has reserved or holds. Only a second reservation for the same machine in the scope is refused.

func (*Client) AddSigningKey

func (c *Client) AddSigningKey(ctx context.Context, zone string, key NewSigningKey) error

AddSigningKey adds a private key to a signed zone. It is only generated: PublishSigningKeys puts it in the zone.

func (*Client) AdmitSecondaryNode

func (c *Client) AdmitSecondaryNode(ctx context.Context, node SecondaryNode) (*Cluster, error)

AdmitSecondaryNode is a server asking the primary to let it into the cluster as a secondary node.

func (*Client) AllSettings

func (c *Client) AllSettings(ctx context.Context) (map[string]any, error)

AllSettings reads every setting the server has, each under the name the API gives it, where Settings reads the part this client knows by type. What is secret is left out: no password, and no key's shared secret.

func (*Client) AllowName

func (c *Client) AllowName(ctx context.Context, name string) error

AllowName adds a name to the server's list of allowed names. A name already on it is no error.

func (*Client) AllowedAbove

func (c *Client) AllowedAbove(ctx context.Context, name string) (*Listed, error)

AllowedAbove is BlockedAbove for the server's list of allowed names.

func (*Client) AllowedNames

func (c *Client) AllowedNames(ctx context.Context) ([]string, error)

AllowedNames lists every name on the server's list of allowed names.

func (*Client) AllowedUnder

func (c *Client) AllowedUnder(ctx context.Context, name string) (*Listed, error)

AllowedUnder is BlockedUnder for the server's list of allowed names.

func (*Client) AppConfig

func (c *Client) AppConfig(ctx context.Context, name string) (string, error)

AppConfig reads an installed app's configuration, which is text of the app's own kind - JSON, for most; "" for an app that has none.

func (*Client) Apps

func (c *Client) Apps(ctx context.Context) ([]App, error)

Apps lists the DNS apps installed on the server.

func (*Client) Backup

func (c *Client) Backup(ctx context.Context, items BackupItems) ([]byte, error)

Backup reads the parts of the server asked for as one zip file. A backup with the accounts, the settings or the zones in it holds what is secret on the server - password hashes, tokens, keys - and is kept as carefully.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL is the address the client was made with, without a trailing slash.

func (*Client) BlockName

func (c *Client) BlockName(ctx context.Context, name string) error

BlockName adds a name to the server's own list of blocked names. A name already on it is no error.

func (*Client) BlockedAbove

func (c *Client) BlockedAbove(ctx context.Context, name string) (*Listed, error)

BlockedAbove is BlockedUnder walking the other way. It differs for a name that only leads on: nothing is listed at it and one name is under it. BlockedUnder answers for the first name below such a one that is listed or branches, and this for the nearest above. A name that is listed, or branches, or that the list knows nothing of, is answered for itself either way.

func (*Client) BlockedNames

func (c *Client) BlockedNames(ctx context.Context) ([]string, error)

BlockedNames lists every name on the server's own list of blocked names: the ones added by hand, not those of the block lists it fetches.

func (*Client) BlockedUnder

func (c *Client) BlockedUnder(ctx context.Context, name string) (*Listed, error)

BlockedUnder reads the server's own list of blocked names as a tree: the names under a name that are blocked or lead to blocked names, and whether the name is blocked itself. "" is the root.

func (*Client) Cache

func (c *Client) Cache(ctx context.Context, name string) (*Cached, error)

Cache reads what the server's cache holds at a name: "" is the top.

func (*Client) CacheAbove

func (c *Client) CacheAbove(ctx context.Context, name string) (*Cached, error)

CacheAbove is Cache walking the other way: asked for a name that only leads on, with nothing kept at it and one name under it, the answer is for the nearest name above that keeps something or branches, where Cache answers for the first below. Any other name is answered for itself either way.

func (*Client) CatalogZones

func (c *Client) CatalogZones(ctx context.Context) ([]string, error)

CatalogZones lists the catalog zones the server holds, by name.

func (*Client) ChangePassword

func (c *Client) ChangePassword(ctx context.Context, current, replacement, totp string, iterations int) error

ChangePassword changes the password of the account the client is signed in as (see Login), given the one it has, and its one-time code when it has a second factor. Iterations is how many rounds the new one is hashed with where it is kept, 0 for the server's own 100000.

func (*Client) CheckForUpdate

func (c *Client) CheckForUpdate(ctx context.Context) (*Update, error)

CheckForUpdate asks the server whether a newer version of itself is out, which it answers by asking its maker's site.

func (*Client) CloneZone

func (c *Client) CloneZone(ctx context.Context, zone, source string) error

CloneZone makes a zone that is another's copy at the time: every record the source has, under the new name.

func (*Client) ClusterState

func (c *Client) ClusterState(ctx context.Context) (*Cluster, error)

ClusterState reads how the server stands in a cluster: whether it is in one, and every node as this one sees it.

func (*Client) ConvertToNSEC

func (c *Client) ConvertToNSEC(ctx context.Context, zone string) error

ConvertToNSEC has a signed zone prove a name is not in it with NSEC, where it used NSEC3.

func (*Client) ConvertToNSEC3

func (c *Client) ConvertToNSEC3(ctx context.Context, zone string) error

ConvertToNSEC3 has a signed zone prove a name is not in it with NSEC3, where it used NSEC.

func (*Client) ConvertZone

func (c *Client) ConvertZone(ctx context.Context, zone, toType string) error

ConvertZone changes what type a zone is: a secondary into a primary, a primary into a forwarder, and the other conversions the server allows.

func (*Client) CreateGroup

func (c *Client) CreateGroup(ctx context.Context, name, description string) (*Group, error)

CreateGroup makes a group with nobody in it.

func (*Client) CreateSSOUser

func (c *Client) CreateSSOUser(ctx context.Context, user NewSSOUser) (*User, error)

CreateSSOUser makes an account for someone who signs in through the provider. It is the call one node of a cluster makes of another, and the server takes it only under the cluster's own token: an administrator's is refused.

func (*Client) CreateToken

func (c *Client) CreateToken(ctx context.Context, name string) (string, error)

CreateToken makes an API token for the account the client is signed in as (see Login), under a name that says what it is for. A token does not expire and may do whatever its account may, so it is given to whatever will use it and kept nowhere else: the server never shows it again.

func (*Client) CreateTokenAs

func (c *Client) CreateTokenAs(ctx context.Context, user, name string) (string, error)

CreateTokenAs makes an API token for any account, which only an administrator may: the token acts as that account and does not expire. It is given to whatever will use it and kept nowhere else, since the server never shows it again.

func (*Client) CreateTokenFor

func (c *Client) CreateTokenFor(ctx context.Context, user, pass, totp, name string) (string, error)

CreateTokenFor is CreateToken with an account's name and password in place of a session, and its one-time code when it has a second factor.

func (*Client) CreateUser

func (c *Client) CreateUser(ctx context.Context, user NewUser) (*User, error)

CreateUser makes an account, which is in no group but Everyone until SetUser puts it in one.

func (*Client) CreateZone

func (c *Client) CreateZone(ctx context.Context, zone NewZone) (string, error)

CreateZone creates an authoritative zone and returns the name the server gave it, which for a reverse zone made from an address is not the name asked for.

func (*Client) DNSSEC

func (c *Client) DNSSEC(ctx context.Context, zone string) (*DNSSEC, error)

DNSSEC reads how a signed primary zone is signed, and its keys.

func (*Client) DSInfo

func (c *Client) DSInfo(ctx context.Context, zone string) (*DSInfo, error)

DSInfo reads the DS records a signed primary zone's parent is to hold.

func (*Client) DeleteAddress

func (c *Client) DeleteAddress(ctx context.Context, zone string, rec *Record) error

DeleteAddress is DeleteRecord for an A or an AAAA record, which also has the server bring the address hints of the zone's SVCB and HTTPS records that name the record's name, and are set to keep their hints themselves, up to date with the address gone.

func (*Client) DeleteAllLogs

func (c *Client) DeleteAllLogs(ctx context.Context) error

DeleteAllLogs deletes every log file the server has for good.

func (*Client) DeleteAllStats

func (c *Client) DeleteAllStats(ctx context.Context) error

DeleteAllStats deletes every statistic the server keeps, from its disk and from memory: the dashboard starts again from nothing.

func (*Client) DeleteCached

func (c *Client) DeleteCached(ctx context.Context, name string) error

DeleteCached drops what the server's cache holds at a name and at every name under it, so the next query for one is resolved afresh.

func (*Client) DeleteCluster

func (c *Client) DeleteCluster(ctx context.Context, force bool) (*Cluster, error)

DeleteCluster takes the cluster off its primary node, which is asked of the primary. Nothing but the cluster's own configuration is lost. The server allows it only when no secondary node is left, unless forced: then the secondaries are orphaned, and one of them has to be promoted by hand.

func (*Client) DeleteGroup

func (c *Client) DeleteGroup(ctx context.Context, name string) error

DeleteGroup deletes a group, and with it what its members were allowed as members of it.

func (*Client) DeleteLog

func (c *Client) DeleteLog(ctx context.Context, fileName string) error

DeleteLog deletes one of the server's log files for good.

func (*Client) DeleteRecord

func (c *Client) DeleteRecord(ctx context.Context, zone string, rec *Record) error

DeleteRecord deletes one record from a zone: the one at the name with the type and the data given. zone "" is the closest the server holds for the name.

func (*Client) DeleteScope

func (c *Client) DeleteScope(ctx context.Context, name string) error

DeleteScope deletes a scope, with its reservations and the record of its leases.

func (*Client) DeleteSecondaryNode

func (c *Client) DeleteSecondaryNode(ctx context.Context, id int64) (*Cluster, error)

DeleteSecondaryNode has the primary drop a secondary node from the cluster at once, without asking it to leave: for a node that is gone.

func (*Client) DeleteSession

func (c *Client) DeleteSession(ctx context.Context, partialToken string) error

DeleteSession ends anyone's session, or deletes an API token, by the part of its token Sessions gives it under.

func (*Client) DeleteSigningKey

func (c *Client) DeleteSigningKey(ctx context.Context, zone string, keyTag int) error

DeleteSigningKey deletes a private key that was only generated: one that has been published is retired instead.

func (*Client) DeleteTSIGKey

func (c *Client) DeleteTSIGKey(ctx context.Context, name string) error

DeleteTSIGKey takes a transfer key off the server, leaving every other as it is. A key that is not there is no error; one a zone still uses the server refuses to lose.

func (*Client) DeleteUser

func (c *Client) DeleteUser(ctx context.Context, name string) error

DeleteUser deletes an account, and with it its sessions and its tokens.

func (*Client) DeleteZone

func (c *Client) DeleteZone(ctx context.Context, zone string) error

DeleteZone deletes an authoritative zone and every record in it.

func (*Client) DeleteZones

func (c *Client) DeleteZones(ctx context.Context, zones []string) error

DeleteZones deletes several zones in one call, each with every record in it. The server stops at the first it cannot delete, with the ones before it gone.

func (*Client) DisableScope

func (c *Client) DisableScope(ctx context.Context, name string) error

DisableScope switches a scope off: it leases nothing, and keeps its reservations and what it has leased.

func (*Client) DisableTwoFactor

func (c *Client) DisableTwoFactor(ctx context.Context) error

DisableTwoFactor takes the second factor off the account the client is signed in as (see Login).

func (*Client) DisableZone

func (c *Client) DisableZone(ctx context.Context, zone string) error

DisableZone switches a zone off: the server keeps it and answers nothing from it.

func (*Client) DownloadLog

func (c *Client) DownloadLog(ctx context.Context, fileName string, limitMB int) (string, error)

DownloadLog reads one of the server's log files, by the name LogFiles gives it: the whole file, or with limitMB its first so many megabytes.

func (*Client) EnableScope

func (c *Client) EnableScope(ctx context.Context, name string) error

EnableScope switches a scope on, so that it leases.

func (*Client) EnableTwoFactor

func (c *Client) EnableTwoFactor(ctx context.Context, code string) error

EnableTwoFactor switches the second factor on with a code made from the secret InitTwoFactor gave: from then on signing in takes a code too.

func (*Client) EnableZone

func (c *Client) EnableZone(ctx context.Context, zone string) error

EnableZone switches a zone back on.

func (*Client) EndSession

func (c *Client) EndSession(ctx context.Context, partialToken string) error

EndSession ends another session of the client's own account, or one of its API tokens, by the part of its token the profile gives it under.

func (*Client) ExportQueryLog

func (c *Client) ExportQueryLog(ctx context.Context, q LogQuery) (string, error)

ExportQueryLog is a search of an app's log of queries as a CSV file: every entry that matched, a line each under a line of headings, where QueryLog gives a page of them. Its paging and its order are not asked for.

func (*Client) ExportZone

func (c *Client) ExportZone(ctx context.Context, zone string) (string, error)

ExportZone is a zone whole as a zone file: every record a line, with the comment a record has after a semicolon.

func (*Client) FlushAllowed

func (c *Client) FlushAllowed(ctx context.Context) error

FlushAllowed empties the server's list of allowed names.

func (*Client) FlushBlocked

func (c *Client) FlushBlocked(ctx context.Context) error

FlushBlocked empties the server's own list of blocked names. The block lists it fetches are not touched.

func (*Client) FlushCache

func (c *Client) FlushCache(ctx context.Context) error

FlushCache drops everything the server's cache holds.

func (*Client) Group

func (c *Client) Group(ctx context.Context, name string, withUsers bool) (*Group, error)

Group reads one group and its members. With withUsers it also lists every account there is.

func (*Client) Groups

func (c *Client) Groups(ctx context.Context) ([]Group, error)

Groups lists the groups on the server, each without its members.

func (*Client) HealthCheck

func (c *Client) HealthCheck(ctx context.Context, name, recordType string) error

HealthCheck asks the server to resolve a name for itself, which answers whether it is running and can resolve at all; nothing of it is written to the log of queries. "" asks for localhost, and no type for an A record.

func (*Client) ImportAllowed

func (c *Client) ImportAllowed(ctx context.Context, names []string) error

ImportAllowed adds many names to the server's list of allowed names in one call.

func (*Client) ImportBlocked

func (c *Client) ImportBlocked(ctx context.Context, names []string) error

ImportBlocked adds many names to the server's own list of blocked names in one call. Names already on it are no error.

func (*Client) ImportResolved

func (c *Client) ImportResolved(ctx context.Context, q ResolveQuery) (*Resolution, error)

ImportResolved asks a question as Resolve does and writes the records of the answer into a zone of the server's own: the closest primary or forwarder zone it holds for the name, or a new primary zone made for it. It is how a zone held elsewhere is copied in a record set at a time, and it changes the server where Resolve only asks.

func (*Client) ImportZone

func (c *Client) ImportZone(ctx context.Context, zone, zoneFile string, how ZoneImport) error

ImportZone adds the records of a zone file, as ExportZone gives one, to a zone the server holds.

func (*Client) InitCluster

func (c *Client) InitCluster(ctx context.Context, domain string, addresses []string) (*Cluster, error)

InitCluster makes the server the primary node of a new cluster under the domain given, reached by the other nodes at the addresses given. The server renames itself under the cluster's domain, turns HTTPS on for its console if it was off - which takes it a moment, during which no node can join - and makes the cluster's two zones. The cluster's domain cannot be changed afterwards.

func (*Client) InitTwoFactor

func (c *Client) InitTwoFactor(ctx context.Context) (*TwoFactorSetup, error)

InitTwoFactor begins giving the account the client is signed in as (see Login) a second factor: the server makes a secret, and EnableTwoFactor switches it on once an app is making codes from it.

func (*Client) InstallApp

func (c *Client) InstallApp(ctx context.Context, name string, zip []byte) (*App, error)

InstallApp installs an app from its zip file under a name.

func (*Client) InstallAppFrom

func (c *Client) InstallAppFrom(ctx context.Context, name, from string) (*App, error)

InstallAppFrom has the server fetch an app's zip file from an address, as StoreApps gives one, and install it under a name.

func (*Client) JoinCluster

func (c *Client) JoinCluster(ctx context.Context, join ClusterJoin) (*Cluster, error)

JoinCluster makes the server a secondary node of the cluster whose primary is named. Its settings, apps, allowed and blocked lists, and its accounts and their tokens are written over with the primary's: the token this client holds stops working, and one of the primary's works here instead.

func (*Client) Leases

func (c *Client) Leases(ctx context.Context) ([]Lease, error)

Leases lists the addresses machines hold now, in every scope.

func (*Client) LeaveCluster

func (c *Client) LeaveCluster(ctx context.Context, force bool) (*Cluster, error)

LeaveCluster takes a secondary node out of its cluster, which is asked of the secondary. Nothing but the cluster's own configuration is lost. Forced, it leaves without telling the primary, which is for a primary that is gone.

func (*Client) LogFiles

func (c *Client) LogFiles(ctx context.Context) ([]LogFile, error)

LogFiles lists the server's log files, newest first.

func (*Client) Login

func (c *Client) Login(ctx context.Context, user, pass, totp string) (*Client, *SignedIn, error)

Login signs in to the server with an account's name and password, and its one-time code when it has a second factor, and returns a client that works under the session that opened. The session ends when nothing has used it for the account's timeout, half an hour unless it was changed, or at Logout.

A session is what a handful of calls about the account itself ask for, where an API token is refused: ChangePassword, SetProfile, the calls about a second factor, and CreateToken.

func (*Client) Logout

func (c *Client) Logout(ctx context.Context) error

Logout ends the session the client works under, after which its token is refused. For a client made with an API token that is the token itself, deleted for good.

func (*Client) Metrics

func (c *Client) Metrics(ctx context.Context) (*Metrics, error)

Metrics reads what the server has counted since it started.

func (*Client) MetricsText

func (c *Client) MetricsText(ctx context.Context) (string, error)

MetricsText is Metrics as Prometheus reads them: a text of counters, one a line.

func (*Client) Node

func (c *Client) Node() string

Node is the node the client's calls are passed on to, "" for the server itself.

func (*Client) NotifySecondary

func (c *Client) NotifySecondary(ctx context.Context, primaryID int64, primaryURL string, addresses []string) error

NotifySecondary is the primary telling a secondary node that the configuration has changed, and where the primary is.

func (*Client) OnNode

func (c *Client) OnNode(domain string) *Client

OnNode is this client with its calls passed on to another node of the cluster the server is in, named by the node's domain: the server asked answers for that node. Only the calls the API passes on take it (see nodeCalls); any other fails without being sent, since it would be answered by the wrong server. "" is the server itself again.

func (*Client) PauseBlocking

func (c *Client) PauseBlocking(ctx context.Context, minutes int) (string, error)

PauseBlocking switches the server's blocking off for some minutes, after which it comes back on by itself, and returns when that is.

func (*Client) Permissions

func (c *Client) Permissions(ctx context.Context) ([]Access, error)

Permissions lists who may do what in every section of the server.

func (*Client) Profile

func (c *Client) Profile(ctx context.Context) (*Profile, error)

Profile reads the account the client's token belongs to.

func (*Client) PromoteToPrimary

func (c *Client) PromoteToPrimary(ctx context.Context, forceDeletePrimary bool) (*Cluster, error)

PromoteToPrimary makes a secondary node the cluster's primary, which is asked of the secondary: it fetches the whole configuration from the primary there is, has it leave the cluster, and takes its place. Forced, the old primary is dropped without being asked, which is for one that is gone. It can take a while.

func (*Client) PublishSigningKeys

func (c *Client) PublishSigningKeys(ctx context.Context, zone string) error

PublishSigningKeys puts every key that was only generated into the zone as a DNSKEY record, after which the server brings each into use by itself. A key signing key waits at Ready for its DS record to be at the zone's parent.

func (*Client) QueryLog

func (c *Client) QueryLog(ctx context.Context, q LogQuery) (*LogPage, error)

QueryLog searches an app's log of queries and returns one page of what matched, with how many matched in all.

func (*Client) RecordsAt

func (c *Client) RecordsAt(ctx context.Context, name, zone string) (*ZoneRecords, error)

RecordsAt reads the records at one domain name, in the zone named or, with none named, in the closest zone the server holds for it.

func (*Client) RemoveLease

func (c *Client) RemoveLease(ctx context.Context, scope, hardwareAddress string) error

RemoveLease has a scope forget the lease a machine holds. A lease that was reserved takes its reservation with it.

func (*Client) RemoveLeaseOfClient

func (c *Client) RemoveLeaseOfClient(ctx context.Context, scope, clientIdentifier string) error

RemoveLeaseOfClient is RemoveLease for a lease named by its client identifier.

func (*Client) RemoveReservation

func (c *Client) RemoveReservation(ctx context.Context, scope, hardwareAddress string) error

RemoveReservation has a scope keep no address for a machine any more.

func (*Client) RemoveSecondaryNode

func (c *Client) RemoveSecondaryNode(ctx context.Context, id int64) (*Cluster, error)

RemoveSecondaryNode has the primary ask a secondary node to leave the cluster, as if LeaveCluster had been asked of that node.

func (*Client) ReserveLease

func (c *Client) ReserveLease(ctx context.Context, scope, hardwareAddress string) error

ReserveLease turns the lease a machine holds into a reservation: the address it has now is the one it keeps.

func (*Client) ReserveLeaseOfClient

func (c *Client) ReserveLeaseOfClient(ctx context.Context, scope, clientIdentifier string) error

ReserveLeaseOfClient is ReserveLease for a lease named by its client identifier.

func (*Client) Resolve

func (c *Client) Resolve(ctx context.Context, q ResolveQuery) (*Resolution, error)

Resolve has the server put a query to a name server - itself, by default - and returns the answer: what a client of the server would be told. A name that does not exist is an answer, with its RCode, and no error.

func (*Client) Restore

func (c *Client) Restore(ctx context.Context, items BackupItems, deleteExisting bool, zip []byte) (*Settings, error)

Restore puts the parts asked for back from a backup's zip file, writing over what the server has of them, and returns the settings as they now stand. With deleteExisting, what the server has of a part and the backup has not is deleted too. Restoring the accounts can end the session the client works under.

func (*Client) ResyncCluster

func (c *Client) ResyncCluster(ctx context.Context) error

ResyncCluster has a secondary node fetch the whole configuration from the primary again, which is asked of the secondary.

func (*Client) ResyncZone

func (c *Client) ResyncZone(ctx context.Context, zone string) error

ResyncZone has a copy of a zone - a Secondary or a Stub - transfer from its primary again now rather than when it is next due. It answers at once: the transfer is made after.

func (*Client) RetireDNSKey

func (c *Client) RetireDNSKey(ctx context.Context, zone string, keyTag int) error

RetireDNSKey retires one of a signed zone's keys and takes it out of the zone once that is safe, which needs another key of its kind in use.

func (*Client) RolloverDNSKey

func (c *Client) RolloverDNSKey(ctx context.Context, zone string, keyTag int) error

RolloverDNSKey replaces one of a signed zone's keys: a new one is made and published, and the old one retired once the new is in use.

func (*Client) SSO

func (c *Client) SSO(ctx context.Context, withGroups bool) (*SSO, error)

SSO reads how the server is set up for single sign-on. With withGroups it also lists the groups here.

func (*Client) Scope

func (c *Client) Scope(ctx context.Context, name string) (*ScopeDetails, error)

Scope reads one scope whole.

func (*Client) Scopes

func (c *Client) Scopes(ctx context.Context) ([]Scope, error)

Scopes lists the server's DHCP scopes.

func (*Client) SectionPermissions

func (c *Client) SectionPermissions(ctx context.Context, section string, withNames bool) (*Access, error)

SectionPermissions reads who may do what in one section. With withNames it also lists every account and group there is.

func (*Client) Session

func (c *Client) Session(ctx context.Context) (*Session, error)

Session reads the session the client's token belongs to: who it acts as, what that account may do, and the server's version and name.

func (*Client) Sessions

func (c *Client) Sessions(ctx context.Context) ([]OpenSession, error)

Sessions lists who is signed in to the server and the API tokens made on it, which only an administrator may read.

func (*Client) SetAppConfig

func (c *Client) SetAppConfig(ctx context.Context, name, config string) error

SetAppConfig writes an installed app's configuration, which is text of the app's own kind - JSON, for most - and takes effect at once.

func (*Client) SetBlockLists

func (c *Client) SetBlockLists(ctx context.Context, addresses []string) (*Settings, error)

SetBlockLists sets the lists the server fetches to the ones at these addresses, and to none when there are none; an address with a ! before it is a list of names to allow. Nothing else of the settings is changed.

func (*Client) SetBlocking

func (c *Client) SetBlocking(ctx context.Context, on bool) (*Settings, error)

SetBlocking switches the server's blocking on or off, and returns its settings as they then stand. Switched on, a pause is over.

func (*Client) SetClusterOptions

func (c *Client) SetClusterOptions(ctx context.Context, options ClusterOptions) (*Cluster, error)

SetClusterOptions sets a cluster's options, which is asked of its primary and holds for every node.

func (*Client) SetGroup

func (c *Client) SetGroup(ctx context.Context, name string, change GroupChange) (*Group, error)

SetGroup changes a group, and returns it as it now stands.

func (*Client) SetProfile

func (c *Client) SetProfile(ctx context.Context, change ProfileChange) (*Profile, error)

SetProfile changes the profile of the account the client is signed in as (see Login), and returns it as it now stands.

func (*Client) SetSSO

func (c *Client) SetSSO(ctx context.Context, change SSOChange) (*SSO, error)

SetSSO changes how the server is set up for single sign-on, and returns it as it now stands. The server restarts its web console when the change needs it, and for that moment answers nothing.

func (*Client) SetSSOUser

func (c *Client) SetSSOUser(ctx context.Context, name string, change SSOUserChange) (*User, error)

SetSSOUser changes a single sign-on account. Like CreateSSOUser it is a call between the nodes of a cluster, taken only under the cluster's own token.

func (*Client) SetScope

func (c *Client) SetScope(ctx context.Context, scope *NewScope) error

SetScope makes a scope, or sets the one of its name to this: what is left out here an existing scope keeps, its reservations among it. A scope made so is enabled at once.

func (*Client) SetSectionPermissions

func (c *Client) SetSectionPermissions(ctx context.Context, section string, change AccessChange) (*Access, error)

SetSectionPermissions sets who may do what in one section, and returns the permissions as they now stand.

func (*Client) SetSettings

func (c *Client) SetSettings(ctx context.Context, values map[string]string) (map[string]any, error)

SetSettings sets settings by name, each to a value written as the API takes it - true or false, a number, a list with commas between, a table with bars - and returns every setting as it now stands, without what is secret. Only the settings given change. A name the API does not know is refused here, since the server passes one over without a word.

A server passes over a setting a later version brought the same way. That is an error here once it has answered, and the settings come back with it: whatever else was sent in the same call is set.

Some settings restart the server's console or its DNS service when they change, and for that moment it answers nothing.

func (*Client) SetTSIGKey

func (c *Client) SetTSIGKey(ctx context.Context, name, sharedSecret, algorithm string) error

SetTSIGKey adds a transfer key to the server, or changes the one there is under the name, leaving every other key as it is. The shared secret is base64, as the two ends of a transfer are both given it; with none the server makes one up, which only this server then has. The algorithm is hmac-sha256 unless another is named.

func (*Client) SetUser

func (c *Client) SetUser(ctx context.Context, name string, change UserChange) (*User, error)

SetUser changes an account, and returns it as it now stands.

func (*Client) SetZoneOptions

func (c *Client) SetZoneOptions(ctx context.Context, zone string, change ZoneChange) error

SetZoneOptions sets options of a zone, leaving every other as it is.

func (*Client) SetZonePermissions

func (c *Client) SetZonePermissions(ctx context.Context, zone string, change AccessChange) (*Access, error)

SetZonePermissions sets who may do what with one zone, and returns the permissions as they now stand.

func (*Client) Settings

func (c *Client) Settings(ctx context.Context) (*Settings, error)

Settings reads how the server is set up.

func (*Client) SignZone

func (c *Client) SignZone(ctx context.Context, zone string, how Signing) error

SignZone signs a primary zone with DNSSEC. The zone is not trusted by anyone until its DS record (see DSInfo) is at its parent.

func (*Client) SingleUseToken

func (c *Client) SingleUseToken(ctx context.Context) (string, error)

SingleUseToken makes a token for the account the client is signed in as (see Login) that works for one call and then is gone.

func (*Client) Stats

func (c *Client) Stats(ctx context.Context, window StatsWindow) (*Stats, error)

Stats reads what the server did over a window.

func (*Client) Status

func (c *Client) Status(ctx context.Context) (*Status, error)

Status asks whether the API is there, which needs no token to answer.

func (*Client) StoreApps

func (c *Client) StoreApps(ctx context.Context) ([]StoreApp, error)

StoreApps lists the apps the server's maker offers, which the server answers by asking its maker's site.

func (*Client) TSIGKeyNames

func (c *Client) TSIGKeyNames(ctx context.Context) ([]string, error)

TSIGKeyNames lists the transfer keys the server has, by name.

func (*Client) TopStats

func (c *Client) TopStats(ctx context.Context, window StatsWindow, list string, limit int) (*Stats, error)

TopStats reads one of the server's lists for a window - TopClients, TopDomains or TopBlockedDomains - to as many entries as asked for.

func (*Client) TransferConfig

func (c *Client) TransferConfig(ctx context.Context, includeZones []string) ([]byte, error)

TransferConfig is a secondary node fetching the cluster's configuration from the primary: a zip file of it, with the DNSSEC private keys of the zones named.

func (*Client) UnallowName

func (c *Client) UnallowName(ctx context.Context, name string) error

UnallowName takes a name off the server's list of allowed names. A name that is not on it is no error.

func (*Client) UnblockName

func (c *Client) UnblockName(ctx context.Context, name string) error

UnblockName takes a name off the server's own list of blocked names. A name that is not on it is no error.

func (*Client) UninstallApp

func (c *Client) UninstallApp(ctx context.Context, name string) error

UninstallApp takes an app off the server. Records that were answered by the app stay in their zones and answer nothing.

func (*Client) UnreserveLease

func (c *Client) UnreserveLease(ctx context.Context, scope, hardwareAddress string) error

UnreserveLease turns a reserved lease back into an ordinary one, which ends when its time is up; the reservation goes with it.

func (*Client) UnreserveLeaseOfClient

func (c *Client) UnreserveLeaseOfClient(ctx context.Context, scope, clientIdentifier string) error

UnreserveLeaseOfClient is UnreserveLease for a lease named by its client identifier.

func (*Client) UnsignZone

func (c *Client) UnsignZone(ctx context.Context, zone string) error

UnsignZone takes DNSSEC off a primary zone. A zone whose DS record is still at its parent stops resolving for everyone who validates.

func (*Client) UpdateApp

func (c *Client) UpdateApp(ctx context.Context, name string, zip []byte) (*App, error)

UpdateApp puts an app's zip file in place of the app installed under a name, keeping its configuration.

func (*Client) UpdateAppFrom

func (c *Client) UpdateAppFrom(ctx context.Context, name, from string) (*App, error)

UpdateAppFrom has the server fetch an app's zip file from an address and put it in place of the app installed under a name, keeping its configuration.

func (*Client) UpdateBlockLists

func (c *Client) UpdateBlockLists(ctx context.Context) error

UpdateBlockLists has the server fetch its block lists now rather than when they are next due. It answers at once: the lists are fetched after.

func (*Client) UpdateDNSKeyTTL

func (c *Client) UpdateDNSKeyTTL(ctx context.Context, zone string, ttl int) error

UpdateDNSKeyTTL sets the TTL of a signed zone's DNSKEY records, which the server allows only while every key is ready or active.

func (*Client) UpdateNSEC3Params

func (c *Client) UpdateNSEC3Params(ctx context.Context, zone string, iterations, saltLength int) error

UpdateNSEC3Params sets how many times a signed zone's NSEC3 hashes a name and how long its salt is, in bytes.

func (*Client) UpdateNodeAddresses

func (c *Client) UpdateNodeAddresses(ctx context.Context, addresses []string) (*Cluster, error)

UpdateNodeAddresses sets the addresses the other nodes of the cluster reach this node at.

func (*Client) UpdatePrimaryNode

func (c *Client) UpdatePrimaryNode(ctx context.Context, primaryURL string, addresses []string) (*Cluster, error)

UpdatePrimaryNode tells a secondary node where the cluster's primary is now, which is asked of the secondary: for a primary whose address changed while the secondary was away. With no addresses the name in the url is resolved.

func (*Client) UpdateRecord

func (c *Client) UpdateRecord(ctx context.Context, zone string, current *Record, want RecordUpdate) (*Record, error)

UpdateRecord changes one record in place - its data, its name, its TTL, its comment, whether it is disabled - and returns it as the server now holds it. current says which record: its name, type and data as they are. zone "" is the closest the server holds for the name.

A record the server does not hold is refused with an error about the zone, in the server's words: it is the record that is not there.

func (*Client) UpdateSOA

func (c *Client) UpdateSOA(ctx context.Context, zone string, current *Record, soa SOA) (*Record, error)

UpdateSOA sets what a zone's SOA record says: the primary it names, whose mailbox it gives, and its times. current is the record as it stands, whose TTL and comment are kept; the serial is the server's own to count, and is sent as it is.

func (*Client) UpdateSecondaryNode

func (c *Client) UpdateSecondaryNode(ctx context.Context, node SecondaryNode) (*Cluster, error)

UpdateSecondaryNode is a secondary node telling the primary its url, its addresses or its certificate have changed.

func (*Client) UpdateSigningKey

func (c *Client) UpdateSigningKey(ctx context.Context, zone string, keyTag, rolloverDays int) error

UpdateSigningKey sets how often one of a signed zone's keys is replaced by itself, in days: 0 to 365, where 0 is never.

func (*Client) User

func (c *Client) User(ctx context.Context, name string, withGroups bool) (*User, error)

User reads one account: its groups, its sessions and its tokens. With withGroups it also lists every group there is.

func (*Client) Users

func (c *Client) Users(ctx context.Context) ([]User, error)

Users lists the accounts on the server.

func (*Client) ZoneOptions

func (c *Client) ZoneOptions(ctx context.Context, zone string) (*ZoneOptions, error)

ZoneOptions reads how a zone is served and copied.

func (*Client) ZonePermissions

func (c *Client) ZonePermissions(ctx context.Context, zone string, withNames bool) (*Access, error)

ZonePermissions reads who may do what with one zone, which is beside what the Zones section allows everybody in it. With withNames it also lists every account and group there is.

func (*Client) ZoneRecords

func (c *Client) ZoneRecords(ctx context.Context, zone string) (*ZoneRecords, error)

ZoneRecords reads every record in a zone.

func (*Client) Zones

func (c *Client) Zones(ctx context.Context, filter ZoneFilter) ([]Zone, error)

Zones lists the authoritative zones the token's account may see, all of them in one answer.

func (*Client) ZonesPage

func (c *Client) ZonesPage(ctx context.Context, filter ZoneFilter, page, perPage int) (*ZonePage, error)

ZonesPage lists the zones a page at a time, for a server with more than are wanted in one answer: page counts from 1, and perPage 0 is the server's ten. Zones gives them all at once.

type Cluster

type Cluster struct {
	Initialized bool `json:"clusterInitialized"`
	// Domain is the cluster's own domain name, under which each node's is:
	// ns1.example.com in the cluster example.com
	Domain string `json:"clusterDomain"`
	// ServerDomain is the name of the server that was asked
	ServerDomain string `json:"dnsServerDomain"`
	Version      string `json:"version"`
	Nodes        []Node `json:"clusterNodes"`
	// how often the nodes look at each other and how often a secondary
	// fetches the primary's configuration, each with how soon it tries again
	// after failing, in seconds; and when this node last fetched it, in UTC
	HeartbeatRefreshIntervalSeconds int    `json:"heartbeatRefreshIntervalSeconds"`
	HeartbeatRetryIntervalSeconds   int    `json:"heartbeatRetryIntervalSeconds"`
	ConfigRefreshIntervalSeconds    int    `json:"configRefreshIntervalSeconds"`
	ConfigRetryIntervalSeconds      int    `json:"configRetryIntervalSeconds"`
	ConfigLastSynced                string `json:"configLastSynced"`
	// ServerIPAddresses are the addresses the server that was asked has
	ServerIPAddresses []string `json:"serverIpAddresses"`
}

Cluster is how a server stands in a cluster, or that it is in none.

func (*Cluster) Primary

func (c *Cluster) Primary() *Node

Primary is the cluster's primary node, nil for a server in no cluster.

func (*Cluster) Self

func (c *Cluster) Self() *Node

Self is the node that was asked, nil for a server in no cluster.

type ClusterJoin

type ClusterJoin struct {
	// Addresses are where the other nodes reach this server
	Addresses []string
	// PrimaryURL is the primary node's console over HTTPS, as its own
	// cluster state gives it: https://ns1.example.com:53443/
	PrimaryURL string
	// PrimaryAddress is the primary's address, for when its name does not
	// resolve from this server yet
	PrimaryAddress string
	// IgnoreCertificateErrors accepts the certificate the primary signed
	// for itself, which is what it has unless it was given a real one
	IgnoreCertificateErrors bool
	// Username and Password are an administrator's on the primary: joining
	// is asked of it as that account, and an API token will not do. TOTP is
	// its one-time code, when it has a second factor
	Username, Password, TOTP string
}

ClusterJoin is what a server needs to join a cluster as a secondary node.

type ClusterOptions

type ClusterOptions struct {
	// HeartbeatRefresh and HeartbeatRetry are 10 to 300
	HeartbeatRefreshIntervalSeconds, HeartbeatRetryIntervalSeconds int
	// ConfigRefresh and ConfigRetry are 30 to 3600
	ConfigRefreshIntervalSeconds, ConfigRetryIntervalSeconds int
}

ClusterOptions is how often the nodes of a cluster look at each other and fetch the primary's configuration, in seconds: 0 leaves one as it is.

type DNSSEC

type DNSSEC struct {
	Name         string       `json:"name"`
	Type         string       `json:"type"`
	Disabled     bool         `json:"disabled"`
	DNSSECStatus string       `json:"dnssecStatus"`
	DNSKeyTTL    int          `json:"dnsKeyTtl"`
	Keys         []SigningKey `json:"dnssecPrivateKeys"`
}

DNSSEC is how a primary zone is signed.

type DSInfo

type DSInfo struct {
	Name         string     `json:"name"`
	Type         string     `json:"type"`
	DNSSECStatus string     `json:"dnssecStatus"`
	DSRecords    []DSRecord `json:"dsRecords"`
}

DSInfo is a signed zone with what its parent needs.

type DSRecord

type DSRecord struct {
	KeyTag int `json:"keyTag"`
	// DNSKeyState is how far the key has come: Published, Ready, Active;
	// and DNSKeyStateReadyBy when a published one will be ready, in UTC
	DNSKeyState        string `json:"dnsKeyState"`
	DNSKeyStateReadyBy string `json:"dnsKeyStateReadyBy"`
	Algorithm          string `json:"algorithm"`
	PublicKey          string `json:"publicKey"`
	Digests            []struct {
		DigestType string `json:"digestType"`
		Digest     string `json:"digest"`
	} `json:"digests"`
}

DSRecord is what a signed zone's parent is given for one of its key signing keys.

type GenericOption

type GenericOption struct {
	Code  int    `json:"code"`
	Value string `json:"value"`
}

GenericOption is a DHCP option by its number, with its value as bytes in hex: for an option the server has no name for.

type Group

type Group struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Members are the accounts in the group, which a list of groups leaves
	// out, and Users every account there is, for choosing among, when they
	// were asked for
	Members []string `json:"members"`
	Users   []string `json:"users"`
}

Group is a group of accounts, which permissions are given to.

type GroupAccess

type GroupAccess struct {
	Name string `json:"name"`

	Permission
}

GroupAccess is what the members of one group may do with something.

type GroupChange

type GroupChange struct {
	// NewName renames the group
	NewName string
	// Description is what the group is for; nil leaves it, and "" clears it
	Description *string
	// Members are the accounts in the group from now on: nil leaves them as
	// they are
	Members []string
}

GroupChange is what to set of a group: whatever is left as it is here stays as it is on the server.

type GroupMapping

type GroupMapping struct {
	RemoteGroup string `json:"remoteGroup"`
	LocalGroup  string `json:"localGroup"`
}

GroupMapping is a group at the single sign-on provider and the group here its members are put in.

type KeyOptions

type KeyOptions struct {
	// Algorithm is RSA, ECDSA or EDDSA
	Algorithm string
	// HashAlgorithm is RSA's: MD5, SHA1, SHA256 or SHA512
	HashAlgorithm string
	Curve         string
}

KeyOptions is how a signing key is made. RSA takes a hash and a size, and the other two a curve: P256 or P384 for ECDSA, ED25519 or ED448 for EDDSA.

type Lease

type Lease struct {
	Scope string `json:"scope"`
	// Type is Dynamic for an address from the scope's range, and Reserved
	// for one kept for the machine
	Type             string `json:"type"`
	HardwareAddress  string `json:"hardwareAddress"`
	ClientIdentifier string `json:"clientIdentifier"`
	Address          string `json:"address"`
	HostName         string `json:"hostName"`
	LeaseObtained    string `json:"leaseObtained"`
	LeaseExpires     string `json:"leaseExpires"`
}

Lease is an address a machine holds now.

type Listed

type Listed struct {
	// Domain is the name the place is at. Asked for a name that only leads
	// on to one other, the server answers for the first name below it where
	// the tree branches or a listed name is, and says so here
	Domain string `json:"domain"`
	// Zones are the names below it that are listed or lead to a listed
	// name, each written whole
	Zones []string `json:"zones"`
	// Records are what the server answers with at the name when it is on
	// the list itself: an SOA and an NS of the server's own making
	Records []Record `json:"records"`
}

Listed is one place in the tree of names one of the server's two lists is kept as.

type LogEntry

type LogEntry struct {
	// Timestamp is when it was asked, in UTC
	Timestamp string `json:"timestamp"`
	Client    string `json:"clientIpAddress"`
	Protocol  string `json:"protocol"`
	// ResponseType is where the answer came from, and RCode how it went
	ResponseType string `json:"responseType"`
	RCode        string `json:"rcode"`
	// ResponseRTT is how long resolving it took, in milliseconds, for an
	// answer that was resolved; nil for one the server had
	ResponseRTT *float64 `json:"responseRtt"`
	Name        string   `json:"qname"`
	Type        string   `json:"qtype"`
	Class       string   `json:"qclass"`
	// Answer is what was answered, as text: A 10.0.0.4, or a chain as
	// CNAME emby.example.com., A 10.0.0.4; "" for an answer with no records
	Answer string `json:"answer"`
}

LogEntry is one query a server answered, as an app logged it.

type LogFile

type LogFile struct {
	// FileName is the file's name, the day it is for: 2020-09-19
	FileName string `json:"fileName"`
	// Size is how big the file is, as the server writes a size: 8.14 KB
	Size string `json:"size"`
}

LogFile is one of the files the server writes its own log to: what it did and what went wrong, a file a day.

type LogPage

type LogPage struct {
	PageNumber   int        `json:"pageNumber"`
	TotalPages   int        `json:"totalPages"`
	TotalEntries int        `json:"totalEntries"`
	Entries      []LogEntry `json:"entries"`
}

LogPage is one page of the entries a search matched.

type LogQuery

type LogQuery struct {
	// App and ClassPath are whose log: an installed app's name, and the
	// class of its part that keeps the log
	App, ClassPath string

	// Name is the name asked for: exactly, or with a * for any run of
	// characters. Case does not matter
	Name string
	// Client is the address that asked, exactly
	Client string
	// Type is the record type asked for, and RCode how it was answered:
	// NoError, NxDomain, ServerFailure, Refused
	Type, RCode string
	// Class is the class asked in: IN for nearly every query there is, and
	// CH for the few that ask a server about itself
	Class string
	// ResponseType is where the answer came from: Authoritative, Recursive,
	// Cached, Blocked, UpstreamBlocked or CacheBlocked
	ResponseType string
	// Protocol is how the query came: Udp, Tcp, Tls, Https or Quic
	Protocol string
	// Start and End bound when it was asked; a zero time is no bound
	Start, End time.Time

	// OldestFirst orders the entries from the oldest; the newest come first
	// without it
	OldestFirst bool
	// Page is which page of the matches, from 1, and PerPage how many
	// entries a page holds: the server's own 10 when 0
	Page, PerPage int
}

LogQuery is a search of an app's log of queries.

type Metrics

type Metrics struct {
	// UpSince is when the server started, in UTC
	UpSince       string     `json:"uptimestamp"`
	UptimeSeconds int64      `json:"uptimeSeconds"`
	Lifetime      StatTotals `json:"lifetimeCounters"`
}

Metrics are what the server has counted since it started, where Stats is what it counted over a window.

type NewRecord

type NewRecord struct {
	// Zone is the zone to add to; "" is the closest the server holds for
	// the name
	Zone string
	Name string
	Type string
	// TTL in seconds; 0 is the server's default for the type
	TTL      int
	Comments string
	// Data is the record's data by field, as a Record carries it
	Data RData
	// Overwrite replaces every record of this type at the name with this
	// one, where the default adds beside them
	Overwrite bool
	// ExpiryTTL is how many seconds after it was last changed the server
	// deletes the record by itself; 0 is never
	ExpiryTTL int
	// PTR has the server add the PTR record for an A or an AAAA record's
	// address as well, in the reverse zone it holds for it; with none it
	// refuses, unless CreatePTRZone has it make the reverse zone too
	PTR, CreatePTRZone bool
	// UpdateSVCBHints has the server bring the address hints of the zone's
	// SVCB and HTTPS records that name this A or AAAA record's name, and are
	// set to keep their hints themselves, up to date with it
	UpdateSVCBHints bool
}

NewRecord is a record to add.

type NewSSOUser

type NewSSOUser struct {
	Username    string
	DisplayName string
	// Identifier is what the provider knows the person by
	Identifier     string
	MemberOfGroups []string
}

NewSSOUser is an account for someone who signs in through the provider.

type NewScope

type NewScope struct {
	Name            string
	StartingAddress string
	EndingAddress   string
	SubnetMask      string
	DomainName      string
	// DNSUpdates has the server record each lease's host name under
	// DomainName, and its PTR; UseThisDNSServer tells machines to resolve
	// through the server itself; AllowOnlyReservedLeases leases to no
	// machine with no reservation. nil leaves each as it is
	DNSUpdates, UseThisDNSServer, AllowOnlyReservedLeases *bool
	RouterAddress                                         string
	DNSServers                                            []string
	// LeaseTimeDays is how long a lease runs in whole days, and LeaseTime
	// the same to the minute, which is used when it is given
	LeaseTimeDays int
	LeaseTime     time.Duration
	// Exclusions are ranges never leased, each as its first and last address
	Exclusions [][2]string

	// NewName renames the scope
	NewName string
	// what a scope does as it leases: how long it waits before it offers an
	// address, in milliseconds; whether it pings an address first to see
	// that nothing has it, with how long it waits and how often it tries;
	// whether a dynamic lease may write over a record made by hand; the TTL
	// of the records it writes; and whether it refuses machines with a
	// made-up hardware address or tells machines apart by hardware address
	// alone. nil leaves each as it is
	OfferDelayTime, PingCheckTimeout, PingCheckRetries, DNSTTL                                                        *int
	PingCheckEnabled, DNSOverwriteForDynamicLease, BlockLocallyAdministeredMACAddresses, IgnoreClientIdentifierOption *bool
	// what a machine that boots from the network is told: the server to
	// fetch from, by address and by name, and the file. nil leaves each
	ServerAddress, ServerHostName, BootFileName *string
	// the lists a scope hands out: the domains to search, and the WINS, NTP
	// (by address, or by name for the server to resolve), CAPWAP and TFTP
	// servers. nil leaves a list as it is and an empty one clears it
	DomainSearchList, WINSServers, NTPServers, NTPServerDomainNames, CAPWAPAddresses, TFTPServerAddresses []string
	// StaticRoutes, VendorInfo and GenericOptions are the tables: routes to
	// other networks, what a vendor's machines are told, and any option the
	// server has no name for, by its code. nil leaves one and empty clears
	StaticRoutes   []StaticRoute
	VendorInfo     []VendorInfo
	GenericOptions []GenericOption
	// ReservedLeases is every reservation of the scope, in place of the
	// ones it has: AddReservation adds one and leaves the rest. nil leaves
	// them all
	ReservedLeases []Reservation
}

NewScope is a scope to make, or to set over the one of its name.

type NewSigningKey

type NewSigningKey struct {
	KeyOptions

	// KeyType is KeySigningKey or ZoneSigningKey
	KeyType string
	// KeySize is RSA's, in bits
	KeySize int
	// PEMPrivateKey is a key to add in place of one the server makes, a
	// private key in PEM
	PEMPrivateKey string
	// RolloverDays is how often the key is replaced by itself, 0 to 365
	// where 0 is never; nil is the server's own 90 for a zone signing key
	// and never for a key signing key
	RolloverDays *int
}

NewSigningKey is a private key to add to a signed zone.

type NewUser

type NewUser struct {
	Username string
	Password string
	// DisplayName is the account's name as people read it, the username
	// when left out
	DisplayName string
}

NewUser is an account to make.

type NewZone

type NewZone struct {
	// Name is the zone's domain name; an IP address or a network in CIDR
	// form makes the reverse zone for it
	Name string
	// Type is one of ZoneTypes
	Type string
	// PrimaryNameServerAddresses are where a secondary or a stub zone
	// transfers from
	PrimaryNameServerAddresses []string
	// Forwarder is, for a Forwarder zone, the address of the name server
	// queries for names in the zone are sent on to
	Forwarder string
	// Catalog is the catalog zone to make the new zone a member of: every
	// server holding that catalog as a secondary then makes itself a
	// secondary of the new zone, which is how a cluster's nodes come to
	// share one
	Catalog string
	// SerialByDate has a zone of the server's own number its changes by the
	// day, 2026101001, where the default counts up from 1
	SerialByDate bool

	// TransferProtocol is what a copy transfers over - Tcp, Tls or Quic -
	// and TSIGKeyName the key it signs its transfers with, by name
	TransferProtocol, TSIGKeyName string
	// ValidateZone has a Secondary check each transfer against the zone's
	// ZONEMD record, and switch itself off when one does not match
	ValidateZone bool

	// EmptyForwarder makes a Forwarder zone with no record in it, where the
	// default makes it with the one that sends its names on
	EmptyForwarder bool
	// ForwarderProtocol is how a Forwarder zone's name server is asked -
	// Udp, Tcp, Tls, Https or Quic - DNSSECValidation whether its answers
	// are validated, and Proxy what it is reached through
	ForwarderProtocol string
	DNSSECValidation  bool
	Proxy             *Proxy
}

NewZone is a zone to create.

type Node

type Node struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
	// URL is where the node's console answers the other nodes, over HTTPS
	URL         string   `json:"url"`
	IPAddresses []string `json:"ipAddresses"`
	// Type is the node's role: the one Primary, whose settings the others
	// copy, or a Secondary
	Type string `json:"type"`
	// State is Self for the server asked, and for another node whether it
	// is reached: Connected, Unreachable, or not yet known
	State   string `json:"state"`
	Version string `json:"version"`
	UpSince string `json:"upSince"`
	// LastSeen is when the server asked last heard from the node
	LastSeen string `json:"lastSeen"`
	// ConfigLastSynced is when a secondary last copied the primary's settings
	ConfigLastSynced string `json:"configLastSynced"`
}

Node is one server of a cluster, as the server that was asked sees it.

type OpenSession

type OpenSession struct {
	Username string `json:"username"`
	// PartialToken is the start of the session's token, which is what the
	// server knows a session by when it is asked to end one. It is not
	// enough of the token to use
	PartialToken string `json:"partialToken"`
	// Type is Standard for someone signed in at the console, and ApiToken
	// for a token, which does not expire
	Type      string `json:"type"`
	TokenName string `json:"tokenName"`
	// IsCurrentSession is the session being the one that asked
	IsCurrentSession bool `json:"isCurrentSession"`
	// LastSeen is when the session last made a call, in UTC, and
	// LastSeenRemoteAddress where from
	LastSeen              string `json:"lastSeen"`
	LastSeenRemoteAddress string `json:"lastSeenRemoteAddress"`
	LastSeenUserAgent     string `json:"lastSeenUserAgent"`
}

OpenSession is someone signed in to the server, or an API token made on it.

type Option

type Option func(o *chttp.Options)

Option is something a client is made with beside its address and token.

func WithLog

func WithLog(log chttp.Logger) Option

WithLog has the client say what it sends and is sent to a logger, each exchange at trace and each request tried again at debug, with what is secret in them hidden. A client given none logs nothing.

type Permission

type Permission struct {
	CanView   bool `json:"canView"`
	CanModify bool `json:"canModify"`
	CanDelete bool `json:"canDelete"`
}

Permission is what an account may do in one section.

type Profile

type Profile struct {
	Username    string `json:"username"`
	DisplayName string `json:"displayName"`
	IsSSOUser   bool   `json:"isSsoUser"`
	TOTPEnabled bool   `json:"totpEnabled"`
	Disabled    bool   `json:"disabled"`
	// PreviousSessionLoggedOn and RecentSessionLoggedOn are when the account
	// signed in the time before last and last, in UTC, and the addresses
	// beside them where from
	PreviousSessionLoggedOn      string `json:"previousSessionLoggedOn"`
	PreviousSessionRemoteAddress string `json:"previousSessionRemoteAddress"`
	RecentSessionLoggedOn        string `json:"recentSessionLoggedOn"`
	RecentSessionRemoteAddress   string `json:"recentSessionRemoteAddress"`
	// SessionTimeoutSeconds is how long a session of the account's lasts
	// with nothing using it
	SessionTimeoutSeconds int      `json:"sessionTimeoutSeconds"`
	MemberOfGroups        []string `json:"memberOfGroups"`
	// Sessions are the account's own: who is signed in as it, and its API
	// tokens
	Sessions []OpenSession `json:"sessions"`
}

Profile is an account as its own owner sees it.

type ProfileChange

type ProfileChange struct {
	// DisplayName is the account's name as people read it, which single
	// sign-on sets for an account of its own
	DisplayName string
	// SessionTimeoutSeconds is how long a session lasts with nothing using
	// it, 0 to leave it
	SessionTimeoutSeconds int
}

ProfileChange is what to set of an account's own profile: whatever is left as it is here stays as it is on the server.

type Proxy

type Proxy struct {
	// Type is NoProxy, DefaultProxy (the server's own, from its settings),
	// Http or Socks5
	Type     string
	Address  string
	Port     int
	Username string
	// Password is sent and never read back
	Password string
}

Proxy is what a forwarder is reached through.

type RData

type RData map[string]any

RData is a record's data as the API gives it, by field name.

func ParseValue

func ParseValue(recordType, value string) (RData, error)

ParseValue reads a record's data from its value on one line, as Value writes one: an address for an A, "10 mail.example.com" for an MX, "1 . alpn=h2,h3 port=443" for an HTTPS. A TXT record's value is its whole text, spaces and all; an APP record's is the app's name, which may hold spaces, and then its class; a type the server has no layout for is its bytes in hex, 01:02:03. The options of a record are no part of its value.

type Record

type Record struct {
	// Name is the record's full domain name, the zone's own for a record
	// at its apex
	Name     string `json:"name"`
	Type     string `json:"type"`
	TTL      int    `json:"ttl"`
	Disabled bool   `json:"disabled"`
	Comments string `json:"comments"`
	// Data is the record's data, whose fields depend on its type: ipAddress
	// for an A, cname for a CNAME, preference and exchange for an MX
	Data RData `json:"rData"`
	// LastUsedOn is when the record last answered a query, in UTC; a record
	// never used carries the zero time, which Used reports as never
	LastUsedOn   string `json:"lastUsedOn"`
	LastModified string `json:"lastModified"`
	// ExpiryTTL is how many seconds after it was last changed the server
	// deletes the record by itself, 0 for never
	ExpiryTTL int `json:"expiryTtl"`
	// GlueRecords are the addresses an NS record carries for its name
	// server, which the server gives beside the record's data rather than in
	// it
	GlueRecords []string `json:"glueRecords"`
}

Record is one resource record as the server holds it.

func (*Record) Address

func (r *Record) Address() (netip.Addr, bool)

Address is the address of an A or an AAAA record.

func (*Record) Modified

func (r *Record) Modified() (time.Time, bool)

Modified is when the record was last changed, and false when the server does not say.

func (*Record) Options

func (r *Record) Options() map[string]string

Options are the record's options that are set, by the names the API takes them under. A proxy's password is not among them: the server never gives one back.

func (*Record) SOA

func (r *Record) SOA() SOA

SOA reads an SOA record; any other record gives an empty one.

func (*Record) Target

func (r *Record) Target() string

Target is the domain name the record points at - a CNAME's, an MX's exchange, an NS's server - and "" for a type that points at none.

func (*Record) Used

func (r *Record) Used() (time.Time, bool)

Used is when the record last answered a query, and false for one that never has.

func (*Record) Value

func (r *Record) Value() string

Value is the record's data on one line, as a zone file would write it: 10.0.0.4 for an A, "10 mail.example.com" for an MX, "1 . alpn=h2,h3" for an HTTPS. What is an option of the record and no part of its value - an NS record's glue, how a forwarder is reached - is not in it. A NAPTR's flags, services and expression are each in quotes, since any of them may be nothing.

type RecordUpdate

type RecordUpdate struct {
	// Name is the record's name; a different one moves it there
	Name     string
	TTL      int
	Disabled bool
	Comments string
	// ExpiryTTL is how many seconds after this change the server deletes
	// the record by itself; 0 is never
	ExpiryTTL int
	// Data is the record's data by field, as a Record carries it, its
	// options among them: what a forwarder record is reached through, an NS
	// record's glue. An option left out is reset by the server
	Data RData
	// PTR has the server change the PTR record for an A or an AAAA record's
	// address with it, CreatePTRZone make the reverse zone when it holds
	// none, and UpdateSVCBHints bring the hints of the zone's SVCB and
	// HTTPS records up to date
	PTR, CreatePTRZone, UpdateSVCBHints bool
}

RecordUpdate is a record as it should be once changed. Every field is what the record will have: the server keeps nothing an update does not send, so a TTL, a comment or a disabled state left out of one is reset, not kept. Fill it from the record as it is (UpdateOf) and change what is to change.

func UpdateOf

func UpdateOf(rec *Record) RecordUpdate

UpdateOf is a record as it is, to change and hand to UpdateRecord: its data with its options, and an NS record's glue with them. What the server never gives back cannot be carried over: a forwarder record that goes through a proxy with a password must be given the password again.

type Reservation

type Reservation struct {
	HostName        string `json:"hostName"`
	HardwareAddress string `json:"hardwareAddress"`
	Address         string `json:"address"`
	Comments        string `json:"comments"`
}

Reservation is an address a scope keeps for one machine, by its hardware address.

type Resolution

type Resolution struct {
	Metadata struct {
		// NameServer is who answered: a name and its address
		NameServer string `json:"NameServer"`
		Protocol   string `json:"Protocol"`
		// RoundTripTime is how long the answer took, as the server writes
		// it: 16.24 ms
		RoundTripTime string `json:"RoundTripTime"`
	} `json:"Metadata"`
	// RCode is how the query went: NoError, NxDomain, ServerFailure, Refused
	RCode string `json:"RCODE"`
	// Authoritative is the answer coming from a zone the name server holds
	// itself, not from its cache or from another server
	Authoritative bool `json:"AuthoritativeAnswer"`
	Truncated     bool `json:"Truncation"`
	// AuthenticData is the answer having been validated with DNSSEC
	AuthenticData bool             `json:"AuthenticData"`
	Answer        []ResolvedRecord `json:"Answer"`
	Authority     []ResolvedRecord `json:"Authority"`
	Additional    []ResolvedRecord `json:"Additional"`
	// EDNS is what the answer carries beside its records: among it, the
	// name server's own word on why it answered as it did
	EDNS struct {
		Options []struct {
			Code string `json:"Code"`
			Data struct {
				InfoCode  string `json:"InfoCode"`
				ExtraText string `json:"ExtraText"`
			} `json:"Data"`
		} `json:"Options"`
	} `json:"EDNS"`
}

Resolution is a name server's answer to a query, as the server that asked it got it.

func (*Resolution) Blocked

func (r *Resolution) Blocked() *Block

Blocked is why the name server blocked the name, nil for an answer that does not say it was blocked.

type ResolveQuery

type ResolveQuery struct {
	// Via is who answers: ResolveThisServer, ResolveRecursively, or the
	// address of any name server, which the server asks from where it is
	Via string
	// Name and Type are the question: emby.example.com, A
	Name, Type string
	// Protocol is Udp (the default), Tcp, Tls, Https or Quic
	Protocol string
	// DNSSEC asks for validation
	DNSSEC bool
	// ClientSubnet is a network the question is asked as if from, 203.0.113.0/24
	// say: what a name server that answers by where the asker is would tell
	// a client there
	ClientSubnet string
}

ResolveQuery is a question for a server to put to a name server.

type ResolvedRecord

type ResolvedRecord struct {
	Name string `json:"Name"`
	Type string `json:"Type"`
	// TTLText is the TTL as the server writes it, with its length in words:
	// 3600 (1h)
	TTLText string `json:"TTL"`
	Data    RData  `json:"RDATA"`
}

ResolvedRecord is one record of an answer. Its data is laid out as a DNS message's is, which is not how a zone's record carries the same data: IPAddress where a zone's record has ipAddress, Domain for a CNAME's target.

func (*ResolvedRecord) Address

func (r *ResolvedRecord) Address() (netip.Addr, bool)

Address is the address of an A or an AAAA record.

func (*ResolvedRecord) TTL

func (r *ResolvedRecord) TTL() int

TTL is the record's TTL in seconds.

func (*ResolvedRecord) Target

func (r *ResolvedRecord) Target() string

Target is the domain name the record points at, "" for a type that points at none.

func (*ResolvedRecord) Value

func (r *ResolvedRecord) Value() string

Value is the record's data on one line, as a zone file would write it; a type this client has no layout for is written as its fields by name.

type SOA

type SOA struct {
	// Primary is the name server the zone names as its primary, and
	// Responsible the mailbox of whoever runs it
	Primary, Responsible string
	Serial               uint32
	// Refresh, Retry and Expire are a copy's times, and Minimum how long
	// the answer that a name does not exist may be kept: all in seconds
	Refresh, Retry, Expire, Minimum int
	// SerialByDate is the zone numbering its changes by the day,
	// 2026101001, where the default counts up from 1
	SerialByDate bool
}

SOA is what a zone's SOA record says of the zone.

type SSO

type SSO struct {
	Enabled   bool   `json:"ssoEnabled"`
	Authority string `json:"ssoAuthority"`
	ClientID  string `json:"ssoClientId"`
	// MetadataAddress is where the provider describes itself, when that is
	// not where the authority's address says
	MetadataAddress string `json:"ssoMetadataAddress"`
	// AllowSignup is an account being made for whoever signs in through the
	// provider for the first time, and AllowSignupOnlyForMappedUsers only
	// for those in a group the map names
	AllowSignup                   bool           `json:"ssoAllowSignup"`
	AllowSignupOnlyForMappedUsers bool           `json:"ssoAllowSignupOnlyForMappedUsers"`
	GroupMap                      []GroupMapping `json:"ssoGroupMap"`
	// LocalGroups are every group there is here, for mapping to, when they
	// were asked for
	LocalGroups []string `json:"localGroups"`
}

SSO is how the server is set up for single sign-on with OpenID Connect. The client's secret at the provider is never read.

type SSOChange

type SSOChange struct {
	Enabled *bool
	// Authority, ClientID and MetadataAddress are set by a value and cleared
	// by ""; nil leaves one as it is
	Authority, ClientID, MetadataAddress *string
	// ClientSecret is the client's secret at the provider, "" to leave it
	ClientSecret                  string
	AllowSignup                   *bool
	AllowSignupOnlyForMappedUsers *bool
	// GroupMap replaces the map there is, whole: nil leaves it
	GroupMap []GroupMapping
}

SSOChange is what to set of single sign-on: whatever is left as it is here stays as it is on the server.

type SSOUserChange

type SSOUserChange struct {
	NewUsername string
	DisplayName string
	// MemberOfGroups are the groups the account is in from now on: nil
	// leaves them as they are
	MemberOfGroups []string
}

SSOUserChange is what to set of a single sign-on account: whatever is left as it is here stays as it is on the server.

type Scope

type Scope struct {
	Name    string `json:"name"`
	Enabled bool   `json:"enabled"`
	// StartingAddress and EndingAddress are the range leased from
	StartingAddress  string `json:"startingAddress"`
	EndingAddress    string `json:"endingAddress"`
	SubnetMask       string `json:"subnetMask"`
	NetworkAddress   string `json:"networkAddress"`
	BroadcastAddress string `json:"broadcastAddress"`
	// InterfaceAddress is the address of the interface an enabled scope
	// serves on
	InterfaceAddress string `json:"interfaceAddress"`
}

Scope is a DHCP scope as the server lists it: a range of addresses it leases on one network.

type ScopeDetails

type ScopeDetails struct {
	Name            string `json:"name"`
	StartingAddress string `json:"startingAddress"`
	EndingAddress   string `json:"endingAddress"`
	SubnetMask      string `json:"subnetMask"`

	LeaseTimeDays    int `json:"leaseTimeDays"`
	LeaseTimeHours   int `json:"leaseTimeHours"`
	LeaseTimeMinutes int `json:"leaseTimeMinutes"`

	// DomainName is the domain a client is told it is in, and the zone its
	// name is recorded in when DNSUpdates is on
	DomainName string `json:"domainName"`
	// DNSUpdates is the server recording each lease's host name in DNS
	DNSUpdates bool `json:"dnsUpdates"`
	DNSTTL     int  `json:"dnsTtl"`

	RouterAddress string `json:"routerAddress"`
	// UseThisDNSServer tells clients to resolve through this server itself,
	// and DNSServers names others
	UseThisDNSServer bool     `json:"useThisDnsServer"`
	DNSServers       []string `json:"dnsServers"`

	// Exclusions are ranges inside the scope's that are never leased
	Exclusions []struct {
		StartingAddress string `json:"startingAddress"`
		EndingAddress   string `json:"endingAddress"`
	} `json:"exclusions"`
	// ReservedLeases are the addresses kept for particular machines
	ReservedLeases []Reservation `json:"reservedLeases"`

	// how it leases, and what else it hands out: see NewScope
	OfferDelayTime                       int             `json:"offerDelayTime"`
	PingCheckEnabled                     bool            `json:"pingCheckEnabled"`
	PingCheckTimeout                     int             `json:"pingCheckTimeout"`
	PingCheckRetries                     int             `json:"pingCheckRetries"`
	DomainSearchList                     []string        `json:"domainSearchList"`
	DNSOverwriteForDynamicLease          bool            `json:"dnsOverwriteForDynamicLease"`
	ServerAddress                        string          `json:"serverAddress"`
	ServerHostName                       string          `json:"serverHostName"`
	BootFileName                         string          `json:"bootFileName"`
	WINSServers                          []string        `json:"winsServers"`
	NTPServers                           []string        `json:"ntpServers"`
	NTPServerDomainNames                 []string        `json:"ntpServerDomainNames"`
	StaticRoutes                         []StaticRoute   `json:"staticRoutes"`
	VendorInfo                           []VendorInfo    `json:"vendorInfo"`
	CAPWAPAddresses                      []string        `json:"capwapAcIpAddresses"`
	TFTPServerAddresses                  []string        `json:"tftpServerAddresses"`
	GenericOptions                       []GenericOption `json:"genericOptions"`
	AllowOnlyReservedLeases              bool            `json:"allowOnlyReservedLeases"`
	BlockLocallyAdministeredMACAddresses bool            `json:"blockLocallyAdministeredMacAddresses"`
	IgnoreClientIdentifierOption         bool            `json:"ignoreClientIdentifierOption"`
}

ScopeDetails is a scope whole: what it leases, what it tells a client, and the addresses it keeps for particular machines.

type SecondaryNode

type SecondaryNode struct {
	// ID is the id the node made up for itself when it began to join
	ID int64
	// URL is the node's console over HTTPS
	URL       string
	Addresses []string
	// Certificate is the certificate the node's console answers with,
	// base64url encoded
	Certificate string
}

SecondaryNode is a secondary node as it tells the primary of itself.

type ServerInfo

type ServerInfo struct {
	Version string `json:"version"`
	// UpSince is when the server started, in UTC
	UpSince string `json:"uptimestamp"`
	// Domain is the server's own domain name, the primary name server its
	// zones name
	Domain             string `json:"dnsServerDomain"`
	DefaultRecordTTL   int    `json:"defaultRecordTtl"`
	DefaultNSRecordTTL int    `json:"defaultNsRecordTtl"`
	DefaultSOATTL      int    `json:"defaultSoaRecordTtl"`
	DNSSECValidation   bool   `json:"dnssecValidation"`
	ClusterInitialized bool   `json:"clusterInitialized"`
	ClusterDomain      string `json:"clusterDomain"`
	// Permissions are what the token's account may do, by section of the
	// console: Zones, Cache, Settings and the rest
	Permissions map[string]Permission `json:"permissions"`
}

ServerInfo is what a session is told of the server it is on.

func (*ServerInfo) Started

func (i *ServerInfo) Started() (time.Time, bool)

Started is when the server started, and false when it does not say in a way that can be read.

type Session

type Session struct {
	Username    string     `json:"username"`
	DisplayName string     `json:"displayName"`
	TokenName   string     `json:"tokenName"`
	Info        ServerInfo `json:"info"`
}

Session is what a token's session says of the account it belongs to and of the server. The token itself, which the server sends back with it, is not kept.

type Settings

type Settings struct {
	Version string `json:"version"`
	Domain  string `json:"dnsServerDomain"`

	// LocalEndPoints are the addresses the server answers DNS on
	LocalEndPoints []string `json:"dnsServerLocalEndPoints"`

	DefaultRecordTTL   int `json:"defaultRecordTtl"`
	DefaultNSRecordTTL int `json:"defaultNsRecordTtl"`
	DefaultSOATTL      int `json:"defaultSoaRecordTtl"`

	// ZoneTransferAllowedNetworks and NotifyAllowedNetworks are who may
	// transfer any zone from the server, and send it a notify, whatever a
	// zone's own settings say
	ZoneTransferAllowedNetworks []string `json:"zoneTransferAllowedNetworks"`
	NotifyAllowedNetworks       []string `json:"notifyAllowedNetworks"`

	CheckForUpdate   bool `json:"dnsServerEnableCheckForUpdate"`
	AppsAutoUpdate   bool `json:"dnsAppsEnableAutomaticUpdate"`
	DNSSECValidation bool `json:"dnssecValidation"`

	// Recursion is who the server resolves other people's names for: Deny,
	// Allow, AllowOnlyForPrivateNetworks or UseSpecifiedNetworkACL, with
	// RecursionNetworkACL for the last
	Recursion           string   `json:"recursion"`
	RecursionNetworkACL []string `json:"recursionNetworkACL"`
	QNameMinimization   bool     `json:"qnameMinimization"`

	// Forwarders are the name servers the server sends what it does not
	// hold to; none is resolving from the root itself
	Forwarders        []string `json:"forwarders"`
	ForwarderProtocol string   `json:"forwarderProtocol"`
	// Proxy is the proxy the server resolves through, nil for none
	Proxy *struct {
		Type    string `json:"type"`
		Address string `json:"address"`
		Port    int    `json:"port"`
	} `json:"proxy"`

	TSIGKeys []TSIGKey `json:"tsigKeys"`

	SaveCache              bool `json:"saveCache"`
	ServeStale             bool `json:"serveStale"`
	CacheMaximumEntries    int  `json:"cacheMaximumEntries"`
	CacheMinimumRecordTTL  int  `json:"cacheMinimumRecordTtl"`
	CacheMaximumRecordTTL  int  `json:"cacheMaximumRecordTtl"`
	CacheNegativeRecordTTL int  `json:"cacheNegativeRecordTtl"`

	EnableBlocking               bool     `json:"enableBlocking"`
	BlockingType                 string   `json:"blockingType"`
	CustomBlockingAddresses      []string `json:"customBlockingAddresses"`
	BlockListURLs                []string `json:"blockListUrls"`
	BlockListUpdateIntervalHours int      `json:"blockListUpdateIntervalHours"`
	// BlockListNextUpdatedOn is when the lists are next fetched, in UTC
	BlockListNextUpdatedOn string `json:"blockListNextUpdatedOn"`
	// TemporaryDisableBlockingTill is when blocking that was switched off
	// for a while comes back on, in UTC; "" when it was not
	TemporaryDisableBlockingTill string `json:"temporaryDisableBlockingTill"`
	// BlockingBypassList are the clients nothing is blocked for, as
	// addresses and networks
	BlockingBypassList []string `json:"blockingBypassList"`

	WebServiceHTTPPort          int  `json:"webServiceHttpPort"`
	WebServiceEnableTLS         bool `json:"webServiceEnableTls"`
	WebServiceTLSPort           int  `json:"webServiceTlsPort"`
	WebServiceHTTPToTLSRedirect bool `json:"webServiceHttpToTlsRedirect"`
	WebServiceUseSelfSignedCert bool `json:"webServiceUseSelfSignedTlsCertificate"`

	EnableDNSOverUDPProxy bool `json:"enableDnsOverUdpProxy"`
	EnableDNSOverTCPProxy bool `json:"enableDnsOverTcpProxy"`
	EnableDNSOverHTTP     bool `json:"enableDnsOverHttp"`
	EnableDNSOverTLS      bool `json:"enableDnsOverTls"`
	EnableDNSOverHTTPS    bool `json:"enableDnsOverHttps"`
	EnableDNSOverHTTP3    bool `json:"enableDnsOverHttp3"`
	EnableDNSOverQUIC     bool `json:"enableDnsOverQuic"`

	LoggingType    string `json:"loggingType"`
	LogQueries     bool   `json:"logQueries"`
	UseLocalTime   bool   `json:"useLocalTime"`
	LogFolder      string `json:"logFolder"`
	MaxLogFileDays int    `json:"maxLogFileDays"`
}

Settings is how a server is set up: the part of its settings this client reads. Nothing secret is among them - a TSIG key is its name and its algorithm, never its shared secret, and no certificate or proxy password is read at all - so nothing that prints the settings can print a credential.

type SignedIn

type SignedIn struct {
	Username    string `json:"username"`
	DisplayName string `json:"displayName"`
	// IsSSOUser is an account that signs in through the single sign-on the
	// server is set up with, and has no password of its own here
	IsSSOUser bool `json:"isSsoUser"`
	// TOTPEnabled is the account asking for a one-time code beside its
	// password
	TOTPEnabled bool       `json:"totpEnabled"`
	Info        ServerInfo `json:"info"`
}

SignedIn is who signing in found the name and password to be.

type Signing

type Signing struct {
	KeyOptions

	// KSKKeySize and ZSKKeySize are the sizes of RSA's two keys, in bits
	KSKKeySize, ZSKKeySize int
	// PEMKSKPrivateKey and PEMZSKPrivateKey are keys to sign with in place
	// of ones the server makes, each a private key in PEM
	PEMKSKPrivateKey, PEMZSKPrivateKey string
	// DNSKeyTTL is the TTL of the zone's DNSKEY records, 0 for the server's
	// own day
	DNSKeyTTL int
	// ZSKRolloverDays is how often the zone signing key is replaced, 0 to
	// 365 where 0 is never; nil is the server's own 30
	ZSKRolloverDays *int
	// NXProof is how the zone proves a name is not in it: NSEC, which lets
	// anyone walk the zone's names, or NSEC3; "" is the server's own NSEC.
	// Iterations and SaltLength are NSEC3's
	NXProof                string
	Iterations, SaltLength int
}

Signing is how a zone is signed.

type SigningKey

type SigningKey struct {
	KeyTag int `json:"keyTag"`
	// KeyType is KeySigningKey or ZoneSigningKey
	KeyType   string `json:"keyType"`
	Algorithm string `json:"algorithm"`
	// State is how far the key has come: Generated, Published, Ready,
	// Active, Retired, Revoked; with when it last changed and, for one on
	// its way, when it will be ready, in UTC
	State          string `json:"state"`
	StateChangedOn string `json:"stateChangedOn"`
	StateReadyBy   string `json:"stateReadyBy"`
	IsRetiring     bool   `json:"isRetiring"`
	// RolloverDays is how often the key is replaced by itself, 0 for never
	RolloverDays int `json:"rolloverDays"`
}

SigningKey is one of a signed zone's private keys, by what the server says of it: the key itself is never read.

type StatTotals

type StatTotals struct {
	Queries       int `json:"totalQueries"`
	NoError       int `json:"totalNoError"`
	ServerFailure int `json:"totalServerFailure"`
	NxDomain      int `json:"totalNxDomain"`
	Refused       int `json:"totalRefused"`
	Authoritative int `json:"totalAuthoritative"`
	Recursive     int `json:"totalRecursive"`
	Cached        int `json:"totalCached"`
	Blocked       int `json:"totalBlocked"`
	Dropped       int `json:"totalDropped"`
	Clients       int `json:"totalClients"`

	// what the server holds now, whatever the window
	Zones         int `json:"zones"`
	CachedEntries int `json:"cachedEntries"`
	// AllowedZones and BlockedZones are the names on the server's own two
	// lists; AllowListZones and BlockListZones the names of the lists it
	// fetches
	AllowedZones   int `json:"allowedZones"`
	BlockedZones   int `json:"blockedZones"`
	AllowListZones int `json:"allowListZones"`
	BlockListZones int `json:"blockListZones"`
}

StatTotals are a window's counts. The queries are counted by how each was answered twice over: by its response code (NoError, ServerFailure, NxDomain, Refused) and by where the answer came from (Authoritative, Recursive, Cached, Blocked, Dropped).

type StaticRoute

type StaticRoute struct {
	Destination string `json:"destination"`
	SubnetMask  string `json:"subnetMask"`
	Router      string `json:"router"`
}

StaticRoute is a route a scope tells its machines of: the network, its mask, and the router that reaches it.

type Stats

type Stats struct {
	Totals StatTotals `json:"stats"`
	// TopClients, TopDomains and TopBlockedDomains are the ten that asked
	// most and were asked for most: TopStats gives more
	TopClients        []TopClient `json:"topClients"`
	TopDomains        []TopDomain `json:"topDomains"`
	TopBlockedDomains []TopDomain `json:"topBlockedDomains"`

	QueryTypeChart chart `json:"queryTypeChartData"`
	ProtocolChart  chart `json:"protocolTypeChartData"`
}

Stats is what a server did over a window, as its dashboard shows it.

func (*Stats) Protocols

func (s *Stats) Protocols() map[string]int

Protocols are the window's queries by how they came: Udp, Tcp, Tls, Https, Quic.

func (*Stats) QueryTypes

func (s *Stats) QueryTypes() map[string]int

QueryTypes are the window's queries by the record type asked for: the ten most asked.

type StatsWindow

type StatsWindow struct {
	Type       string
	Start, End time.Time

	// EveryQueryType has Stats give each record type asked for its own
	// count, where the server otherwise gives the leading ones and the rest
	// as one
	EveryQueryType bool
	// NoReverseLookup has TopStats give clients by address alone, without
	// the server looking up a name for each, and OnlyRateLimited only the
	// clients it is holding back for asking too much
	NoReverseLookup, OnlyRateLimited bool
}

StatsWindow is the time a server's statistics are asked for: one of the windows it keeps (StatsLastHour, the default, to StatsLastYear), or the time between Start and End.

type Status

type Status struct {
	// Server is the server's own domain name
	Server string `json:"server"`
	// HasDefaultCredentials is the admin account still on the password the
	// server ships with
	HasDefaultCredentials bool `json:"hasDefaultCredentials"`
	SSOEnabled            bool `json:"ssoEnabled"`
}

Status is what a server says of itself to anyone who asks, token or none.

type StoreApp

type StoreApp struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description"`
	// URL is where the app's zip file is fetched from
	URL string `json:"url"`
	// Size is how big the zip file is, as the server writes a size: 2.01 MB
	Size      string `json:"size"`
	Installed bool   `json:"installed"`
	// InstalledVersion and UpdateAvailable are an installed app's
	InstalledVersion string `json:"installedVersion"`
	UpdateAvailable  bool   `json:"updateAvailable"`
}

StoreApp is a DNS app the server's maker offers for installing.

type TSIGKey

type TSIGKey struct {
	Name      string `json:"keyName"`
	Algorithm string `json:"algorithmName"`
}

TSIGKey is a transfer key by its name: its secret is never read.

type TopClient

type TopClient struct {
	// Name is the client's address, and Domain the name its PTR gives it
	Name   string `json:"name"`
	Domain string `json:"domain"`
	Hits   int    `json:"hits"`
	// RateLimited is the server holding the client back for asking too much
	RateLimited bool `json:"rateLimited"`
}

TopClient is a client by how much it asked.

type TopDomain

type TopDomain struct {
	Name string `json:"name"`
	Hits int    `json:"hits"`
}

TopDomain is a name by how often it was asked for.

type TwoFactorSetup

type TwoFactorSetup struct {
	// Enabled is the account having a second factor already
	Enabled bool `json:"totpEnabled"`
	// Secret is what the app is given by hand, and QRCodePNG the same as a
	// picture, a PNG in base64. Either one is the second factor itself:
	// whoever has it can make the codes
	Secret    string `json:"secret"`
	QRCodePNG string `json:"qrCodePngImage"`
}

TwoFactorSetup is a second factor waiting to be switched on: the secret an authenticator app is given, as text and as the picture one scans.

type Update

type Update struct {
	// CheckEnabled is the server set to look for updates at all
	CheckEnabled   bool   `json:"dnsServerEnableCheckForUpdate"`
	Available      bool   `json:"updateAvailable"`
	CurrentVersion string `json:"currentVersion"`
	UpdateVersion  string `json:"updateVersion"`
	Title          string `json:"updateTitle"`
	Message        string `json:"updateMessage"`
	ChangeLogLink  string `json:"changeLogLink"`
}

Update is what the server knows of a newer version of itself.

type UpdatePolicy

type UpdatePolicy struct {
	TSIGKeyName string `json:"tsigKeyName"`
	// Domain is the name it may change, or *.example.com for every name
	// under one
	Domain string `json:"domain"`
	// AllowedTypes are the record types it may change there; ANY is all
	AllowedTypes []string `json:"allowedTypes"`
}

UpdatePolicy is one key a dynamic update may be signed with, and what an update signed with it may change.

type User

type User struct {
	Profile

	// Groups are every group there is, for choosing among, when they were
	// asked for
	Groups []string `json:"groups"`
}

User is an account as an administrator sees it. A list of users gives each without its groups and sessions.

type UserAccess

type UserAccess struct {
	Username string `json:"username"`

	Permission
}

UserAccess is what one account may do with something, and GroupAccess what the members of one group may.

type UserChange

type UserChange struct {
	DisplayName string
	// NewUsername renames the account
	NewUsername string
	// DisableTwoFactor takes the account's second factor off. One cannot be
	// put on for somebody else
	DisableTwoFactor bool
	// Disabled switches the account off, which ends its sessions, or back on
	Disabled *bool
	// SessionTimeoutSeconds is how long a session lasts with nothing using
	// it, 0 to leave it
	SessionTimeoutSeconds int
	// NewPassword resets the password, hashed with Iterations rounds or the
	// server's own 100000 for 0
	NewPassword string
	Iterations  int
	// MemberOfGroups are the groups the account is in from now on: nil
	// leaves them as they are
	MemberOfGroups []string
}

UserChange is what to set of an account: whatever is left as it is here stays as it is on the server.

type VendorInfo

type VendorInfo struct {
	Identifier  string `json:"identifier"`
	Information string `json:"information"`
}

VendorInfo is what a scope tells the machines of one vendor: the class they say they are, and the bytes they are given, in hex.

type Zone

type Zone struct {
	Name string `json:"name"`
	Type string `json:"type"`
	// Internal is a zone the server made for itself and keeps: localhost and
	// the reverse zones for loopback
	Internal     bool   `json:"internal"`
	Disabled     bool   `json:"disabled"`
	SOASerial    uint32 `json:"soaSerial"`
	DNSSECStatus string `json:"dnssecStatus"`
	// Catalog is the catalog zone this one is a member of, "" for none
	Catalog string `json:"catalog"`
	// LastModified is when a record in the zone last changed, in UTC
	LastModified string `json:"lastModified"`

	// Expiry, IsExpired and SyncFailed are a secondary's: when the copy
	// stops being served unless a transfer renews it, whether it has, and
	// whether the last transfer from the primary failed
	Expiry     string `json:"expiry"`
	IsExpired  bool   `json:"isExpired"`
	SyncFailed bool   `json:"syncFailed"`

	// NotifyFailed and NotifyFailedFor are a primary's: whether telling its
	// secondaries of a change failed, and for which of them
	NotifyFailed    bool     `json:"notifyFailed"`
	NotifyFailedFor []string `json:"notifyFailedFor"`
}

Zone is an authoritative zone as the server lists it.

func (*Zone) Modified

func (z *Zone) Modified() (time.Time, bool)

Modified is when a record in the zone last changed, and false when the server does not say.

func (*Zone) Signed

func (z *Zone) Signed() bool

Signed reports whether the zone is DNSSEC signed.

type ZoneChange

type ZoneChange struct {
	// Disabled switches the zone off, or back on
	Disabled *bool
	// Catalog makes the zone a member of a catalog zone
	Catalog string

	// QueryAccess, ZoneTransfer, Notify and Update are the policies, as
	// ZoneOptions has them; "" leaves one as it is. A name the server does
	// not know it passes over without a word, so what was set is only known
	// by reading the options back
	QueryAccess, ZoneTransfer, Notify, Update string
	// the lists a policy by list reads: nil leaves one as it is, and an
	// empty one clears it
	QueryAccessNetworks, ZoneTransferNetworks, NotifyNameServers, UpdateNetworks []string

	// ZoneTransferTSIGKeyNames are the keys a transfer of the zone may be
	// signed with, by name; nil leaves them and an empty list clears them
	ZoneTransferTSIGKeyNames []string
	// UpdatePolicies are the keys a dynamic update must be signed with and
	// what each may change; nil leaves them and an empty list clears them
	UpdatePolicies []UpdatePolicy
	// NotifySecondaryCatalogsNameServers are the addresses a catalog zone
	// tells of a change to itself, under the notify policy for that
	NotifySecondaryCatalogsNameServers []string

	// a copy's: where its primary is (nil leaves it, and an empty list has
	// the server find the primary by resolving the zone's own records),
	// what it transfers over - Tcp, Tls or Quic - and the key it signs its
	// transfers with, where nil leaves the key and "" takes it off
	PrimaryNameServerAddresses     []string
	PrimaryZoneTransferProtocol    string
	PrimaryZoneTransferTSIGKeyName *string
	// ValidateZone has a Secondary check each transfer against the zone's
	// ZONEMD record
	ValidateZone *bool

	// a member of a catalog keeping its own setting where the catalog has
	// one for all its members
	OverrideCatalogQueryAccess, OverrideCatalogZoneTransfer, OverrideCatalogNotify *bool
}

ZoneChange is what to set of a zone's options: whatever is left as it is here stays as it is on the server.

type ZoneFilter

type ZoneFilter struct {
	// Name keeps the zones whose name matches, * standing for any run of
	// characters and ? for one
	Name string
	// Type keeps the zones of one type (see ZoneTypes)
	Type string
}

ZoneFilter narrows a listing of zones on the server's side.

type ZoneImport

type ZoneImport struct {
	// KeepExisting leaves a name's records of a type as they are where the
	// file has records for them too; without it the file's replace them
	KeepExisting bool
	// ReplaceZone deletes every record the zone has before the file's are
	// added
	ReplaceZone bool
	// OverwriteSOASerial takes the SOA serial the file gives. A serial lower
	// than the zone's own stops its copies from following it
	OverwriteSOASerial bool
}

ZoneImport is how a zone file is taken into a zone.

type ZoneOptions

type ZoneOptions struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Disabled bool   `json:"disabled"`
	// Catalog is the catalog zone this one is a member of
	Catalog      string `json:"catalog"`
	DNSSECStatus string `json:"dnssecStatus"`

	// QueryAccess is who may ask for the zone's names: Deny, Allow,
	// AllowOnlyPrivateNetworks, AllowOnlyZoneNameServers,
	// UseSpecifiedNetworkACL or AllowZoneNameServersAndUseSpecifiedNetworkACL
	QueryAccess           string   `json:"queryAccess"`
	QueryAccessNetworkACL []string `json:"queryAccessNetworkACL"`

	// ZoneTransfer is who may transfer the zone whole: Deny, Allow,
	// AllowOnlyZoneNameServers, UseSpecifiedNetworkACL or
	// AllowZoneNameServersAndUseSpecifiedNetworkACL
	ZoneTransfer             string   `json:"zoneTransfer"`
	ZoneTransferNetworkACL   []string `json:"zoneTransferNetworkACL"`
	ZoneTransferTSIGKeyNames []string `json:"zoneTransferTsigKeyNames"`

	// Notify is who is told when the zone changes: None, ZoneNameServers,
	// SpecifiedNameServers, BothZoneAndSpecifiedNameServers or
	// SeparateNameServersForCatalogAndMemberZones
	Notify            string   `json:"notify"`
	NotifyNameServers []string `json:"notifyNameServers"`
	NotifyFailed      bool     `json:"notifyFailed"`
	NotifyFailedFor   []string `json:"notifyFailedFor"`

	// Update is who may change the zone's records by a DNS update: Deny,
	// Allow, AllowOnlyZoneNameServers, UseSpecifiedNetworkACL or
	// AllowZoneNameServersAndUseSpecifiedNetworkACL
	Update           string   `json:"update"`
	UpdateNetworkACL []string `json:"updateNetworkACL"`
	// UpdateSecurityPolicies are the keys an update must be signed with,
	// each with the names and the types it may change
	UpdateSecurityPolicies []UpdatePolicy `json:"updateSecurityPolicies"`

	// a copy's: where its primary is, and how it is transferred from there
	PrimaryNameServerAddresses     []string `json:"primaryNameServerAddresses"`
	PrimaryZoneTransferProtocol    string   `json:"primaryZoneTransferProtocol"`
	PrimaryZoneTransferTSIGKeyName string   `json:"primaryZoneTransferTsigKeyName"`
	// ValidateZone is a Secondary checking each transfer against the zone's
	// ZONEMD record
	ValidateZone bool `json:"validateZone"`

	// a member of a catalog takes who may ask, who may transfer and who is
	// told from the catalog, unless it is set to keep its own
	OverrideCatalogQueryAccess  bool `json:"overrideCatalogQueryAccess"`
	OverrideCatalogZoneTransfer bool `json:"overrideCatalogZoneTransfer"`
	OverrideCatalogNotify       bool `json:"overrideCatalogNotify"`
	// NotifySecondaryCatalogsNameServers are, for a catalog zone told to
	// tell others than its members' servers, the addresses told of a change
	// to the catalog itself
	NotifySecondaryCatalogsNameServers []string `json:"notifySecondaryCatalogsNameServers"`

	// AvailableCatalogZoneNames are the catalogs the zone could be made a
	// member of, and AvailableTSIGKeyNames the keys the server has for a
	// transfer or an update to name
	AvailableCatalogZoneNames []string `json:"availableCatalogZoneNames"`
	AvailableTSIGKeyNames     []string `json:"availableTsigKeyNames"`
}

ZoneOptions is how one zone is served and copied: who may ask for its names, who may transfer it and with which keys, who is told when it changes, who may update it, and for a copy where its primary is.

type ZonePage

type ZonePage struct {
	PageNumber int    `json:"pageNumber"`
	TotalPages int    `json:"totalPages"`
	TotalZones int    `json:"totalZones"`
	Zones      []Zone `json:"zones"`
}

ZonePage is one page of the zones a server holds, with how many there are in all.

type ZoneRecords

type ZoneRecords struct {
	Zone    Zone     `json:"zone"`
	Records []Record `json:"records"`
}

ZoneRecords is a zone and records in it.

Directories

Path Synopsis
Package technitiumtest is a canned Technitium server for tests: it answers the API calls a test tells it to and records what it was asked.
Package technitiumtest is a canned Technitium server for tests: it answers the API calls a test tells it to and records what it was asked.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL