README
¶
PowerDNS client library for Go
This package contains a Go library for accessing the PowerDNS Authoritative API.
Supported features
- Servers
- Zones
- Cryptokeys
- Metadata
- TSIG Keys
- Searching
- Statistics
- Cache
Installation
Install using go get:
> go get github.com/mittwald/go-powerdns
Usage
First, instantiate a client using pdns.New:
client, err := pdns.New(
pdns.WithBaseURL("http://localhost:8081"),
pdns.WithAPIKeyAuthentication("supersecret"),
)
The client then offers more specialiced sub-clients, for example for managing server and zones. Have a look at this library's documentation for more information.
Complete example
package main
import "context"
import "github.com/mittwald/go-powerdns"
import "github.com/mittwald/go-powerdns/apis/zones"
func main() {
client, err := pdns.New(
pdns.WithBaseURL("http://localhost:8081"),
pdns.WithAPIKeyAuthentication("supersecret"),
)
if err != nil {
panic(err)
}
client.Zones().CreateZone(context.Background(), "localhost", zones.Zone{
Name: "mydomain.example.",
Type: zones.ZoneTypeZone,
Kind: zones.ZoneKindNative,
Nameservers: []string{
"ns1.example.com.",
"ns2.example.com.",
},
ResourceRecordSets: []zones.ResourceRecordSet{
{Name: "foo.mydomain.example.", Type: "A", TTL: 60, Records: []zones.Record{{Content: "127.0.0.1"}}},
},
})
}
Documentation
¶
Overview ¶
This package contains a client library used for connecting to the PowerDNS API.
Index ¶
- type Client
- type ClientOption
- func WithAPIKeyAuthentication(key string) ClientOption
- func WithBaseURL(baseURL string) ClientOption
- func WithBasicAuthentication(username string, password string) ClientOption
- func WithDebuggingOutput(out io.Writer) ClientOption
- func WithHTTPClient(httpClient *http.Client) ClientOption
- func WithTLSAuthentication(caFile string, clientCertFile string, clientKeyFile string) ClientOption
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// Status checks if the PowerDNS API is reachable. This does a simple HTTP connection check;
// it will NOT check if your authentication is set up correctly (except you're using TLS client
// authentication.
Status() error
// WaitUntilUp will block until the PowerDNS API accepts HTTP requests. You can use the "ctx"
// parameter to make this method wait only for (or until) a certain time (see examples).
WaitUntilUp(ctx context.Context) error
// Servers returns a specialized API for interacting with PowerDNS servers
Servers() servers.Client
// Zones returns a specialized API for interacting with PowerDNS zones
Zones() zones.Client
// Search returns a specialized API for searching
Search() search.Client
// Cache returns a specialized API for caching
Cache() cache.Client
// Cryptokeys returns a specialized API for cryptokeys
Cryptokeys() cryptokeys.Client
}
Client is the root-level interface for interacting with the PowerDNS API. You can instantiate an implementation of this interface using the "New" function.
Example (CreateZone) ¶
This example uses the "Zones()" sub-client to create a new zone.
client, _ := New(
WithBaseURL("http://localhost:8081"),
WithAPIKeyAuthentication("secret"),
)
input := zones.Zone{
Name: "mydomain.example.",
Type: zones.ZoneTypeZone,
Kind: zones.ZoneKindNative,
Nameservers: []string{
"ns1.example.com.",
"ns2.example.com.",
},
ResourceRecordSets: []zones.ResourceRecordSet{
{Name: "foo.mydomain.example.", Type: "A", TTL: 60, Records: []zones.Record{{Content: "127.0.0.1"}}},
},
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
zone, err := client.Zones().CreateZone(ctx, "localhost", input)
if err != nil {
panic(err)
}
fmt.Printf("zone ID: %s\n", zone.ID)
Output: zone ID: mydomain.example.
Example (GetServer) ¶
client, _ := New(
WithBaseURL("http://localhost:8081"),
WithAPIKeyAuthentication("secret"),
)
server, err := client.Servers().GetServer(context.Background(), "localhost")
if err != nil {
if pdnshttp.IsNotFound(err) {
// handle not found
} else {
panic(err)
}
}
fmt.Printf("found server: %s\n", server.ID)
Output:
Example (ListServers) ¶
client, _ := New(
WithBaseURL("http://localhost:8081"),
WithAPIKeyAuthentication("secret"),
)
servers, err := client.Servers().ListServers(context.Background())
if err != nil {
panic(err)
}
for i := range servers {
fmt.Printf("found server: %s\n", servers[i].ID)
}
Output:
Example (WaitUntilUp) ¶
This example uses the "context.WithTimeout" function to wait until the PowerDNS API is reachable up until a given timeout is reached. After that, the "WaitUntilUp" method will return with an error.
client, _ := New(
WithBaseURL("http://localhost:8081"),
WithAPIKeyAuthentication("secret"),
)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err := client.WaitUntilUp(ctx)
if err != nil {
panic(err)
}
Output:
func New ¶
func New(opt ...ClientOption) (Client, error)
New creates a new PowerDNS client. Various client options can be used to configure the PowerDNS client (see examples).
Example (WithAPIKeyAuthentication) ¶
This example uses with WithAPIKeyAuthentication function to add API-key based authentication to the PowerDNS client.
client, err := New(
WithBaseURL("http://your-dns-server.example:8081"),
WithAPIKeyAuthentication("super-secret"),
)
if err != nil {
panic(err)
}
client.Status()
Output:
Example (WithDebugging) ¶
This example uses the WithDebuggingOutput function; this will cause all HTTP requests and responses to be logged to the io.Writer that is supplied to WithDebuggingOutput.
client, err := New(
WithBaseURL("http://your-dns-server.example:8081"),
WithAPIKeyAuthentication("super-secret"),
WithDebuggingOutput(os.Stdout),
)
if err != nil {
panic(err)
}
client.Status()
Output:
type ClientOption ¶
type ClientOption func(c *client) error
func WithAPIKeyAuthentication ¶
func WithAPIKeyAuthentication(key string) ClientOption
WithAPIKeyAuthentication adds API-key based authentication to the PowerDNS client. In effect, each HTTP request will have an additional header that contains the API key supplied to this function:
X-API-Key: {{ key }}
func WithBaseURL ¶
func WithBaseURL(baseURL string) ClientOption
WithBaseURL sets a client's base URL
func WithBasicAuthentication ¶ added in v0.6.0
func WithBasicAuthentication(username string, password string) ClientOption
WithBasicAuthentication adds basic authentication to the PowerDNS client.
func WithDebuggingOutput ¶
func WithDebuggingOutput(out io.Writer) ClientOption
WithDebuggingOutput can be used to supply an io.Writer to the client into which all outgoing HTTP requests and their responses will be logged. Useful for debugging.
func WithHTTPClient ¶
func WithHTTPClient(httpClient *http.Client) ClientOption
WithHTTPClient can be used to override a client's HTTP client. Otherwise, the default HTTP client will be used
func WithTLSAuthentication ¶
func WithTLSAuthentication(caFile string, clientCertFile string, clientKeyFile string) ClientOption
WithTLSAuthentication configures TLS-based authentication for the PowerDNS client. This is not a feature that is provided by PowerDNS natively, but might be implemented when the PowerDNS API is run behind a reverse proxy.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
apis
|
|
|
cache
Package cache contains a specialized client for interacting with PowerDNS' "Cache" API.
|
Package cache contains a specialized client for interacting with PowerDNS' "Cache" API. |
|
cryptokeys
Package cryptokeys contains a specialized client for interacting with PowerDNS' "Cryptokeys" API.
|
Package cryptokeys contains a specialized client for interacting with PowerDNS' "Cryptokeys" API. |
|
servers
This package contains a specialized client for interacting with PowerDNS' "Servers" API.
|
This package contains a specialized client for interacting with PowerDNS' "Servers" API. |
|
zones
This package contains a specialized client for interacting with PowerDNS' "Zones" API.
|
This package contains a specialized client for interacting with PowerDNS' "Zones" API. |