Guide

Configuration Editor

Ze includes an interactive configuration editor with YANG-driven tab completion, rollback history, and live validation.

Usage

ze config edit                      # Edit default config
ze config edit myconfig.conf        # Edit specific file

Stored editing runs inside the owning daemon over an SSH terminal session. When no daemon answers, the editor starts an ephemeral daemon and connects to it. Once connected, the local process holds no writable store handle. Terminal resizing and input travel over the SSH PTY, and the daemon persists drafts and command history.

Three more surfaces reach the same editor against a running daemon. An SSH session opens in configuration mode. The web interface gives each authenticated user an editor of their own. The console of ze start --cli opens at the operational prompt, where configure enters configuration mode. A commit now from any of the three reloads the daemon.

Command history is immediately available to Up/Down after Enter. A session-owned worker publishes detached whole snapshots without holding up input, timers or delivered command results. It keeps only the newest waiting snapshot for each of the two modes, plus the active write. The model owner MUST close the model before releasing its editor or borrowed store: graceful close cancels dispatch, drains and joins history, then closes the transcript. SSH (including no-PTY refusal), attached consoles, local loose-file/backup programs and headless restarts use that lifetime. Construction alone starts no history worker. Each SSH channel holds its own model closer, even when channels share one authenticated connection. The SSH model owner's Server.Stop seals new model admission and joins all admitted factories/model cleanup before its caller may close the borrowed store. Its network deadline does not cancel this history drain: a network error closes remaining connections, then Stop still waits for accepted history. A storage call that has stopped answering holds Stop for at most 5 seconds, a share of the teardown margin the service manager's stop timeout allows. Stop then logs an error naming the storage and returns, so the daemon's teardown continues without that write, and that session's history or unsaved edit may be lost: a write it has not begun yet fails once the store closes. The stuck write still holds the store's own lock, so closing the store waits for it after everything else has stopped, and a second stop signal or the service manager's stop timeout forces the exit. Server.Start refuses a new generation while such a session is still running. Server.Start waits for every bound listener's actual Serve registration, so an immediate Stop cannot miss a primary/extra listener still starting. Hook-built daemon SSH is retained by the actual plugin server's OnStop callbacks. runYANGConfig immediately defers one sync.OnceFunc stop owner and uses that same owner at explicit shutdown sites. Normal shutdown and startup failure therefore both join SSH cleanup before the outer caller releases its store. A private hook-admission seal also joins a constructor already running; a just-built server refused by the stopping owner is closed synchronously. This does not depend on stop-callback ordering or a live editor Update loop. Abrupt process death can lose queued command history; draft, configuration and commit durability are unchanged. Slow draft I/O can still delay a command's own result. Separate sessions keep independent whole snapshots, not merged history.

Editor Commands

Command Description
set <path> <value> Set a configuration value
delete <path> Delete a configuration value or section
show Display current configuration
show <path> Display a specific section
show | blame Annotate with authorship
show | changes [all] Pending changes (session or all)
show | compare Diff against committed config; shows only the parts that differ
show | errors Validation issues
show | history List rollback revisions
commit now Save changes and notify daemon
commit now force Commit even though validation reports warnings (never errors)
commit confirmed <N> Commit with N-second auto-revert window (1-3600)
commit accept Make a pending confirmed commit permanent
commit abort Roll back a pending confirmed commit immediately
commit verify Validate the candidate and apply nothing
discard all Drop every pending change (in an editing session, every change of this session)
discard <path> Drop the pending changes at or under the path, and keep every other change
rollback <N> Restore revision N
top Navigate to config root
top <command> Run one command as if at the root, and stay where you are unless the command moves you
up Navigate up one level
edit <path> Navigate into a section
exit Exit editor

top <command> takes any command the editor accepts and runs it once with the position at the root, then leaves you where you were. Inside edit bgp peer peer1, top set bgp router-id 192.0.2.9 sets the root path, top show displays the whole configuration, and top show | errors lists every issue. Only a command that moves you keeps its move: top edit bgp goes to bgp, as edit bgp typed at the root would. top run <cmd>, top exit, top clear, top stop and top restart do exactly what they do without top. top load terminal relative merge pastes at the root. History keeps the line as you typed it, and completion after top offers what the root offers. This form runs in the SSH editor and ze config edit.

In an editing session a bare discard is refused and names both forms above. Without an editing session, a bare discard drops every change, and discard <path> puts back the committed content at the path, or removes what the path holds when the committed config has nothing there.

