UniFi Network

This is the provider for UniFi Network, Ubiquiti's network management platform.

UniFi Network includes a local DNS server that can be managed via its API. This provider allows DNSControl to manage DNS records on your UniFi Network controller.

Configuration

To use this provider, add an entry to creds.json with TYPE set to UNIFI along with your connection details.

Configuration parameters

Parameter	Required	Description
TYPE	Yes	Must be set to UNIFI
api_key	Yes	UniFi API key
host	Yes*	Controller address for local access (e.g., https://192.168.1.1)
console_id	Yes*	Console ID for cloud access via ui.com
site	No	Site name (defaults to default)
api_version	No	API version: auto, new, or legacy (defaults to auto)
skip_tls_verify	No	Set to true to skip TLS certificate verification
debug	No	Set to true to enable debug output

*Either host or console_id is required, but not both.

Local access example

Use host to connect directly to your UniFi controller:

creds.json

{
  "unifi": {
    "TYPE": "UNIFI",
    "host": "https://192.168.1.1",
    "api_key": "your-api-key",
    "site": "default"
  }
}

Cloud access example

Use console_id to connect via UniFi Cloud (ui.com):

creds.json

{
  "unifi": {
    "TYPE": "UNIFI",
    "console_id": "28704E24-XXXX-XXXX-XXXX-XXXXXXXXXXXX:1234567890",
    "api_key": "your-api-key",
    "site": "default"
  }
}

The console_id can be found in the URL when accessing your console via https://unifi.ui.com.

API versions

UniFi Network has two different DNS APIs. The provider supports both and can auto-detect which one to use.

Legacy API

• Availability: UniFi Network 8.x and later

• Endpoint: /proxy/network/v2/api/site/{site}/static-dns

• Features: Basic CRUD operations, update requires delete + create

• Record types: A, AAAA, CNAME, MX, TXT, SRV, NS

New API

• Availability: UniFi Network 10.1+ (currently in Early Access)

• Endpoint: /proxy/network/integration/v1/sites/{siteId}/dns/policies

• Features: Full CRUD with native update support

• Record types: A, AAAA, CNAME, MX, TXT, SRV

Choosing an API version

The api_version parameter controls which API to use:

Value	Behavior
auto (default)	Auto-detect: tries new API first, falls back to legacy
new	Force new API (requires UniFi Network 10.1+)
legacy	Force legacy API (works with UniFi Network 8.x+)

Recommendation: Use auto (the default) for maximum compatibility. The provider will automatically use the best available API for your controller version.

creds.json

{
  "unifi": {
    "TYPE": "UNIFI",
    "host": "https://192.168.1.1",
    "api_key": "your-api-key",
    "api_version": "auto"
  }
}

Metadata

This provider does not recognize any special metadata fields unique to UniFi.

Usage

An example configuration:

dnsconfig.js

var REG_NONE = NewRegistrar("none");
var DSP_UNIFI = NewDnsProvider("unifi");

D("example.lan", REG_NONE, DnsProvider(DSP_UNIFI),
    A("server", "192.168.1.10"),
    AAAA("server", "fd00::10"),
    CNAME("www", "server.example.lan."),
    MX("@", 10, "mail.example.lan."),
    TXT("@", "v=spf1 mx -all"),
    SRV("_http._tcp", 0, 0, 80, "server.example.lan."),
);

Activation

To create an API key for DNSControl:

1. Log in to your UniFi controller

2. Navigate to Settings > Admins & Users

3. Click on your user profile or create a dedicated API user

4. Generate an API key with appropriate permissions

5. Copy the API key to your creds.json

For cloud access, you can also generate API keys at https://unifi.ui.com under your account settings.

Supported record types

Type	Legacy API	New API
A	Yes	Yes
AAAA	Yes	Yes
CNAME	Yes	Yes
MX	Yes	Yes
TXT	Yes	Yes
SRV	Yes	Yes
NS	Yes	No

Limitations

No zone concept

UniFi Network stores DNS records flat, without the concept of zones. DNSControl filters records by domain suffix to simulate zone management. This means:

• dnscontrol get-zones is not supported

• Creating new domains is not supported (records are added directly)

Wildcard CNAMEs

UniFi does not support wildcard CNAME records. Attempting to create a *.example.com CNAME will result in an error.

TTL handling

• If TTL is not specified, the provider uses a default of 300 seconds

• TTL support varies by record type in the legacy API (MX and TXT records may ignore TTL)

Self-signed certificates

If your UniFi controller uses a self-signed certificate, set skip_tls_verify to true:

creds.json

{
  "unifi": {
    "TYPE": "UNIFI",
    "host": "https://192.168.1.1",
    "api_key": "your-api-key",
    "skip_tls_verify": "true"
  }
}

Concurrent operations

The provider does not support concurrent API operations. Changes are applied sequentially to ensure reliability.