unifi

README

UniFi for libdns

This package implements the libdns interfaces for UniFi Network, allowing you to manage DNS records through the UniFi Network's DNS policy API.

Supported Record Types

This provider supports the following DNS record types:

• A - IPv4 address records
• AAAA - IPv6 address records
• CNAME - Canonical name (alias) records
• MX - Mail exchange records (Without TTL)
• TXT - Text records (Without TTL)
• SRV - Service records (Without TTL)

Configuration

The provider requires three pieces of configuration:

1. API Key - Your UniFi API authentication key
2. Site ID - The UUID of the UniFi site containing the DNS policies
3. Host URL - The base URL of your UniFi controller API

Example Usage

package main

import (
	"context"
	"log"
	"net/netip"
	"time"

	"github.com/libdns/libdns"
	"github.com/libdns/unifi"
)

func main() {
	provider := unifi.Provider{
		ApiKey:  "your-api-key",
		SiteId:  "your-site-uuid",
		BaseUrl: "https://192.168.1.1/proxy/network/integration/v1",
	}

	// List existing records
	records, err := provider.GetRecords(context.Background(), "example.com")
	if err != nil {
		log.Fatal(err)
	}

	// Add a new A record
	newRecords, err := provider.AppendRecords(context.Background(), "example.com", []libdns.Record{
		libdns.Address{
			Name: "www",
			IP:   netip.MustParseAddr("192.0.2.1"),
			TTL:  3600 * time.Second,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}

Getting Your Credentials

API Key

1. Log into your UniFi Network Console
2. Navigate to Integrations
3. Create a new API Key
4. Set the key as your UNIFI_API_KEY environment variable or use it as ApiKey parameter

Site ID

Execute the following request to retrive the ID of your sites:

curl -k -X GET 'https://YOU_UNIFI_NETWORK_CONTROLLER/proxy/network/integration/v1/sites' -H 'X-API-KEY: YOUR_API_KEY' -H 'Accept: application/json'

Base URL

The base URL is the base path of your UniFi Network API endpoint:

• Default: https://YOU_UNIFI_NETWORK_CONTROLLER/proxy/network/integration/v1 (replace IP with your device IP)
• CloudKey/Controller: https://YOU_UNIFI_NETWORK_CONTROLLER:8443/proxy/network/integration/v1

Documentation

Overview

Package unifi implements a DNS record management client compatible with the libdns interfaces for UniFi

Index

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

Examples

• Provider

Types

type Provider

type Provider struct {
	// ApiKey is the Unifi API authentication key.
	ApiKey string `json:"api_key,omitempty"`

	// SiteId is the UUID of the Unifi site containing the DNS policies.
	SiteId string `json:"site_id,omitempty"`

	// BaseUrl is the base URL of the Unifi controller API.
	// Example: https://192.168.1.1/proxy/network/integration/v1
	BaseUrl string `json:"base_url,omitempty"`
	// contains filtered or unexported fields
}

Provider facilitates DNS record management for Unifi Network. It implements the libdns record management interfaces.

Credentials can be set directly on the struct fields or via environment variables:

Example

ExampleProvider demonstrates basic usage of the unifi provider

package main

import (
	"context"
	"log"
	"net/netip"
	"time"

	"github.com/libdns/libdns"
	"github.com/libdns/unifi"
)

func main() {
	provider := unifi.Provider{
		ApiKey:  "your-api-key",
		SiteId:  "your-site-uuid",
		BaseUrl: "https://192.168.1.1/proxy/network/integration/v1",
	}

	ctx := context.Background()

	// List all records
	records, err := provider.GetRecords(ctx, "example.com")
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("Found %d records\n", len(records))

	// Add a new record
	newRecord := libdns.Address{
		Name: "www",
		IP:   netip.MustParseAddr("192.0.2.1"),
		TTL:  3600 * time.Second,
	}

	created, err := provider.AppendRecords(ctx, "example.com", []libdns.Record{newRecord})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("Created %d records\n", len(created))
}

func (*Provider) AppendRecords

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

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

func (*Provider) DeleteRecords

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

DeleteRecords deletes the specified records from the zone and returns the deleted records.

func (*Provider) GetRecords

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

GetRecords lists all the records in the zone. The zone parameter is not used for Unifi (all records for the site are returned).

func (*Provider) SetRecords

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

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