The help overlay (help), Tab completion and ze config edit --help all read one command table, so their wording for a command is the same.

commit always takes a subcommand: a bare commit, a bare force, or an unknown word is refused with the list of subcommands, so a typo never applies a configuration. force is a modifier that only follows commit now or commit confirmed <seconds>. While a confirmed commit is pending, commit now and a second commit confirmed are refused: answer the window first with commit accept or commit abort. The SSH editor, ze config edit and the web terminal share this grammar. With nothing pending, the SSH editor and the web terminal answer commit now with "no changes to commit" and apply nothing, and commit confirmed <seconds> with "no changes to commit: no confirmed commit was opened", because a window over no change would revert nothing.

A commit that validation refuses says on the status line how many errors and warnings block it. When only warnings block it, that line names the forced form of what you typed (commit now force, or commit confirmed <seconds> force), and a forced commit reports how many warnings it skipped. force never commits over an error. The viewport shows the same header, then each issue on its own lines, indented: the problem, why, and a fix: line you can type where you are. At the root the fix is set <full path> <value>; inside an edit context it is top set <full path> <value>, which works from any position. A refused member of a leaf-list gets delete <path> <member> instead. A missing mandatory leaf names its set in brackets the same way, with top in front inside a context. commit verify and show | errors give the same list and apply nothing. The web terminal and the web CLI bar run the same validation and answer with the same text, the CLI bar as an error notification, and a refused commit leaves your changes pending there too.

A set or insert the schema refuses (a value outside an enumeration, a range, a length or a format), and a rename or copy whose new key the list refuses, names the setting path, lists what the leaf accepts, and ends with the command you typed, corrected, in the form you typed it: relative inside an edit context, and behind top when you typed it behind top. A refusal of several lines is shown whole in the viewport, and the line above the prompt keeps its first line. Inside edit bgp peer peer1, a mistyped set session capability route-refresh requre ends with fix: set session capability route-refresh require. The refusal's full shape, for every kind of value and every surface, is Value refusals.

Command input in the SSH editor, web terminal and web CLI bar uses the config token codec. Double-quoted words decode \", \\, \n, \r and \t. Single-quoted words keep their contents raw, so 'C:\Users\test' preserves each backslash; the double-quoted form is "C:\\Users\\test". A quoted "|" is a literal key or value; a bare | starts a pipe. For example, show | match "|" shows only lines with a literal pipe, and show | match "|" | head 1 shows the first one. Printed fixes preserve these boundaries, including behind top, so a group named "edge routers" keeps its name when you type the proposed correction.

A commit refused because of an API-supplied value keeps that value and your other pending changes. Apply the proposed correction and commit again. A session's stored candidate remains readable and editable even when one of its leaf values or leaf-list members is invalid; you do not need to discard your changes to repair it.

show | errors validates the current candidate with the same checks as commit, including errors that force cannot override. It lists those errors and any warnings in the viewport, with line numbers referring to the hierarchical configuration view. After a repair, run it again: the list reflects the candidate now, not the validation hints cached before your edit. It applies nothing and keeps pending changes.

Inline validation hints follow the highlighted configuration line; they never replace it. An invalid intermediate edit, such as copying a peer before changing its duplicate remote IP, therefore keeps the peer's configuration visible.

In the SSH editor and the web terminal, commit now is refused when your change conflicts with another user's pending change (LIVE) or with a value committed since you made it (STALE). commit now force applies your change anyway. Each other user's pending change that it overrides is removed from that user's change file, or from the shared draft when they already ran save, and nothing else of theirs is touched. Their next commit does not bring it back. Every editor session of theirs, SSH or web, reports "Your change at was discarded by 's forced commit" once: an SSH session at its next check for changes by other sessions (every two seconds, a check that waits while one of their own commands runs, or when they next connect), a web session in the notification bar of each open page within a second, or when a page next opens if none was open, and again at the next second for a page whose event stream was too full to take it. From then on each session shows the committed value in place of theirs, and show | changes there no longer lists it. A notice does not expire with time: it stays on disk until each session of theirs has shown it, so a web session with no page open is told when its page opens. A session they open later is told only of discards no session of theirs has reported yet. The log keeps their 64 newest discards. Validation errors still block a forced commit. When the commit applies but the discard fails, for example because a file could not be written, the answer says the commit applied and adds the warning "commit applied, but the changes it overrode were not discarded and stay pending for their owners", with the cause, so you know to tell them.

