Skip to content

Design: UniFi client alias

See openspec/changes/archive/2026-10-19-unifi-client-alias/proposal.md for the reason and the scope. The spec is openspec/specs/unifi-client-alias/spec.md.

The parts of the estate that this design touches:

  • The store holds 41 curated entries on 2026-10-17, and 24 of them hold a MAC. The column entries.mac is a nullable macaddr with a UNIQUE constraint, so two entries never hold one MAC. entries.Entry normalises a MAC to the lower-case colon form. ShortHostname() gives the first label of the hostname, for example pdu for pdu.fzymgc.house..
  • The UniFi Network application runs on the UCG-Fiber at https://unifi.fzymgc.house, with the site default. The collection rest/user holds every client that the controller knows, also a client that is offline. Spike 012 read 203 clients on 2026-10-17. 21 of them hold name, and no client holds note.
  • apps/dns-control/internal/unifi reads only stat/sta, with the account dns-control-observer and the role Network View Only. It logs in with POST /api/auth/login, keeps the session cookie and sends no CSRF token. dns-control writes nothing to the controller today.
  • observed-aaaa-sweep is the one Temporal Schedule of dns-control. observed.EnsureSchedule creates it at start, or updates its interval, overlap policy (SKIP), catch-up window and paused state. Its activities take and return protobuf messages of observedv1. Its status is one row in the table observed_sweep, and GET /api/health, dns_get_health and ObservedAAAA.svelte show that row.
  • dns-control decodes its configuration strictly. An unknown key in the file and an unknown DNS_CONTROL_* variable both stop the start.
  • The secret secret/fzymgc-house/cluster/dns-control holds unifi_username and unifi_password of the observer. The policy of External Secrets reads cluster/*. The network policy of dns-control already allows 192.168.40.1/32 on port 443.
  • The lineage mark of dns-control on a pdns RRset is writer=dns-control change=<uuid>, matched by an anchored regular expression in internal/lineage/marks.go.

This change allocates no address and no prefix, so docs/reference/network.md does not change. No Terraform resource changes, and the collection user stays at the tier never.

Goals:

  • The comparison converges. Each run computes the whole difference from the store and the controller. The next run heals a missed run, a restart or the edit of a person.
  • dns-control changes two keys of a client and no other key.
  • A run that cannot read both sides writes nothing.
  • The set of clients that no entry holds comes out of the comparison as a value, so a later change can store it.

Non-Goals:

  • A write when an entry changes. The Schedule alone carries a change to the controller, within one interval.
  • An audit row in the store for a write to the controller.
  • An alert for a stalled comparison. Decision 9 explains this.
  • A site other than default.

Decision 1: The spike decides the write, and the design stops on a failed item

Section titled “Decision 1: The spike decides the write, and the design stops on a failed item”

The proposal names three unknowns of the controller. Decision 6 settles the third one, the role. The spike under Spike below measures the other two. Decisions 5 and 7 name a default and a fallback for each result. If no write keeps the other keys of a client, the design stops and comes back to Sean with the result.

Decision 2: The comparison runs as the Temporal Schedule unifi-client-alias

Section titled “Decision 2: The comparison runs as the Temporal Schedule unifi-client-alias”

A second Schedule, unifi-client-alias, starts the workflow unifi_alias.sync at each interval, 15 minutes by default. It has the same overlap policy and catch-up window as the sweep, and it is paused while unifi_alias.enabled is false. EnsureSchedule moves out of internal/observed into a helper that both Schedules call, so both keep the same policy.

Alternative: a goroutine with a ticker, like the lineage refresh. It loses the pause, the run history and the overlap policy that the Schedule gives, and the proposal names a Schedule.

Decision 3: One activity reads, compares and writes

Section titled “Decision 3: One activity reads, compares and writes”

The workflow runs one activity, unifi_alias.run, with one attempt. The activity:

  1. reads every entry from the store,
  2. logs in with the writer account and reads rest/user,
  3. runs the comparison of Decision 4,
  4. sends the writes and clears,
  5. records the outcome in the status row of Decision 8.

It takes an empty input and returns the counts as a protobuf message of proto/dnscontrol/unifialias/v1, as the payload rule of the repository asks. No client record enters the workflow history.

Alternative: the read, the comparison and the write as separate activities, like the sweep. The sweep plans its writes through the change service, so it needs the read in the workflow. This comparison writes from a read that ages with every second in the history. Also, the client records do not belong in the history.

Decision 4: The comparison is one pure function

Section titled “Decision 4: The comparison is one pure function”

Compare(entries, clients) joins the entries that hold a MAC with the clients on the MAC in the lower-case colon form. It returns four sets:

Set Holds The run
writes each client that an entry holds, whose name is not the first label of the hostname of the entry, or whose note is not the mark of the entry sends one write
clears each client whose note carries a mark and whose MAC no entry holds sends one clear
unknown the key of each entry whose MAC no client holds records it in the status row
unclaimed each client whose MAC no entry holds and whose note carries no mark drops it

A client in no set gets no request. The unclaimed set is the set that a later change can store and show.

Decision 5: The mark is writer=dns-control entry=<key>

Section titled “Decision 5: The mark is writer=dns-control entry=<key>”

The note of a curated client is exactly writer=dns-control entry=<key>. The regular expression ^writer=dns-control entry=[a-z0-9_]{1,64}$ decides whether a note carries the mark. The form follows the lineage mark. The key, not the hostname, names the entry, because a change of the hostname keeps the key.

The note of a curated client belongs to dns-control, as its alias does. A note that a person writes on a curated client goes at the next run. The comment of the entry is the place for a description of the device. The baseline of the spike counts the clients that hold a note today.

Alternative: track the written MACs in a table of dns-control. A restore of the store or of the controller then separates the table from the controller. The note keeps the proof of ownership on the object that it describes, and a person sees it in the UniFi UI.

Decision 6: The writer account dns-control-writer

Section titled “Decision 6: The writer account dns-control-writer”

dns-control writes with a new local UniFi OS account, dns-control-writer. The account reads rest/user and writes the client. The account dns-control-observer keeps the role Network View Only and keeps the sweep.

The name is the job of the account, not this one feature. A later write of dns-control to the controller uses the same account.

Sean created the account on 2026-10-17 with the role Network Admin. GET /api/users/self as the account reads network.management: ["admin"] and system.management.user: ["readonly"]. The View Only account reads network.management: ["readonly"]. The console offers no Network role between the two, so Network Admin is the narrowest role that can rename a client. It is also the Network right of automation-admin: the account can change every network, firewall rule and port of the site.

The controller therefore does not confine the account, and dns-control does:

  • The writer client in internal/unifi has one write, SetAlias, with the fixed path rest/user/<_id>. A test records every request of the client and fails on any other method or path.
  • The admin activity log of the controller names the account for each change. The spec requirement “The writer account changes clients only” reads that log.
  • The credential reaches only the namespace dns-control.

Alternative: reuse dns-control-observer with the role Network Admin. The sweep then runs with write rights that it never uses, and one credential carries both jobs.

The credential lives in the existing secret secret/fzymgc-house/cluster/dns-control, in the new fields unifi_writer_username and unifi_writer_password. The External Secrets policy already reads cluster/*, so no Vault policy changes. The operator adds the fields with vault kv patch, because vault kv put replaces every field of the secret.

The configuration keys are unifi_alias.enabled, unifi_alias.interval, unifi.writer_username and unifi.writer_password. The Deployment maps the two secret fields to DNS_CONTROL_UNIFI__WRITER_USERNAME and DNS_CONTROL_UNIFI__WRITER_PASSWORD. The run reads unifi.url as the sweep does.

The client of internal/unifi gains three parts:

  • The CSRF token. It reads X-CSRF-Token from the login answer and X-Updated-CSRF-Token from each later answer, and sends X-CSRF-Token on each write, as scripts/unifi_session.py does.
  • Users, which reads rest/user. It refuses a record with no _id or no mac, and takes name and note as optional.
  • SetAlias, which sends the write of one client.

The write is PUT /proxy/network/api/s/default/rest/user/<_id> with a body of exactly name and note. The Go struct of the body names those two keys and no other. A clear sends both as "". Spike 012 measured this form on Network 10.6.106:

  • The controller merges the body into the record. A write changes name, note and noted, and keeps every other key, also fixed_ip and network_members_group_ids.
  • A clear stores "" and does not remove a key. noted is true while name is not empty, and false after a clear.
  • The UI writes the same path with a partial body too. The inline rename sends name and display_name, and the client panel sends the eleven values of its form.

So Users reads an absent name or note as "", and the comparison of Decision 4 compares those values. The fallback of a whole-record write is not needed.

Each run logs in once with the writer account. The first failed write ends the run with the outcome failed, and the next run sends the remaining writes again. Each write and each clear logs one line with the MAC, the client id, the old values and the new values.

Decision 8: The status row and the health reading

Section titled “Decision 8: The status row and the health reading”

A migration adds the one-row table unifi_alias_run with last_good_run_at, last_error_at, last_error, written, cleared and unknown (a text[] of entry keys). GET /api/health and dns_get_health show it as unifi_alias, with the field status:

status When
ok the last run ended without an error
failing the last run ended with an error
paused unifi_alias.enabled is false
not_run no run ended yet

The Health screen shows the row in a card next to the card of the observed AAAA sweep, with the unknown keys as a list. The record index tile does not read it.

A run writes nothing when one of these holds, and records the reason as its error:

  • The login fails.
  • The read of rest/user fails.
  • rest/user holds no client.
  • The read of the store fails.
  • The store holds no entry with a MAC.

The last guard keeps a fault in the store read from clearing every alias that dns-control wrote.

An alias that is one hour old harms no service and asks no person to act at once. The card on the Health screen shows a run that stopped. So the stalled loop alert of dns-control-alerting does not cover the Schedule, and that capability gets no delta.

Alternative: a gauge dns_control_unifi_alias_run_timestamp_seconds and a tile alert below one per hour, like the sweep. Sean can add both later without a change of the comparison.

The change model of dns-control plans and applies writes to pdns, with one step for each node. A write to the controller fits none of it. The log line of Decision 7 goes to ClickStack. The system log of UniFi OS also records each change of a client with the name of the account.

Alternative: a change subject unifi_alias with a row in change_audit for each run that writes. That adds a subject, a plan with no step and an export rule for a display name.

The spike runs from a workstation against the live controller. Items S1 and S2 only read. Item S3 writes one alias and one note, and it needs a go from Sean in the session before it runs. Item S4 sends one write that the controller refuses. Each item ends with a command that passes or fails, and each verdict carries a control. About eight UniFi OS logins in a few minutes return HTTP 429, so the wrapper logs in once for each item.

Item Question Pass
S1 What does the UI send for a rename, a removal of the alias and a note? Read the submit handler in the JavaScript bundle of Network 10.6 offline The README quotes the method, the path and the body keys of each of the three requests, with the bundle file and the version
S2 Baseline. Which of the 24 MACs does the controller know? Which curated clients hold an alias or a note today, and which client holds a note at all? The README lists each set from one --for-diff dump with the View Only account
S3 Does PUT rest/user/<_id> with name and note alone keep every other key? Is the same true for a clear? A --for-diff dump before and after each write differs only in name, note and noted. The control: a rename in the UI of the same client, diffed the same way. The sensitivity check: a dump with one deliberate edit to another key in a scratch copy shows in the diff
S4 Do the two accounts hold the rights of Decision 6? GET /api/users/self as dns-control-writer reads the permissions of Decision 6 and no other key, and dns-control-observer is refused the rename of S3. The control: the same rename as dns-control-writer succeeds in S3

S3 writes on the client of the entry pdu, whose alias is a display name only, and puts the alias back at the end.

Spike 012 (.planning/spikes/012-unifi-client-rename/) passed all four items on 2026-10-17 against Network 10.6.106.

Item Reading
S1 Both UI writes of a client use PUT rest/user/<_id> with a partial body. The inline rename sends name and display_name. The client panel sends its eleven form values, note among them, and refuses an empty name
S2 203 clients, and none holds a note. noted marks the 21 clients with an alias. 20 of the 24 curated MACs are known, and nas, seattle, doorsportal1 and gh_runner are not. powerwall holds the alias tesla-powerwall, which a person set
S3 A write of name and note changes those keys and noted only, on pdu and on a client with fixed_ip and a client group. A clear stores "" and sets noted to false. A rename in the client panel adds the defaults of its form
S4 The writer reads the permissions of Decision 6 and no other key. The observer reads network.management: ["readonly"] and gets HTTP 403 for a rename

The results change Decision 7 and touch task 3.1: Users reads an absent name or note as "".

  • [A partial write drops a key of the client] → S3 measured it before any code. The spec requirement “A write changes only the alias and the note” repeats the dump diff after the first run.
  • [A later Network version changes how a write merges] → The runbook repeats the dump diff after each Network upgrade.
  • [A person’s note on a curated client goes at the next run] → S2 found no note on any client. The runbook says that the entry comment holds the description of a device.
  • [The first run replaces an alias that a person set] → S2 found one, tesla-powerwall on the client of powerwall. The first run writes powerwall. To keep another name, change the hostname of the entry before the switch of task 5.2.
  • [A device with a private Wi-Fi address shows another MAC] → The entry appears in the unknown list. The operator then fixes the MAC of the entry or the setting of the device.
  • [The UniFi OS login rate limit] → One login for each run, every 15 minutes. A refused login fails the run, and the next run tries again.
  • [A fault clears every alias] → A run clears only a client with the mark. A run with no entry that holds a MAC writes nothing.
  • [The writer credential leaks, or dns-control writes another object] → The account can change every Network object of the site (Decision 6). The one write path of the client, its request test and the admin activity log limit and show what dns-control sends. If the credential leaks, Sean changes its password on the console and in Vault with vault kv patch.

The pull requests follow the split of proposal.md. One step moves. Sean created the account dns-control-writer before the spike, because S3 and S4 measure that account. Pull request 2 then only maps the secret into the cluster. No pull request touches routing or DNS.

  • Pull request 1 is the spike. It writes one alias and one note, and puts both back.

  • Pull request 2 adds the two fields to the ExternalSecret only. The Deployment does not map them yet, because the running release refuses an unknown DNS_CONTROL_* variable. Rollback: git revert of the merge commit and an ArgoCD sync of dns-control.

  • Pull requests 3 and 4 are the code and its release. They change nothing live.

  • Pull request 5 is the updater pull request of the release. Its branch gets unifi_alias.enabled: true and the two variables of the Deployment before the merge, as docs/operations/releases.md says. Rollback: a pull request that sets unifi_alias.enabled: false. Reloader restarts the pod, and the Schedule pauses. The aliases stay, and they still name the right devices. To remove them, a person clears each alias and note in the UniFi UI. This command lists the clients to clear:

    Terminal window
    scripts/unifi-readonly.sh scripts/unifi-inventory.py /tmp/alias.unifi-dump > /dev/null
    jq -r '.[] | select((.note // "") | test("^writer=dns-control entry=")) | [.mac, .name] | @tsv' /tmp/alias.unifi-dump/user.json
  • If the account goes away, Sean deletes dns-control-writer on the console. The two fields in Vault then hold a credential that no longer logs in.