UniFi Configuration

HEAD'S UP

If you haven't read the primer on name server configuration, you should read that first as this page builds on the information presented there.

What is UniFi?

UniFi is Ubiquiti's line of networking hardware, including Cloud Gateways and Dream Machines that include a built-in DNS server. DockNS can manage DNS records on these devices via the UniFi Network Integration API.

Connector Modes

The UniFi API supports two connection modes. Set host to match the mode you want to use:

Mode	host value
Local	https://<consoleIP> (e.g. https://192.168.1.1)
Remote	https://api.ui.com/v1/connector/consoles/<consoleId>

Local Connector and TLS

Local UniFi controllers use self-signed TLS certificates. DockNS automatically accepts self-signed certificates when connecting to any host other than api.ui.com, so the local connector works without any additional CA configuration.

Finding Your Console ID

The consoleId field that is included in the host value for a Remote UniFi node can be found by logging into https://unifi.ui.com and going to the site you want to connect to. The consoleId is the string in URL between "consoles/" and "/network". For example:

https://morsio.ui.com/consoles/<consoleId>/network/default/settings/settings_overview

Finding Your Site ID

The account_id field identifies which UniFi site DockNS should manage. It accepts a site UUID, a site name, or can be omitted entirely to auto-discover the default site.

account_id value	Behaviour
Omitted or empty	Auto-selects the site with internalReference = default
A site name (e.g. Default)	Fetches the site list and matches by name (case-insensitive)
A UUID	Used directly with no extra API call

When account_id is omitted or empty, DockNS logs every available site and then selects the default:

WARN dockns::name_servers::unifi: available UniFi site site_id="88f7af54-..." name="Default"
WARN dockns::name_servers::unifi: available UniFi site site_id="a1b2c3d4-..." name="Guest Network"
WARN dockns::name_servers::unifi: selected UniFi default site; set account_id to this UUID to skip auto-discovery on startup site_id="88f7af54-..." name="Default"

When account_id is set to a site name, DockNS logs the resolved UUID:

WARN dockns::name_servers::unifi: resolved UniFi site name to UUID; consider using the UUID as account_id directly site_id="88f7af54-..." name="Default"

If you need to look up your site UUID manually, you can query the sites list directly:

curl -sk "https://<consoleIP>/proxy/network/integration/v1/sites" \
  -H "X-API-Key: <api key>" | jq '.data[] | {id, internalReference, name}'

Fields

host string required

The base URL of your UniFi console. See Connector Modes above.

config.toml (local)

[name_servers.unifi_local]
service = "unifi"
host = "https://192.168.1.1"
api_key = "<api key>"
# account_id = "<site UUID>"  # omit to auto-select the default site

config.toml (remote)

[name_servers.unifi_remote]
service = "unifi"
host = "https://api.ui.com/v1/connector/consoles/<consoleId>"
api_key = "<api key>"
# account_id = "<site UUID>"  # omit to auto-select the default site

Environment Variables (local)

DOCKNS_NS_UNIFI_LOCAL_SERVICE=unifi
DOCKNS_NS_UNIFI_LOCAL_HOST=https://192.168.1.1
DOCKNS_NS_UNIFI_LOCAL_API_KEY=<api key>
# DOCKNS_NS_UNIFI_LOCAL_ACCOUNT_ID=<site UUID>  # omit to auto-select the default site

api_key string required

An API key with permission to manage DNS records. You can generate either a remote api_key or a local api_key. The one you should generate depends on if your host is a Local or Remote address. Generate the api_key matching your selection for host.

Remote api_key

1. Log in to https://unifi.ui.com
2. Ensure you are at the Site Manager level and not within a specific site.
3. Navigate to Settings → API Keys.
4. Click Create New API Key, give it a name (e.g. dockns), choose what it can access, and save it.
5. Copy the key — it won't be shown again.

Local api_key

1. Log in to your UniFi console.

2. Log in to your UniFi console.

3. Navigate to Integrations.

4. Click Create New API Key, give it a name (e.g. dockns), and save it.

5. Copy the key — it won't be shown again.

account_id string optional

Identifies the UniFi site to manage. Accepts a site UUID, a site name, or can be left empty to auto-select the default site. See Finding Your Site ID.

Setting this to the site UUID is the most efficient option as it skips the site-list lookup on every startup.

config.toml — UUID (recommended)

[name_servers.unifi_local]
service = "unifi"
host = "https://192.168.1.1"
api_key = "<api key>"
account_id = "88f7af54-98f8-306a-a1c7-c9349722b1f6"

config.toml — site name

[name_servers.unifi_local]
service = "unifi"
host = "https://192.168.1.1"
api_key = "<api key>"
account_id = "Default"

config.toml — auto-discover

[name_servers.unifi_local]
service = "unifi"
host = "https://192.168.1.1"
api_key = "<api key>"

Environment Variables

DOCKNS_NS_UNIFI_LOCAL_SERVICE=unifi
DOCKNS_NS_UNIFI_LOCAL_HOST=https://192.168.1.1
DOCKNS_NS_UNIFI_LOCAL_API_KEY=<api key>
DOCKNS_NS_UNIFI_LOCAL_ACCOUNT_ID=88f7af54-98f8-306a-a1c7-c9349722b1f6