|
| 1 | +This is the provider for [UniFi Network](https://ui.com/), Ubiquiti's network management platform. |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Configuration |
| 6 | + |
| 7 | +To use this provider, add an entry to `creds.json` with `TYPE` set to `UNIFI` along with your connection details. |
| 8 | + |
| 9 | +### Configuration parameters |
| 10 | + |
| 11 | +| Parameter | Required | Description | |
| 12 | +|-----------|----------|-------------| |
| 13 | +| `TYPE` | Yes | Must be set to `UNIFI` | |
| 14 | +| `api_key` | Yes | UniFi API key | |
| 15 | +| `host` | Yes* | Controller address for local access (e.g., `https://192.168.1.1`) | |
| 16 | +| `console_id` | Yes* | Console ID for cloud access via ui.com | |
| 17 | +| `site` | No | Site name (defaults to `default`) | |
| 18 | +| `api_version` | No | API version: `auto`, `new`, or `legacy` (defaults to `auto`) | |
| 19 | +| `skip_tls_verify` | No | Set to `true` to skip TLS certificate verification | |
| 20 | +| `debug` | No | Set to `true` to enable debug output | |
| 21 | + |
| 22 | +*Either `host` or `console_id` is required, but not both. |
| 23 | + |
| 24 | +### Local access example |
| 25 | + |
| 26 | +Use `host` to connect directly to your UniFi controller: |
| 27 | + |
| 28 | +{% code title="creds.json" %} |
| 29 | +```json |
| 30 | +{ |
| 31 | + "unifi": { |
| 32 | + "TYPE": "UNIFI", |
| 33 | + "host": "https://192.168.1.1", |
| 34 | + "api_key": "your-api-key", |
| 35 | + "site": "default" |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | +{% endcode %} |
| 40 | + |
| 41 | +### Cloud access example |
| 42 | + |
| 43 | +Use `console_id` to connect via UniFi Cloud (ui.com): |
| 44 | + |
| 45 | +{% code title="creds.json" %} |
| 46 | +```json |
| 47 | +{ |
| 48 | + "unifi": { |
| 49 | + "TYPE": "UNIFI", |
| 50 | + "console_id": "28704E24-XXXX-XXXX-XXXX-XXXXXXXXXXXX:1234567890", |
| 51 | + "api_key": "your-api-key", |
| 52 | + "site": "default" |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | +{% endcode %} |
| 57 | + |
| 58 | +The `console_id` can be found in the URL when accessing your console via https://unifi.ui.com. |
| 59 | + |
| 60 | +## API versions |
| 61 | + |
| 62 | +UniFi Network has two different DNS APIs. The provider supports both and can auto-detect which one to use. |
| 63 | + |
| 64 | +### Legacy API |
| 65 | + |
| 66 | +- **Availability**: UniFi Network 8.x and later |
| 67 | +- **Endpoint**: `/proxy/network/v2/api/site/{site}/static-dns` |
| 68 | +- **Features**: Basic CRUD operations, update requires delete + create |
| 69 | +- **Record types**: A, AAAA, CNAME, MX, TXT, SRV, NS |
| 70 | + |
| 71 | +### New API |
| 72 | + |
| 73 | +- **Availability**: UniFi Network 10.1+ (currently in Early Access) |
| 74 | +- **Endpoint**: `/proxy/network/integration/v1/sites/{siteId}/dns/policies` |
| 75 | +- **Features**: Full CRUD with native update support |
| 76 | +- **Record types**: A, AAAA, CNAME, MX, TXT, SRV |
| 77 | + |
| 78 | +### Choosing an API version |
| 79 | + |
| 80 | +The `api_version` parameter controls which API to use: |
| 81 | + |
| 82 | +| Value | Behavior | |
| 83 | +|-------|----------| |
| 84 | +| `auto` (default) | Auto-detect: tries new API first, falls back to legacy | |
| 85 | +| `new` | Force new API (requires UniFi Network 10.1+) | |
| 86 | +| `legacy` | Force legacy API (works with UniFi Network 8.x+) | |
| 87 | + |
| 88 | +**Recommendation**: Use `auto` (the default) for maximum compatibility. The provider will automatically use the best available API for your controller version. |
| 89 | + |
| 90 | +{% code title="creds.json" %} |
| 91 | +```json |
| 92 | +{ |
| 93 | + "unifi": { |
| 94 | + "TYPE": "UNIFI", |
| 95 | + "host": "https://192.168.1.1", |
| 96 | + "api_key": "your-api-key", |
| 97 | + "api_version": "auto" |
| 98 | + } |
| 99 | +} |
| 100 | +``` |
| 101 | +{% endcode %} |
| 102 | + |
| 103 | +## Metadata |
| 104 | + |
| 105 | +This provider does not recognize any special metadata fields unique to UniFi. |
| 106 | + |
| 107 | +## Usage |
| 108 | + |
| 109 | +An example configuration: |
| 110 | + |
| 111 | +{% code title="dnsconfig.js" %} |
| 112 | +```javascript |
| 113 | +var REG_NONE = NewRegistrar("none"); |
| 114 | +var DSP_UNIFI = NewDnsProvider("unifi"); |
| 115 | + |
| 116 | +D("example.lan", REG_NONE, DnsProvider(DSP_UNIFI), |
| 117 | + A("server", "192.168.1.10"), |
| 118 | + AAAA("server", "fd00::10"), |
| 119 | + CNAME("www", "server.example.lan."), |
| 120 | + MX("@", 10, "mail.example.lan."), |
| 121 | + TXT("@", "v=spf1 mx -all"), |
| 122 | + SRV("_http._tcp", 0, 0, 80, "server.example.lan."), |
| 123 | +); |
| 124 | +``` |
| 125 | +{% endcode %} |
| 126 | + |
| 127 | +## Activation |
| 128 | + |
| 129 | +To create an API key for DNSControl: |
| 130 | + |
| 131 | +1. Log in to your UniFi controller |
| 132 | +2. Navigate to **Settings** > **Admins & Users** |
| 133 | +3. Click on your user profile or create a dedicated API user |
| 134 | +4. Generate an API key with appropriate permissions |
| 135 | +5. Copy the API key to your `creds.json` |
| 136 | + |
| 137 | +For cloud access, you can also generate API keys at https://unifi.ui.com under your account settings. |
| 138 | + |
| 139 | +## Supported record types |
| 140 | + |
| 141 | +| Type | Legacy API | New API | |
| 142 | +|------|------------|---------| |
| 143 | +| A | Yes | Yes | |
| 144 | +| AAAA | Yes | Yes | |
| 145 | +| CNAME | Yes | Yes | |
| 146 | +| MX | Yes | Yes | |
| 147 | +| TXT | Yes | Yes | |
| 148 | +| SRV | Yes | Yes | |
| 149 | +| NS | Yes | No | |
| 150 | + |
| 151 | +## Limitations |
| 152 | + |
| 153 | +### No zone concept |
| 154 | + |
| 155 | +UniFi Network stores DNS records flat, without the concept of zones. DNSControl filters records by domain suffix to simulate zone management. This means: |
| 156 | + |
| 157 | +- `dnscontrol get-zones` is not supported |
| 158 | +- Creating new domains is not supported (records are added directly) |
| 159 | + |
| 160 | +### Wildcard CNAMEs |
| 161 | + |
| 162 | +UniFi does not support wildcard CNAME records. Attempting to create a `*.example.com` CNAME will result in an error. |
| 163 | + |
| 164 | +### TTL handling |
| 165 | + |
| 166 | +- If TTL is not specified, the provider uses a default of 300 seconds |
| 167 | +- TTL support varies by record type in the legacy API (MX and TXT records may ignore TTL) |
| 168 | + |
| 169 | +### Self-signed certificates |
| 170 | + |
| 171 | +If your UniFi controller uses a self-signed certificate, set `skip_tls_verify` to `true`: |
| 172 | + |
| 173 | +{% code title="creds.json" %} |
| 174 | +```json |
| 175 | +{ |
| 176 | + "unifi": { |
| 177 | + "TYPE": "UNIFI", |
| 178 | + "host": "https://192.168.1.1", |
| 179 | + "api_key": "your-api-key", |
| 180 | + "skip_tls_verify": "true" |
| 181 | + } |
| 182 | +} |
| 183 | +``` |
| 184 | +{% endcode %} |
| 185 | + |
| 186 | +### Concurrent operations |
| 187 | + |
| 188 | +The provider does not support concurrent API operations. Changes are applied sequentially to ensure reliability. |
0 commit comments