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 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, keyedpeer 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-classoffers the classes of that qdisc, and Tab on a filter chain'sfilters [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'sike-groupandesp-group; a firewall term'sjumpandgotochain; a geodns source'shost-set; a policy match instance'sprefix-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 [ Pcompletes 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 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 commit now, commit confirmed,
commit accept and commit abort are refused while it is open, and their
status line shows "A confirmed commit by 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.
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.
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