Web UI

goethite serves a web UI next to its REST API, on the same addresses. On the machine running goethite, open:

http://127.0.0.1:8053/

It shows what goethite is doing and changes everything the REST API can: lists, rules, local records, groups, clients, schedules and settings.

A node with no admin token and no users answers loopback only and needs no sign-in; once a user account exists, loopback clients sign in too. Reach a fresh node from another machine through an SSH tunnel, then open http://localhost:8053/:

ssh -L 8053:127.0.0.1:8053 dns.example.lan

Everyone else signs in with a user name and password (see Users and sign-in). Create the first user before reaching the node, since goethite holds its store file locked while it runs:

goethite user add --config /etc/goethite/goethite.toml admin

It prints a generated password once. The sign-in may ask for a six-digit code too, when the account has a second factor: set one up under Account, together with recovery codes for the day the authenticator app is lost (they are shown once, when the second factor is turned on). Sessions last twelve hours, end on sign-out, and end on every node when the account's password, role or new second factor changes. An admin can issue a one-time reset link under Users; it opens a page that sets a new password once, and ends every session of that user. Serve the API over HTTPS (tls_cert and tls_key) when you use it across the network; otherwise passwords cross it in clear text.

• Dashboard: the last 24 hours, 7 days or 30 days (queries, blocked, cached, forwarded, failed, average answer time), a chart of queries per hour, 6 hours or day, the top blocked names, names and clients, each upstream's health (a Recursion panel instead when the node resolves from the root down: queries sent, TCP, timeouts, unresolved, DNSSEC secure, insecure and bogus, zones and servers), the filter and its lists, and the node's cache and query log. Everything leads to its queries: a tile opens the query log for that answer, a name or client in a top list for that name or client, and a bar of the chart (hover or focus it for its counts) for its time window. A top blocked name can be allowed, and a top name blocked, in two clicks: that adds a custom rule. The range is part of the address. The header shows whether filtering is on, and pauses it for 10 minutes or resumes it. In a cluster, the counts are every node's together, the header shows what this node does in the cluster and how many members are up, a Cluster panel shows the cluster's health, the leader and each member, and cluster problems appear at the top.
• Cluster, only on a node in a cluster: see below.
• Query log: the newest queries, following new ones live, with the client, the answer and what decided it (the rule, a CNAME, the upstream). Search by name and by answer, and page back through older entries. Filters set from the dashboard (a client, a time window) show as chips to remove. Searches are part of the address, so they can be bookmarked.
• Lists: every filter list with its rule count, the lines it skipped and any problem, and a button to download them all again now. A new list can join the default group at once, so it filters straight away. Recommended lists are shown by category with their sizes and add in a click; presets set a group's lists in one step after showing what changes; lists that do the same job switch rather than stack; and Find lists searches the FilterLists directory.
• Rules: custom rules, added from the top of the page, filtered as you type, turned on and off in place. goethite explains a rule it cannot use.
• Records: local DNS records, added from the top of the page and turned on and off in place.
• Groups: which lists and blocked services filter a group's clients, each always or during a schedule, and safe search.
• Clients: devices and networks by address or client ID, and their group. With an ID, the editor shows the DNS over HTTPS URL and the DNS over TLS and QUIC names to set the device up with.
• Schedules: weekly windows in a time zone; a window can run past midnight.
• Audit log: who changed what, from where, with the resource before and after.
• Leak test: whether this device's lookups reach goethite, over which protocol and as which client, or go to another resolver past its filtering, with the tests of the last hour from any device under Recent tests; see DNS leak test.
• Users (admins): add users, give them the viewer role, issue one-time password reset links, set passwords, disable accounts.
• Account: change your password, set up or remove a TOTP second factor, see how many recovery codes are left (the codes themselves are shown once, when the second factor is turned on).
• Settings, in the header behind the account button (a person icon), with Account and Sign out: filtering on or off, how blocked names are answered (including an address of your own), how long blocked answers are kept, how often lists are downloaded, and who may use goethite: the allowed and blocked clients (see access control). Empty the cache makes the next query for a name reach the upstreams again. It also shows the running version; Check for updates asks GitHub for the newest release and says whether this node runs it, and installs nothing.

Changes are made with the revision you saw: if someone else changed the same thing meanwhile, the UI says so and offers their version instead of overwriting it. A list, schedule or group that something still uses says what: deleting a list takes it out of the groups that use it, while a schedule or a group can only go once nothing uses it.

Every answer carries a text label (BLOCKED, CACHED, FORWARDED and so on), so nothing depends on color alone. The UI has one theme, light.

In the top bar of every page, Docs opens this documentation and API docs the API reference, both in a new tab; the sign-in page has them under its form. On narrow screens the top bar shows only their icons, a book and braces. The API reference is the node's own (for its exact version) when it serves one, which it does only to a browser on the same machine; otherwise it is the one on this site.

A node in a cluster has a Cluster page; the header's cluster badges and the dashboard's Cluster panel lead there too. It shows, as this node sees it:

• Health, in a word: HEALTHY (every member up, changes work), DEGRADED (changes work, but a member is down or something needs a look), READ-ONLY (a leader, but changes through this node are refused, and why), NO LEADER (changes are frozen until most voters reach each other) or WAITING TO BE ADDED (this node is in no cluster yet). Beside it: the leader, whether changes work, and the voters: how many there are, how many it takes, and how many more the cluster can lose (3 voters, 2 needed: can lose 1).
• A card per member: up or down, what it does (leader, follower, learner), whether it votes, whether it is a witness, its address and goethite version (flagged when it differs from this node's), its configuration version and how many changes it is behind the leader, when it was last checked, and why the check failed. The leader's card has an ochre header; a member that is down has a dashed border, and says DOWN.
• Following the leader, on a member that does not lead: when it last heard from the leader, and when its configuration last changed.
• Recovery: the steps from When the cluster cannot elect a leader, offered only where they apply. Without a leader, Take the cluster over (or Start a cluster here on a node in no cluster yet). When another member leads a cluster of its own, Join its cluster. On the card of a member that is down, Remove takes it out of the cluster for good (first take it out of every member's config file). Each needs a second click, and acts on the node you are looking at. When goethite refuses one because it does not apply, the refusal offers to do it anyway, with what that means.

The UI runs under a strict Content Security Policy: no inline code, nothing from other sites, not even fonts. The one exception: images from *.leak.goethite.test, names only goethite answers, which the leak test has the browser look up. Its files need no token, but everything they show comes from the API, which does. The API refuses requests from other web sites and, without a token, requests that do not name this machine, so pages you visit cannot use your browser against it. See ADR 0009.

To turn the UI off and keep only the API:

[api]
web_ui = false

Builds made without the UI (see Install) log that they have none.

goethite can serve its API reference, rendered from its own OpenAPI document, at /api/docs:

[api]
docs = true

It answers loopback clients only (use an SSH tunnel from elsewhere) and needs no token: it describes the API, not your data, as the reference on this site does. Its files are built into goethite. Its policy differs from the UI's in styles and image sources: style elements need a fresh nonce or a known hash, and style attributes are allowed, since the reference sets sizes in them; scripts stay limited to goethite's own files, and it has no leak-test image exception.