A STALE conflict on a leaf-list member names the change as you made it, deactivate <path> <member>, activate <path> <member> or insert <path> <member> <position> [<reference>], and follows it with a fix: line. When the commit no longer holds the member, the line names discard <path> <member>, which drops your changes to that one member and leaves your other edits pending, a rename of the entry above the list included; adding the member back resolves it too. An insert refused for its reference is reported once: its discard also drops a later deactivate or activate of the member it inserted. The SSH editor, commit confirmed, the web terminal, the web CLI bar and the web editor's Commit button all print the fix: line, and discard <path> works on each of them: in the web terminal and the CLI bar, discard alone or discard all drops every change, and a path holding none of your pending changes is refused with the command that lists them. The closing "Re-set conflicting values to resolve." is printed only when a contested leaf value is among the conflicts. A leaf you set or delete below an entry you renamed is judged against the committed value at the old name, so a rename followed by an edit commits with no conflict when nobody else committed.

A newly created list entry is a pending change even when it contains no leaf values. show | changes lists it as set <entry path>. Loading a block such as an empty dummy interface or an interface-only static next hop preserves that entry through save and commit; it does not need a placeholder description or another leaf. Discarding the creation removes the pending entry, including after it was saved to the draft or subsequently deleted without saving, unless another pending edit or the committed configuration still owns it. Newly materialized list-entry ancestors are removed too when nothing still owns them; existing ancestors are retained.

Saving an entry before renaming it does not leave a second, unowned copy at the old name. Copying an entry retains this session's pending leaf edits, including edits already saved to the draft, without copying another session's ownership. Its member inactivity and child edits remain as they were at copy time, even if the source is renamed or edited afterward. Renaming or copying an ancestor also preserves the ordered effects of its pending child edits: a child created and then deleted stays deleted. An existing entry renamed more than once still checks its original committed source, not an intermediate name. Saving between those renames continues from the materialized entry without moving it back through its old name; another session's new entry at that old name is preserved. String keys containing spaces or # keep their boundaries through save, rename, copy, commit and discard, including leaf-list member toggles below those keys.

If a pending creation's ownership path cannot be parsed or resolved against the schema, commit and discard report an error rather than treating it as unowned. A forced commit does not bypass that uncertainty. After an edit has already succeeded, an inconclusive overlap check is reported as conflict check failed, separately from a known conflict; the edit stays pending.

commit now reaches the same reload as ze signal reload. Which configuration changes stop a session, and in what order, is in The order of a commit.

The | after an editor command belongs to the editor's own filter language. It is separate from the operational command operators published by ze help command --json, so names such as blame, compare, and history apply here without becoming operational pipe operators.

Structural operations appear in the diff

show | changes and show | compare include the draft's structural operations, not only its leaf values. A deleted list entry, a deleted container, a deleted list, a rename, an insert at a position, and a deactivate or activate are recorded in the per-user change file rather than in the value tree. The tree store exposes those change files to both display surfaces, so the reviewed diff includes the operations that commit will apply.

show follows the working configuration's recorded list-entry order. show | compare omits unchanged entries, except for the context retained within a reordered ordered-by user list. Reordering a plain list alone creates no change marker. For a list declared ordered-by user in YANG, order is part of the configuration: a moved entry is shown removed at its old position and added at its new position. Surviving entries follow working order; deleted entries appear after their original predecessor. Removed rows have no working line number, so they do not shift validation highlighting onto another entry. Bracket leaf-list rows keep their leaf name and indentation in every change state, so a surviving bracket statement maps to its working line.

Secrets are masked on every display path

One predicate answers whether a leaf holds a secret, and every display path reads it. A leaf the schema marks ze:sensitive or ze:bcrypt is masked in the tree view, the annotated view, the search results, the blame view, ze config show, ze config dump, and ze config diff. ze config diff masks the COMPUTED diff, so a rotated credential still reports as changed and neither value is shown. The text output and the JSON output agree.

What a command says back is masked too. ze config set writes set <path> /* SECRET-DATA */ rather than the password the operator typed, and so do its --dry-run line, the set status line of the SSH CLI editor, the adoption prompt of ze config edit, and both sides of a commit conflict. A refusal names the rule the value broke and not the value. The path stays in the clear, so the operator still reads which leaf was written.

