Web Interface
Ze provides an HTTPS web interface for browsing configuration, editing values, and running commands through a browser. The web UI uses the same YANG schemas, user database, and command grammar as the SSH CLI.
Starting the Web Server
Command Line
ze start --web 8443 # Start daemon + web on port 8443
ze start --web 8443 --insecure-web # No authentication (forces 127.0.0.1)
When no certificate is configured, ze generates an ECDSA P-256 self-signed certificate automatically. The certificate includes SANs for localhost, 127.0.0.1, ::1, and the listen address. WebCertHosts builds that list, and a listen address of 0.0.0.0 adds every non-loopback interface address of the machine.
When no config file is named, the daemon reads the config name from the store. If the store's instance name cannot be read, ze start exits 1 with an error naming ze doctor, and a web server started with no config path stays off and prints warning: web server disabled: with the reason.
| Flag | Description |
|---|---|
--web <port> |
Start web interface on 0.0.0.0:<port> (requires config) |
--web-only |
Start web UI only, no daemon (config editing only, default port 3443) |
--insecure-web |
Disable authentication (forces 127.0.0.1, requires --web or --web-only) |
Workbench UI
Ze defaults to a RouterOS-style operator workbench UI. The workbench keeps the same authentication and commit flow; the CLI is available as a separate /cli tab instead of a bottom bar. BGP peer rows ship with related operator tools (peer detail, capabilities, statistics, flush, teardown) that run the same dispatched commands as the SSH CLI. Confirmation prompts gate destructive tools.
To roll back to the legacy Finder UI:
ZE_WEB_UI=finder ze start --web 8443
Configuration
The web server listen address can also be set in the ze configuration file:
environment {
web {
enabled true;
server main {
ip 0.0.0.0;
port 8443;
}
}
}
Authentication
The web interface uses the same user database as the SSH server. Users log in through a browser login page or authenticate API requests with HTTP Basic Auth.
Browser Sessions
- Navigate to
https://<host>:8443/. Unauthenticated requests receive a login page. - Enter username and password. On success, a
ze-sessioncookie is set. - The cookie is
Secure,HttpOnly, andSameSite=Strict. - Each user can have one active session. Logging in again invalidates the previous session.
- A session lasts 24 hours, and ends earlier if the configuration stops declaring the user. Remove a user and reload, and their open browser tab is refused on its next request. No daemon restart is necessary.
A user authenticated by RADIUS or TACACS+ keeps their session: the local user list did not grant it and does not end it.
JSON API
API clients that send Accept: application/json (or append ?format=json to the URL) can authenticate with HTTP Basic Auth instead of session cookies. No session is created for Basic Auth requests.
curl -k -u admin:password https://localhost:8443/show/bgp/?format=json
Security Headers
Every response carries X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self', and HSTS (max-age=63072000; includeSubDomains). An authenticated response adds Cache-Control: no-store and X-Ze-Version.
X-Ze-Version carries the release, the git commit, the Go version and the OS, which tells a client the exact build it speaks to. Write environment { hide-version true; } to keep it off every response of the web interface and the looking glass together. The default is false, so the banner stays until you hide it, and no other header changes. Ze sends no Server header at all.
script-src 'self' refuses an inline script and refuses Function(). No page therefore carries an inline event handler, and no htmx attribute uses a bracketed trigger filter, because htmx compiles such a filter into source and calls Function() on it. A test refuses both in any .templ source.
Secret Masking
No render path prints a value the schema marks ze:sensitive or ze:bcrypt. One
predicate, config.LeafHoldsSecret, answers whether a leaf holds a secret. The
display mask and the write guard both read it, so the two halves cannot drift
apart.
| Surface | Behavior |
|---|---|
| The config tree, the diff, the compare view and the download | A secret leaf that holds a value reads as the placeholder. An unset secret stays empty, so the field still reads as unconfigured |
| The commit diff | A rotated secret is named as a changed path. Neither the old value nor the new one is printed |
| The web CLI bar and the terminal | show masks the same leaves. The verb needs no config authorization, so any authenticated session used to reach them |
The terminal's answer to set |
The acknowledgement reads set <leaf> /* SECRET-DATA */, so the value never travels back in the response body |
| Commit, load and upload | A tree carrying the placeholder in a secret leaf is refused. Restore the real value from the edit-authorized raw download, or set it through plaintext-<name> or ze passwd |
Rendering
Every page, panel, fragment and out-of-band swap is written in a .templ source
and compiled to Go by templ. No Go file in the package
builds markup: the exemption table is empty and a test holds it at zero. A
renamed view-model field is therefore a compile error, where html/template
rendered a blank panel and answered 200.
| Command | What it does |
|---|---|
./le repo update |
Regenerates every *_templ.go from its .templ source. Run it after any .templ edit |
./le doc check templ-output |
Refuses stale generated output, orphaned *_templ.go files, and .templ sources outside the generator walk |
The generator runs from vendor/, so ./le repo update needs no network and
nothing on PATH. Run ./le repo update, not a bare templ generate: the walk
root is written into the generated Go, so a bare run rewrites every file and
reds the check.
The browser assets are vendored in third_party/web/ and copied to each
consumer by the same ./le repo update run. htmx 4.0.0 and its
hx-sse.min.js extension serve the web interface, the looking glass and the
chaos dashboard. internal/le/web/assets.Write derives each page's asset set
from its component graph, so a page loads only what it reaches.
Navigation
URL Scheme
URLs follow a verb-first three-tier pattern. A segment that is also a canonical
CLI verb (show, monitor, and set, delete, commit under /config/)
takes its spelling from command.Verbs, so the web URL and the CLI command
cannot drift apart. config, admin, portal, login, assets and the
editor words edit, add, form, add-form, changes, rename, discard
and compare are this router's own and the verb registry holds none of them.
| Tier | URL Pattern | Method | Description |
|---|---|---|---|
| View | /show/<yang-path> |
GET | Config tree view |
| View | /monitor/<yang-path> |
GET | View with auto-polling |
| Config | /show/<path> |
GET | Editable config tree view using the authenticated user's pending changes |
| Config | /config/set/<path> |
POST | Set a leaf value |
| Config | /config/add/<path> |
POST | Create a list entry (with optional field values) |
| Config | /config/add-form/<path> |
GET | Fetch add-entry overlay form |
| Config | /config/rename/<path> |
POST | Rename a keyed list entry |
| Config | /config/delete/<path> |
POST | Delete the node named by the leaf form field: a leaf, a leaf-list member, a container, a whole list, or one list entry (the delete button on a list row) |
| Config | /config/commit/ |
GET/POST | View diff and commit changes |
| Config | /config/discard/ |
POST | Discard pending changes |
| Config | /config/changes |
GET | Commit bar state (pending change count) |
| Config | /config/compare/ |
GET | Compare pending vs committed |
| Admin | /admin/<yang-path> |
GET/POST | Administrative commands |
| Auth | /login |
POST | Login (no auth required) |
| Static | /assets/ |
GET | CSS, JS, images (no auth required) |
The root URL / redirects to /show/.
Finder Navigation
The left panel uses a Finder-style column browser (similar to macOS Finder). It shows up to 3 columns, scrolling horizontally as you navigate deeper.
Named vs unnamed containers: Named containers (lists with YANG keys, like peer, group) appear above unnamed containers (global settings like local, timer), separated by a horizontal rule. This makes keyed sections easy to find.
Simple lists: Lists without unique constraints show as a flat column of clickable entries with a + new button.
Context Heading
When inside a list entry, the detail panel shows a context heading at the top with the list name and entry key (e.g., PEER london). This provides immediate context without checking the breadcrumb.
List Table View
Lists that have YANG unique constraints (e.g., peer with unique "remote/ip") display as an interactive table in the detail panel. The table shows the list key and all unique fields as columns.
| Column | Behavior |
|---|---|
| Rename button | Opens a modal, normalizes the new key, and renames the entry without losing its subtree |
| Key column (e.g., name) | Clickable link, navigates into the entry's config subtree |
| Unique field columns (e.g., remote/ip) | Editable inline, saves on blur/Enter/auto-save (1s debounce) |
| Delete button | Removes the entry after confirmation |
The + new button below the table opens a server-rendered form (via HTMX) with inputs for the entry name and all unique fields. Field values are validated against YANG types before the entry is created.
Breadcrumb Navigation
Every page displays a breadcrumb trail from root to the current YANG path. Clicking any breadcrumb segment navigates to that level.
Content Negotiation
The response format is determined by:
?format=jsonquery parameter (takes precedence)Accept: application/jsonheader (whentext/htmlis not also present)- Default: HTML
Config Editing
Each authenticated user gets an independent editor session with its own working tree. Changes are tracked per-user and do not affect other users until committed.
Workflow
- Browse: Navigate to a list (e.g.,
/show/bgp/peer/) to see entries in a table. - Add: Click
+ newto create an entry. Fill in the name and unique fields. Values are validated against YANG types (e.g., IP addresses must be valid). - Rename: In table views, click the rename button to change an entry key. The new key is trimmed and lowercased, and the existing subtree stays attached to the renamed entry.
- Edit: Click an entry name to see its full config. Edit leaf values through inline fields.
- Review: The commit bar at the bottom shows pending change count. Click "Review & Commit" to see a diff.
- Commit: Apply changes. Conflicts with other users are detected and reported.
- Discard: Click "Discard" to abandon all pending changes.
Validation
Field values are validated server-side against YANG types before being accepted:
Every value set from the web (a form field, the add form, the CLI bar and the
terminal set) is then judged with the checks a config file gets: the
enumeration, range, length and pattern the YANG declares, a union's members,
and each member of a leaf-list. A value outside them is refused when it is set,
not at commit. The refusal names the setting path and the value, lists the
accepted values (each with its one-line help) or the accepted bounds or format,
and ends with the command that fixes it:
bgp peer peer1 session capability route-refresh: "requre" is not an accepted value (did you mean require?)
route-refresh accepts only these values:
enable Advertise the capability; no enforcement
disable Do not advertise the capability; no enforcement
require Advertise the capability; refuse the session when the peer does not offer it
refuse Do not advertise the capability; refuse the session when the peer offers it
fix: set bgp peer peer1 session capability route-refresh require
The same refusal reads the same on every surface; the range, length, pattern and union forms are in Value refusals.
A form or the commit modal holds no editor position, so its fix is the set
from the root. The terminal and the CLI bar frame the fix for the position the
line was typed at: the set as typed, corrected, for a refused set, and
top set <full path> ... for a commit refusal inside a context. A new list key
is judged where its entry is created, and the add form judges every field
before it creates the entry, so a refused field never leaves a partial entry.
A key refused by the terminal's rename, copy, insert, activate or
deactivate gets that same command as its fix, with the key corrected and
framed for the position, and the Rename button's refusal ends with
fix: rename <full path> to <corrected key>.
Fix commands quote list keys and values that contain spaces or quotes. Type the whole printed command, including its quotes. A refused key can precede a secret assignment: its correction keeps the assignment and masks the secret.
| Type | Validation |
|---|---|
| IP address | Must be a valid IPv4 or IPv6 address |
| IPv4 | Must be a valid IPv4 address |
| IPv6 | Must be a valid IPv6 address |
| Prefix | Must be a valid CIDR prefix |
| Uint16/Uint32 | Must be a valid unsigned integer in range |
| Boolean | Normalized to true/false |
YANG unique constraints are enforced: duplicate values are rejected with an error naming the conflicting entry.
Entry key names are automatically lowercased and trimmed for both add and rename operations.
Duplicate entry keys are rejected. Validation runs before the entry is created, so invalid input never produces a partial entry.
Navigating to a non-existent list entry (e.g., /show/bgp/peer/london/ when london has not been created) redirects to the root view with an error notification.
A field check reads one value. A commit runs the whole-config validator, the same one ze config validate runs, over the config the commit is about to write. This includes the BGP peer pipeline, so a peer the daemon would refuse blocks the commit while the config is still on the screen. The refusal appears in the commit modal as Commit failed: with the validator's message, and nothing is written.
Notifications
Error notifications appear as toasts in the top-right corner with a 30-second countdown. Click the countdown to pause (for screenshots). Click the close button to dismiss immediately.
A refused action raises a toast carrying the status and the message the daemon wrote, and the same message lands in the field or panel the action came from. A request that gets no answer at all raises a toast that says so instead: the daemon is unreachable, and nothing was changed.
Input Auto-Save
Text and number fields auto-save 1 second after the user stops typing, in addition to saving on blur and Enter. This prevents data loss when navigating away before a field loses focus. Enter commits inside the debounce, so three keystrokes and an Enter send one POST, not four.
Enter arrives as ze-enter, a named event a delegated listener in assets/cli.js dispatches. The listener reads the element's own hx-trigger, lives in a file rather than in an attribute, and survives every swap. An inline editor replaces itself, so each input also carries a stable id derived from its leaf path: without one, htmx restored focus by looking up the empty string and the caret was lost on every save.
Conflict Detection
When two users edit the same leaf concurrently, the commit reports which paths conflict, showing both the local and other user's values. The user must resolve conflicts before committing.
Session Limits
The editor manager allows up to 50 concurrent user sessions. Idle sessions (no activity for 1 hour) are evicted when capacity is reached.
CLI Bar
The web interface includes a CLI bar at the bottom of the page that accepts the same command grammar as the SSH CLI. The CLI bar sends the current URL path as context, so set and delete commands operate relative to the current view.
Integrated Mode
In integrated mode, CLI commands update the page content directly:
| Command | Effect |
|---|---|
edit <path> |
Navigate to a config path |
set [path] <leaf> <value> |
Set a value under the current context path. The last token is the value and the one before it the leaf, as in the SSH CLI; quote a value that holds spaces |
delete <path> [member] |
Delete the schema node at the path relative to the current view, or only the named leaf-list member. The rest of the leaf-list and its containing section stay in place |
show [path] |
Display config text at the current or specified path |
top |
Navigate to root |
top <command> |
Run one command as if at the root context, whatever the command is (top set ospf router-id 192.0.2.9, top show). The position stays where it was unless the command moves it (top edit ospf). The terminal reads top before it splits a pipe, so top show | format config shows the root |
up |
Navigate one level up |
commit now |
Commit pending changes. commit now force commits over another user's conflicting change and discards it from theirs (see the config editor guide). commit without a subcommand is refused with the list of subcommands. commit confirmed <seconds>, commit accept, commit abort and commit verify follow the config editor guide. A commit that validation refuses answers with the SSH editor's text, listing each error and warning; when only warnings block it, the answer names the forced form, and the CLI bar shows it as an error |
discard |
Discard pending changes. discard alone or discard all drops every change; discard <path> drops only the changes at or under that path, the command a commit conflict's fix: line prints, and a path holding none of your pending changes is refused, as is a pipe (`discard |
help |
List available commands |
The prompt shows the current context path: ze[bgp peer]# .
Terminal Mode
Terminal mode provides a scrollback terminal in the browser. Commands produce plain text output identical to the SSH CLI, displayed in a scrollback area with prompt echo. set reads its line the way the integrated mode does. deactivate <path> and activate <path> take a leaf, a leaf-list value, a container or a list entry, and answer as the SSH editor does ("Deactivated bgp router-id"). errors lists this session's pending changes, one line each: + copy, ~ deactivate, ~ activate, +/- for a set or a delete.
Tab Completion
The CLI bar provides tab completion via a JSON endpoint at /cli/complete. Completions are context-aware: when at /show/bgp/peer/london/, typing set + Tab suggests remote, local, timer (children of the peer entry), not root-level items. For YANG union types that include an enum (e.g., local/ip accepting an IP address or auto), the enum values are offered as completions.
Live Updates
The web interface uses Server-Sent Events (SSE) to notify connected browsers when configuration changes are committed by any user. A notification banner appears with the username and a "Refresh" button.
The same stream carries, to each user alone, what the SSH editor's status
line would show that user: the countdown of a commit confirmed window, or
whose window is pending, how a window ended, and that another user's forced
commit discarded one of your changes. They arrive as config-change events,
so they use the same banner. While a user's own commit is in flight, the
window news for that user waits, so a user's own commit accept or
commit abort is never reported as closed by another session. See "Commit
Confirmed" in config-editor.md.
Connect to the SSE stream at /events (requires authentication). Each stream is registered under its user. The broker supports up to 100 concurrent SSE clients. Slow clients that fall behind have events dropped rather than blocking other clients.
Event Format
Events use the standard SSE wire format:
event: config-change
data: <html-fragment>
The HTML fragment contains a notification banner with the change description and action buttons.
Admin Commands
The /admin/ tier provides a browsable tree of administrative commands. Container nodes display navigable links to sub-commands. Leaf commands display a parameter form with an "Execute" button.
The form also shows the command's help, read from the same command model every other surface reads. The declared one-line summary is the lede above the form, and the declared long explanation is the paragraph under it. A command that declares no explanation shows the summary alone. A path the command tree does not hold shows neither text, and never borrows its parent's.
Admin command results are displayed as titled cards showing the command name, output text, and success/error styling.
Resilience
Corrupt change files: If a per-user change file in the live store has an unknown path, malformed command or invalid structural syntax, every edit and every commit for that user fails with an error naming the file, and the file is left as it was. Its pending changes are never dropped in silence: the operator inspects the file, then discards the changes (discard) to start again. An invalid leaf value or leaf-list member in an API candidate remains editable: commit refuses the value, and the operator can apply its proposed correction without discarding other changes.
Asset caching: Static assets (/assets/) are served with Cache-Control: no-cache, must-revalidate so browsers always pick up changes after binary updates without requiring a hard refresh.