Skip to content

UniFi Network

At the end of this page Ferrule will be reading your gateway, switches and access points.

You need two things from the gateway: an API key and a read-only local admin. Do this on the gateway itself (UDM, UDM-SE, Cloud Gateway), signed in by its IP address. Don't use the mobile app or unifi.ui.com.

On the gateway

  1. Open https://<gateway address> in a browser and sign in.
  2. Go to Settings → Control Plane → Integrations → Create API Key. Name it ferrule and copy the key now. UniFi shows it only once.
  3. Go to Settings → Admins & Users → Add New Admin:
    • tick Restrict to Local Access Only;
    • username telemetry, and a long password;
    • role Read Only;
    • leave two-factor (MFA) off for this account.

In your settings

These four lines are the ones from Install:

UNIFI_HOST=https://192.168.1.1
UNIFI_API_KEY=the key from step 2
UNIFI_USERNAME=telemetry
UNIFI_PASSWORD=the password from step 3

After changing them:

  1. Open the ferrule stack and find Environment variables.
  2. Add or change the lines. In Advanced mode you can paste several at once.
  3. Click Pull and redeploy.
  1. Open .env in the folder where you cloned ferrule-deploy.
  2. Add or change the lines.
  3. Run docker compose up -d in that folder.

How to know it worked

  • The LAN tab lists your switches and access points, and each switch opens to its front panel.
  • The WAN tab shows your internet links.
  • Settings → Sources shows UniFi Network with the access it got.

If it doesn't work

What you see Why, and the fix
login rejected: check the credentials, and that the account is local-only with MFA disabled Usually MFA is on for the account, or it's a UniFi cloud account rather than a local one. Make a local one as in step 3
x509: certificate signed by unknown authority UNIFI_VERIFY_TLS=true is set, but the gateway still has its own certificate. Remove that line
No devices, and the logs say poll: network: The Docker host can't reach UNIFI_HOST. Check the address and that it starts https://
Why both an API key and an account?

UniFi's official API, which uses the key, gives only the basics: CPU, memory, uptime. Fan speeds, port errors, fibre optic readings, PoE and the outage history are only available to a signed-in account. Ferrule tries the key first and signs in only where it has to.

Why MFA has to be off

Ferrule signs in without a person there, so it can't answer a code. The account is local-only and read-only, so it can't be used from the internet or to change anything.

A self-hosted Network controller, not a gateway

Add UNIFI_OS=false, and use the controller's address and port in UNIFI_HOST.