To read the actual value of a ze:sensitive leaf, copy its $9$ form from the config file and run ze secret decode '$9$...', or ze secret decode - to keep the value out of the shell history. A ze:bcrypt leaf holds a one-way hash, which no command can decode.

Commands run one at a time, in order

The config commands of one session run serially, in the order the operator entered them. Pasting a block of set lines followed by commit now over SSH lands every set before the commit reads the draft. Nothing is dropped and no command is refused for arriving while another is in flight. A command starts only once the answer of the one before it is on screen, so answers appear in the same order: commit abort typed straight after commit confirmed always ends with the abort's answer. While a command is in flight, the two-second check for changes by other sessions waits: it neither re-reads the draft under the running command nor looks at a confirmed-commit window, so a session's own accept or abort is never reported as another session's. When the session ends with commands still queued, because the SSH client went away or the operator left, those commands are dropped unrun: a command that no operator will ever see the answer of does not change the draft.

Other Config Subcommands

Command Description
ze config validate <file> Validate configuration file
ze config migrate <file> Rewrite a config in the set or hierarchical form
ze config fmt <file> Normalize formatting (output to stdout)
ze config dump <file> Dump parsed config as JSON tree
ze config diff <a> <b> Compare two config files
ze config diff <N> <file> Compare rollback revision N against current
ze config set <file> <path> <value> Set a single value programmatically
ze config history <file> List available rollback revisions
ze config rollback <N> <file> Restore revision N
ze config archive <name> <file> Archive config to named destination (details)
ze config completion <file> Query YANG completion engine (debugging)

Every <file> above accepts - for stdin. The read-modify commands ze config set, ze config deactivate, and ze config activate become pipeline stages when given -: they read the config from stdin, apply the change, and emit the modified config to stdout instead of writing back, so they compose (ze config show - | ze config set - bgp session asn local 65001). ze config edit -, ze config rollback <N> -, and ze config history - are rejected with a clear error: an interactive editor needs a TTY, and rollback/history need on-disk revision history that a piped config does not have.

validate, show, and a diff between two explicit paths read those paths without opening a store. Equal filenames in different folders remain separate inputs. An offline set writes the supplied file and records its previous content only when that folder already holds a store. Without one it prints no version recorded; it does not create a store. history, numbered diff, and rollback require the folder's history and name ze init when it is absent. An offline writer refuses while the daemon owns that store, except ze config import, which then sends its inputs to that daemon (below).

An offline ze config set refuses an invalid value or a new list key before it writes the file. It exits with code 2 and prints the value refusal on stderr. The last line gives the corrected set command from the root, including the words after a refused key. For example, ze config set router.conf ospf redistribute bogus nssa-propagate true ends with fix: set ospf redistribute <connected|static|kernel|bgp|isis> nssa-propagate true.

ze config import --dir <folder> <file>... selects a destination independently of its input files. Without --dir, the destination follows ze.config.dir and then the default config folder. --name supplies the destination name for one input, including stdin. Duplicate basenames are refused before any input is written. A destination name the store already holds is replaced only once confirmed: on a terminal the command names the configs it would replace and asks, and y or yes replaces them while any other answer writes nothing and exits non-zero. Without a terminal, including when the input is stdin, it asks nothing and refuses, naming --yes; --yes confirms in advance. A replaced config is committed as a new active version and the previous one becomes its rollback, so ze config rollback restores it. A config the store holds through its active version alone, with no file key, counts as held. A name is a plain config name: not ., .., a path or -.

While a running daemon owns the destination store, the import goes through that daemon. The name checks and the confirmation run first, exactly as above, over a reader of the store. Every input is then read and encoded before anything is sent, so an unreadable input, or one over 195,840 bytes (the most one command carries), stops the import with nothing sent; a larger config is restored from a backup on the daemon's host with request data restore path <file> config. Each input then goes to the daemon as update data config name <name> content <base64>, which stages the daemon's own config and reloads, or commits another name as a new version, and the command prints the same imported or replaced lines and file count. The first refusal ends the import with the daemon's reason and fix, leaving the inputs before it imported. When no daemon answers, the command keeps the store's refusal, says why the daemon did not answer and names the fix. It reaches the daemon as ze data import does: the address and login of that store, with no password prompt. --dir naming a store no daemon owns stays offline.

Offline, an import into a config whose confirmed commit was left open by a daemon that then stopped is refused, as ze config rollback is: that daemon's next start reverts the commit, which would undo the import. The refusal names ze start <config>.

Editing Modes

