UniFi Network provider for octoDNS

An octoDNS provider for managing local DNS on UniFi Network controllers.

Installation

Command line

pip install octodns-unifi

requirements.txt/setup.py

Pinning specific versions or SHAs is recommended to avoid unplanned upgrades.

Versions

# Start with the latest versions and don't just copy what's here
octodns==1.16.0
octodns-unifi==1.1.3

SHAs

# Start with the latest/specific versions and don't just copy what's here
-e git+https://git@github.com/octodns/octodns.git@9da19749e28f68407a1c246dfdf65663cdc1c422#egg=octodns
-e git+https://git@github.com/netshad0w/octodns-unifi.git@9da63f00309d76bfa94001c0cfdc0c594a647b97#egg=octodns_unifi

Configuration

Requires UniFi Network 10.1+, the integration API (v1), and an API key.

providers:
  unifi:
    class: octodns_unifi.UnifiProvider
    # Controller hostname or IP (local access)
    host: unifi.example.com
    # API key from UniFi controller settings
    api_key: env/UNIFI_API_KEY
    # Site name (defaults to 'default')
    site: default
    # SSL verification (defaults to true). Set to false to disable it, or
    # point it at a CA bundle (e.g. /etc/ssl/internal-ca.crt) to trust a
    # self-signed/internal certificate without turning verification off.
    verify_ssl: true
    # Console ID for cloud access via api.ui.com (see below)
    # console_id: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:123456"
    # TTL in seconds (defaults to 300)
    default_ttl: 300
    # Explicit zone list, useful for multi-label TLDs (co.uk, com.au)
    # When omitted, zones are guessed from the last two labels of each
    # record (e.g. host.example.com -> example.com)
    # zones:
    #   - example.com.
    #   - internal.example.

Cloud access

You can manage DNS through the Ubiquiti cloud API instead of connecting directly to the controller. Set console_id to your console's ID, which you can grab from the URL at unifi.ui.com (https://unifi.ui.com/consoles/<console_id>/...).

host is still required but gets ignored when console_id is set.

providers:
  unifi:
    class: octodns_unifi.UnifiProvider
    host: unused
    api_key: env/UNIFI_API_KEY
    site: default
    console_id: env/UNIFI_CONSOLE_ID

Support Information

Records

Limitations

Custom TTL values only work for A, AAAA, and CNAME records. For MX, TXT, and SRV, the controller manages the TTL and any octodns value is ignored.

Zone auto-detection infers zones from the last two labels of each domain (e.g. example.com). If you use multi-label TLDs like co.uk or com.au, set zones explicitly in the provider config.

Dynamic

UnifiProvider does not support dynamic records.

Development

See the /script/ directory for some tools to help with the development process. They generally follow the Script to rule them all pattern. Most useful is ./script/bootstrap which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.