# UniFi Network

This is the provider for [UniFi Network](https://ui.com/), 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:

{% code title="creds.json" %}

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

{% endcode %}

#### Cloud access example

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

{% code title="creds.json" %}

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

{% endcode %}

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.

{% code title="creds.json" %}

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

{% endcode %}

### Metadata

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

### Usage

An example configuration:

{% code title="dnsconfig.js" %}

```javascript
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."),
);
```

{% endcode %}

### 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`:

{% code title="creds.json" %}

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

{% endcode %}

#### Concurrent operations

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