The selected source determines the editor's mode.

File mode (ze config edit -f <file>): the editor reads and writes the explicit loose file. It keeps its .edit recovery file alongside it, and records rollback versions in an existing store in the file's folder. commit confirmed restores from that history, so in a folder with no store it refuses before writing anything and names ze init. A file changed externally since it was opened causes commit to fail rather than overwrite the edit. -f cannot be combined with --web or --insecure-web; use session mode without -f to serve the web editor from the owning daemon.

Session mode (ze config edit, SSH, web, or the attached console): the owning daemon gives each session an identity (user@origin%timestamp) and a per-user change file. Commit applies the session's changes with conflict detection. The same store holds draft recovery and history for every surface.

Backup mode (ze config edit --backup <artifact> [config-name]): the editor opens a config inside a backup artifact (a .zefs file that ze data backup or request data backup wrote) with no daemon. No SSH credentials are read, no daemon is probed or started, and run commands have nothing to reach. The session behaves as a daemon session does: it has an identity, a draft and history, all inside the artifact. A commit publishes into the artifact: a new version, the active and rollback pointers, and file/active/<name>. The status line ends in "and published". ze data restore <artifact> config then applies the edited config to a device.

The editor holds the artifact's <artifact>.lock sidecar for the whole session, so a second --backup editor, and any other --backup command, on the same file is refused with an error that names it. A lock on the artifact itself would not do: each commit rewrites the artifact through a rename, which installs a new file. Writes pad each changed slot by 10%, so a later edit of about the same size stays in place; ze data backup writes exact-fit artifacts because nothing edits them. --backup cannot be combined with -f, --web or --insecure-web, and the refusal names both flags. Without a config name the editor uses the artifact's <instance>.conf and otherwise asks which config to edit.

When the editor takes the config name from the store, it reads the store's instance name. If that key exists but cannot be read (a CRC mismatch, an I/O error), ze config edit exits with an error that names ze doctor and ze init, rather than opening ze.conf. With no store at all it uses ze.conf.

ze config show, diff, set and list take the same --backup <artifact> flag and work on the configs inside it: show and diff read under a shared lock, set publishes the way an editor commit does, and list names only the artifact's configs. set --backup refuses --reload, because an artifact has no daemon.

When the daemon was started with an explicit file, every start reads that file, and daemon commits update it together with stored history. An external edit must be reconciled before a competing daemon commit can succeed. Bare ze start takes its active configuration from the store.

In a session editor, commit confirmed <seconds> runs through the daemon's confirmed-commit window (see Commit Confirmed). A session editor of a configuration the daemon does not run has no such window, and validates its candidate first, showing any blocking issues with the same status header and viewport corrections as commit now. A valid candidate is refused with "commit confirmed needs a daemon that runs this configuration from its store"; commit now still works there. The web editor of ze start --web-only has no daemon and answers the same way.

insert is supported in session mode: InsertLeafListValue routes through writeThroughMemberOp, and so do deactivate and activate when they name a leaf-list member rather than a leaf or a path. A deactivated member stays in its leaf-list, bracket ones such as address [ ... ] included: the file writes the whole list and then one inactive: address <member> statement for it (nop <path> <member> in set form, as for any leaf-list), so a save, a commit and a reload all keep it deactivated. You can deactivate a member your session has just added: commit now applies that deactivation after the set that adds the member. Setting a bracket leaf-list whole keeps every deactivated member deactivated: one the new list names stays deactivated in its new place, and one the new list does not name is kept, still deactivated, after the members the list names. delete address <member> removes that one member, deactivated or not, and leaves the rest of the list, and an earlier deactivate or insert of it goes with it, so adding, deactivating and then deleting a member commits as if it was never added. Setting the list whole replaces your session's earlier member changes to it: a member you deleted and then list again stays in the list, and an insert position gives way to the order the new list states. When another commit has removed a member you deactivate, or the member an insert is placed against, commit reports a conflict on that path rather than failing. A reference member your own session adds, by a set or by an earlier insert, is no conflict, and neither is a deactivated reference, which holds its place in the list.

copy, and deactivate or activate on a leaf or a path, are supported in session mode too. Each records one structural op in your change file (copy-entry, deactivate-leaf, activate-leaf, deactivate-path, activate-path), shows as one change in show | changes, and is applied by commit now before your leaf edits. copy and rename never overwrite: a destination that is another existing entry is refused, so delete it first, and a destination equal to the entry's own key is refused with "new key must differ from current key".

