Should be able to edit DNS records even if headscale configuration is read only

[debtquity]

Description

Problem

I would like to see support for editable DNS records via headplane.

At the moment, my headscale instance and configuration is managed via NixOS module. So I would like to keep the headscale configuration read only. However, I have configured dns.extra_records_path to point to a read/write location on disk.

# ls -hal /var/lib/headscale/extra_dns_records.json
-rw-rw---- 1 headscale headscale 66 Aug 22 23:00 /var/lib/headscale/extra_dns_records.json

# cat /var/lib/headscale/extra_dns_records.json
[{"Name":"init.example.com","Type":"A","Value":"100.64.1.2"}]

Path is accessible by the headplane process and observe this in logs:

# journalctl -u headplane
...
Aug 22 22:26:33 ... headplane[140794]: {"level":"warn","timestamp":"2026-08-22T22:26:33.341Z","pid":140794,"hostname":"...","component":"config","msg":"Headscale configuration file at /nix/store/9cybgwk1dycrqnsl3030ks73i9v8r3yj-headscale.yaml is not writable"}
Aug 22 22:26:33 ... headplane[140794]: {"level":"info","timestamp":"2026-08-22T22:26:33.373Z","pid":140794,"hostname":"...","component":"config","msg":"Found a valid Headscale DNS file at /var/lib/headscale/extra_dns_records.json"}
...

However, on the actual instance itself it's not loading the DNS record(s) in file and not able to add records via headplane web interface.

Workaround(s)

use dummy headscale configuration

1. Make copy of generated headscale configuration that exists in /nix/store/...
2. Set services.headplane.settings.headscale.config_path to point to copy of headscale configuration
3. Rebuild system

The drawback here is that UI is misleading and indicates other configurable options (dns nameservers) can be changed. Only DNS records are modifiable here.

Other Issue

At least for my instance, records not added via headplane are not visible in the UI.

[pullfrog]

Analysis

This is actionable and really two related bugs in the DNS-records flow.

Bug 1 (title): records can't be edited when the Headscale config is read-only. Headplane gates all DNS editing on headscaleConfig.writable(), which reflects access to the main config.yaml. When that file lives in a read-only location (e.g. the NixOS store, /nix/store/...), writable() is false even though dns.extra_records_path points at a fully writable sidecar JSON file. The sidecar file already has its own access tracking (HeadscaleDNSConfig in app/server/headscale/config-dns.ts, whose writable() is correctly true here), but that state is never surfaced to the UI or to the actions:

• app/routes/dns/overview.tsx:43 returns writable: headscaleConfig.writable() and disables ManageRecords (and every other DNS control) when it's false.
• app/routes/dns/dns-actions.ts:26 returns 403 for every action — including add_record/remove_record — when headscaleConfig.writable() is false.

Note that config-loader.ts's addDNS/removeDNS already route through config.dns and check config.dns.writable(), so the backend plumbing is correct; only the UI/action guard is wrong.

Bug 2 ("Other Issue"): pre-existing records in the sidecar file aren't displayed. config-dns.ts:loadConfigFile() does JSON.parse(data) as DNSRecord[] with no validation or key normalization. Headscale (Go encoding/json) unmarshals records case-insensitively, so a file with capitalised keys — exactly what the reporter has: [{"Name":"init.example.com","Type":"A","Value":"100.64.1.2"}] — is valid to Headscale but renders as empty rows in Headplane, which reads strict lowercase name/type/value.

Plan

1. Expose DNS-records-specific access on HeadscaleConfig (app/server/headscale/config-loader.ts)

Add dnsWritable() (and a dnsReadable() if cheap) to the HeadscaleConfig interface + factory, returning:

• state.dns.writable() when the sidecar file is in use (extra_records_path set), else
• writable(state) (records are inline in config.yaml).

2. Thread the flag through the DNS UI (app/routes/dns/overview.tsx, components/manage-records.tsx)

• Add dnsWritable to the loader result; keep writable for the other controls (nameservers, domains, magic DNS, override) which genuinely live in config.yaml.
• Drive ManageRecords's isDisabled from dnsWritable instead of writable, so records stay editable while the rest of the page is read-only. Adjust the read-only Notice so it doesn't imply records are also locked.

3. Relax the action guard (app/routes/dns/dns-actions.ts)

Replace the single top-level writable() check with per-action guards:

• add_record / remove_record: require headscaleConfig.dnsWritable().
• all other actions (rename_tailnet, toggle_magic, add_ns, remove_ns, add_domain, remove_domain, override_dns): keep requiring headscaleConfig.writable().

4. Normalize record keys on load (app/server/headscale/config-dns.ts)

In loadConfigFile, map each parsed entry into { name, type, value } accepting both lowercase and capitalised (Name/Type/Value) keys (case-insensitive match), and validate with valibot (dnsRecordsSchema-shaped) so malformed entries are rejected. Confirm the existing lowercase write format remains correct for Headscale.

5. Tests (tests/unit/headscale/config-loader.test.ts / new config-dns.test.ts)

• Inline mode: dnsWritable() mirrors writable().
• Sidecar mode with chmod-read-only config.yaml + writable records file: dnsWritable() is true, and addDNS/removeDNS succeed and persist only to the sidecar file.
• Sidecar file with capitalised keys loads and surfaces name/type/value.

6. Docs

Clarify in the install/DNS docs that DNS records remain editable when config.yaml is read-only as long as dns.extra_records_path points to a writable file; add a CHANGELOG line.

No changes are needed to settings/* (those gate OIDC/restrictions, which do live in config.yaml).

Task list (2/2 completed)

• Analyze issue Should be able to edit DNS records even if headscale configuration is read only #615 and gather codebase context
• Produce structured plan and report via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[linear-code]

HP-578