load works in session mode and in file mode through one path. The input, from a file or pasted after load terminal ... and ended with Ctrl-D, is parsed against the schema first: at the root it may be hierarchical or set lines, and a relative load takes a hierarchical body checked against the children of your current context, so a key that node does not hold is refused by name. A merge then applies each leaf, leaf-list member, list entry and inactive marker the input carries that the configuration does not already hold, and a leaf both name takes the loaded value while every leaf the input omits is kept; a replace also deletes what the node holds and the input omits, scoped to the context for a relative load. A bracket leaf-list such as address [ 192.0.2.1/24 ] or virtual-address [ 203.0.113.1 ] is written as one value, the way a typed set writes it: a merge adds the loaded members the configuration lacks to the ones it holds, and a member you deactivated stays deactivated, while a replace, and an ordered sequence whose repeats matter, take the loaded members as they are; a replace takes their inactive markers too. In session mode each applied difference is one tracked change, the same entry a typed set or delete records, so a leaf equal to its current value records nothing and show | changes lists exactly what the load changed.

For a list of named entries, both forms keep existing entries in their current positions and append new entries in the order the input names them. A replace removes omitted entries but does not move the entries it retains; it is not a list-reordering command.

Entries created by typed set commands keep their creation order through draft save, commit and reload too. Session replay takes that order from the candidate tree, not from metadata map iteration or the session's timestamp.

A load is all or nothing. A parse error, a refused entry, or a failed write of the change file leaves the candidate exactly as it was, and the error says load refused, candidate unchanged. In session mode the load holds the change file's lock for its whole run, reads the change file and the committed configuration once, applies every difference in memory, and writes the change file once, at the end, so its cost grows with the size of the input rather than with its square.

Use file mode (ze config edit -f) for the blocked operations above.

Feature File mode Session mode Backup mode
Commit Writes explicit file Applies tracked changes in the owning daemon Publishes a version and its pointers into the artifact
Multi-user Offline writer only Per-user change files One editor; the artifact lock refuses a second
Conflict detection External file changes Live and stale changes Live and stale changes
Blame / authorship ✕ ✓ ✓
Crash recovery .edit file Change files and draft Change files and draft, inside the artifact
Draft / discard path ✕ ✓ ✓

YANG Completion

Tab completion is driven by registered YANG schemas. The editor suggests:

  • Valid config keys at the current level
  • Enum values for leaf nodes
  • Address family names from registered plugins
  • The keys of a list whose key is an enumeration, including the ones the config does not hold yet, each with the help text the schema declares
  • For a list whose key names several leaves (bfd single-hop-session, keyed peer vrf interface), the first value of each configured entry, once, so one peer on two links is offered once; the key leaf names follow it
  • Well-known values a plugin offers for one of its own leaves, such as the transit-free ASNs on policy reject-asn ... via
  • For a leaf that names another configured entry, the entries it may name at that position: Tab on traffic-control default-class offers the classes of that qdisc, and Tab on a filter chain's filters [ offers the policy filters that chain's protocol accepts. The other references completed this way: a bfd session, BGP peer or static next-hop bfd profile; an OSPF or IS-IS key-chain; a user's or tacacs-profile's authorization profile; an IPsec peer's or remote-access gateway's ike-group and esp-group; a firewall term's jump and goto chain; a geodns source's host-set; a policy match instance's prefix-list; and every PKI certificate or CA name a web, looking glass, plugin, IPsec, RPKI, geodns or AS112 block carries. Completion and commit run the same check, so commit accepts every value offered; with none configured, Tab shows the type hint
  • Inside a leaf-list's brackets, the next value: set filters [ P completes a second filter

List keys and every other value read from the config come from your own candidate configuration, uncommitted edits included. In the web CLI each user completes from their own session, so another user's uncommitted entries never appear in your suggestions.

A suggestion is never a constraint. A leaf that offers well-known values still accepts every value its YANG type admits, so an ASN outside the offered set is entered and committed with no warning.

A menu row is the config key alone. The second message line above the prompt shows the summary of the selected key, which the YANG ze:help statement declares. Tab on the value of an enumeration key does the same for each value: the message line shows the ze:help that value declares, and a value that declares none shows an empty line rather than a placeholder.

Press ? on a highlighted key to read its long explanation, in a box above the prompt. That text is the description statement the schema declares, and it is often a paragraph. The message line holds one row, so the box is the only place the paragraph fits. A key that declares no description says so on the message line, and its summary is not repeated in the box.

Tab on a complete config path reveals nothing more to read: ? is the key that opens the explanation of a config key. Operational command help is reachable from configuration mode behind run , and the keys are in the CLI guide.

Commit Confirmed

commit confirmed <seconds> writes the configuration and notifies the daemon, but starts a countdown timer. If commit accept is not issued before the timer expires, the configuration automatically reverts to the previous version. This prevents lockouts when making changes remotely -- if a bad config breaks connectivity, the auto-revert restores access.

Step What happens
commit confirmed 60 Config saved, daemon notified, 60-second timer starts
Verify the change works BGP sessions come up, routes propagate, etc.
commit accept Timer stops, config is permanent
or commit abort Config reverts immediately
or timer expires Config reverts automatically

The seconds parameter accepts values from 1 to 3600 (one hour).

Closing an editor cancels its display countdown, validation debounce and live-view polling timers. A delayed tick from that editor cannot update a restarted editor. This session lifetime does not cancel the daemon's commit-confirm window: the daemon still owns its deadline and rollback. The model retains a polled daemon rollback failure as a structured error as well as displaying its status. The error clears when the watch observes recovery, closure or a stopped window, even if shutdown interrupted watch initialization; reporting it does not close the daemon window.

Every write to the daemon's configuration (a commit from any editor, an accept, an abort, a gNMI Set, an API config session, a managed push) runs on the daemon's one commit-confirm worker. A Ze defect met during one write ends that write only: its caller gets an error saying the write may be partly applied and naming the ze show crashes record, and the worker serves the next write and keeps the open window's deadline. A commit confirmed whose apply met the defect still opens its window, so its deadline, or commit abort, reverts whatever part of it applied. The panic is counted in ze_task_panics_total{component="config-confirm",task="write"} (Monitoring, "Contained Panics").

In an SSH session editor or the web editor of the daemon's own configuration, the daemon owns the window, not your session. Both editors commit through the same window code, so the rules below hold for a web user too, from the web terminal, the CLI bar and the "Review & Commit" button. While a window is open, the config writers outside the editors' commit are refused for every user, its owner included, with the same "A confirmed commit by is pending" refusal, because the revert would wipe what they wrote: a REST, gRPC or gNMI config session commit, request data restore of the daemon's config, update bgp config, the web raw-source editor, a config push from the managed hub, which the hub receives as the error in its acknowledgement, and rollback <N> in a session editor (SSH or web terminal), which writes the file directly. ze config rollback <N> <file> from the shell runs outside the daemon and needs the store to itself, so a running daemon refuses it as busy. With the daemon stopped, it reads the window's record in the store: a daemon that stopped during a window reverts that window when it starts, so the rollback is refused, and the refusal names ze start <file> to start the daemon and revert the window first. The owner's rollback <N> refusal points to commit abort, which reverts the window and lets the rollback run. Accept or abort the window first. Closing or losing the session leaves the countdown running, and the revert still happens at the deadline. The window belongs to the user who opened it: from any session as that user, commit accept and commit abort answer it, and the status line shows "Confirm within s or auto-revert". Every other user's commit now, commit confirmed, commit accept and commit abort are refused while it is open, and their status line shows "A confirmed commit by is pending: s left." A session that saw the window open reports how it closed: a timeout says "Timeout: configuration automatically rolled back", and an accept or abort from another of your sessions says the window "was closed by another session". A web user with a page open sees the same lines in the notification bar, refreshed every second over the page's live-update stream: the countdown or whose window is pending, and how a window ended unless the web user closed it themselves. Inside your own window, commit confirmed <seconds> force applies your new changes and restarts the countdown at <seconds>; the revert still restores the configuration from before the first commit.

File mode (ze config edit -f) keeps the countdown in the editor itself rather than in a daemon. Inside that window, commit now and a plain commit confirmed are refused as in a session editor, and commit confirmed <seconds> force takes the same nested form: the new changes apply, the countdown restarts at <seconds>, and an abort or a timeout restores the backup the first commit recorded.

The open window is recorded in the store before the commit applies, so no commit is ever applied without its revert: a record that cannot be saved refuses the commit and applies nothing. If the daemon stops while the window is open, even just after the commit applied, the next start reverts it before the configuration is read, so the daemon boots the configuration from before the unconfirmed commit.

If the revert at the deadline fails, the window stays open and its record stays in the store. The daemon logs each failure and retries with a doubling wait, from one second up to one minute, eight attempts in all. Every SSH session's status line says the revert failed, with the error and when the next retry runs, and every other user's commit is refused with the same error, because a commit made meanwhile would be wiped by the revert that later succeeds. The owner may run commit abort to retry the revert at once, or commit accept to keep the configuration and close the window. Once the retries are spent, the window waits for one of those two, or for a restart, which reverts from the record. The countdown never shows a negative number.

The revert restores the rollback revision the commit records, so commit confirmed needs config history. An editor without one, such as ze config edit -f on a file whose folder holds no store, refuses before it writes the file and names ze init; commit now still works there.

The demonstration uses the running daemon's SSH editor, not file mode. It load-merges a trial hostname and uses commit confirmed 15. After the unaccepted window expires, it checks the restored edge-original hostname and an empty show | compare, followed by show | changes reporting no pending changes. A second change, committed with commit confirmed 15, uses commit accept and stays edge-confirmed beyond its deadline. After leaving the editor, it runs ze cli -c "show config history $ZE_CONFIG_DIR/ze.conf | yaml | no-more" to read the running lab's stored revisions. History is a local read and resolves the supplied file's folder: a bare ze.conf selects the shell's current folder, even when ZE_CONFIG_DIR points at the daemon's store. The explicit path selects that store without creating another one. The live validator reads the same history as JSON and requires at least two stored revisions after the automatic rollback, before testing acceptance.

Ze terminal lab

Protect live SSH commits with rollback

Load a risky hostname change over SSH, observe automatic rollback, then accept a second change and prove it persists on the same running router.

Reproducible
Ze 26.10.282 minutes 38 secondsLinux namespace labTerminalZe recorder Plain-text transcript
Read the demonstration transcript
Commit confirmed: rollback and acceptance on the running router

Connect with sshpass -e ssh ze-demo. The SSH editor starts from edge-original.
Load /src/demos/terminal/topics/commit-confirmed/1-trial-host.conf, review
show | compare, then run commit confirmed 15. Ze's timeout is in seconds,
unlike Junos commit confirmed, whose timeout is in minutes.

$ ze-demo card topic-commit-confirmed lab
$ ze-demo card topic-commit-confirmed overview
$ sshpass -e ssh ze-demo
ze# show system host
ze# load file absolute merge /src/demos/terminal/topics/commit-confirmed/1-trial-host.conf
ze# show | compare
ze# commit confirmed 15

Show the active edge-trial value, then deliberately leave the change
unaccepted. Wait for the actual automatic rollback notice. Inspect show
system host for edge-original, the empty show | compare view, and
show | changes for the explicit No pending changes response.

ze# show system host

After the automatic rollback:
ze# show system host
ze# show | compare
ze# show | changes

Load /src/demos/terminal/topics/commit-confirmed/2-confirmed-host.conf,
compare, commit confirmed 15, then commit accept. Wait beyond the fifteen-second
deadline and inspect edge-confirmed again. The accepted value must remain.

ze# load file absolute merge /src/demos/terminal/topics/commit-confirmed/2-confirmed-host.conf
ze# show | compare
ze# commit confirmed 15
ze# commit accept

After waiting beyond the deadline:
ze# show system host

Leave the editor and run:
ze# exit
ze> exit
$ ze cli -c "show config history $ZE_CONFIG_DIR/ze.conf | yaml | no-more"
The explicit config folder selects the running lab's stored revisions.
History is a local read: a bare ze.conf selects the shell's current folder,
not ZE_CONFIG_DIR. Both outcomes use the running daemon's session editor,
never an offline file editor or a router restart.

$ ze-demo card topic-commit-confirmed recap

These are the authored walkthrough steps. Runtime validation and recording
must succeed before this source is published as a recording.

Rollback

The editor automatically saves a rollback revision before each commit. Inside the editor, use show | history to list revisions and rollback <N> to restore. From the shell: ze config history <file> and ze config rollback <N> <file>.

Exit Codes

Code Meaning
0 Success
1 Configuration has errors (from validate command)
2 Error (file not found, parse failure)

Example Workflow

ze config validate config.conf      # Pre-flight validation
ze config edit config.conf          # Interactive editing
ze config diff 3 config.conf       # Compare with revision 3
ze config rollback 3 config.conf   # Restore revision 3
ze config archive prod config.conf # Archive to named destination