Command Reference

Ze commands fall into two categories: shell commands that run locally and runtime commands sent to the running daemon via SSH.

For the forward-looking cross-vendor roadmap (which commands VyOS / Junos / Nokia / Arista expose and ze's status per row), see command-catalogue.md.

Shell Commands

Run directly from the terminal. No daemon required (except ze signal, ze status, ze cli, and daemon-targeted ze show subcommands). Some ze show subcommands run locally: version, bgp decode, bgp encode, env, schema, yang, completion.

ze

Start the daemon or access subcommands.

ze <config-file>                 # Start daemon with config
ze start                         # Start daemon from database

Flag	Purpose
`-d`, `--debug`	Enable debug logging
`-f <file>`	Use filesystem directly, bypass blob store
`--plugin <name>`	Load plugin before starting a YANG/native config (repeatable). Hub/orchestrator configs reject this; use `plugin { external ... }` in the config instead.
`--plugins`	List available internal plugins
`--pprof <addr:port>`	Start pprof HTTP server
`-V`, `--version`	Show version (also available as `ze show version`)
`--chaos-seed <N>`	Enable chaos self-test mode
`--chaos-rate <0-1>`	Fault probability per operation
`--server <host:port>`	Override hub address for managed mode
`--name <name>`	Override client name for managed mode
`--token <token>`	Override auth token for managed mode
`--color`	Force colored output (even when not a TTY)
`--no-color`	Disable colored output (also: `NO_COLOR` env var, `TERM=dumb`)

ze config validate

Validate a configuration file without starting the daemon.

ze config validate <config-file>
ze config validate -q <config-file>     # Quiet: exit code only
ze config validate --json <config-file> # JSON output

Flag	Purpose
`-v`	Verbose output
`-q`	Quiet mode (exit code only)
`--json`	JSON output

Exit codes: 0 = valid, 1 = invalid, 2 = file not found.

Validation includes the commit-time backend capability gate: a config whose active backend leaf does not implement a feature it uses (e.g. backend vpp with a bridge, tunnel, wireguard, veth, or mirror entry) is rejected with one error per offending YANG path, matching the diagnostic the running daemon produces on reload. See Backend Capability Errors.

ze config

Configuration management.

Editing:

ze config edit [file]            # Interactive editor
ze config set <file> <path> <value>
ze config deactivate <file> <path>  # Mark a node inactive (kept in file, skipped at apply)
ze config activate <file> <path>    # Clear the inactive flag on a node

deactivate and activate accept any node type: leaf, container, list entry, or leaf-list value. The deactivated node round-trips through save/load and is skipped at apply time. See docs/guide/config-deactivate.md.

Storage:

ze config import <file>...       # Import files into the database
ze config import --name <n> <file>  # Import under a different name
ze config rename <old> <new>     # Rename a config in the database
ze config ls [prefix]            # List files in database
ze config cat <key>              # Print database entry

Inspection:

ze config validate <file>        # Validate configuration file
ze config dump <file>            # Dump parsed configuration
ze config diff <f1> <f2>         # Compare two configs
ze config diff <N> <file>        # Compare with rollback revision
ze config fmt <file>             # Format and normalize

History:

ze config history <file>         # List rollback revisions
ze config rollback <N> <file>    # Restore revision N
ze config archive <name> <file>  # Archive config (see config-archive.md)

Migration:

ze config migrate <file>         # Convert old format to current

Flag	Purpose
`-f`	Bypass database, use filesystem directly
`-o <output>`	Output file (migrate)
`--dry-run`	Show what would be migrated without changes (migrate)
`--list`	List available transformations (migrate)
`--format <fmt>`	Output format: `set` (default) or `hierarchical` (migrate)

ze signal

Send commands to the running daemon via SSH.

ze signal reload                 # Reload configuration
ze signal stop                   # Graceful shutdown (no GR marker)
ze signal restart                # Graceful restart (with GR marker)
ze signal reboot                 # Graceful shutdown + OS reboot (with GR marker, requires root on Linux)
ze signal status                 # Dump daemon status
ze signal quit                   # Immediate exit + goroutine dump

Flag	Purpose
`--host`	SSH host (default: 127.0.0.1 or `ze_ssh_host`)
`--port`	SSH port (default: 2222 or `ze_ssh_port`)

Exit codes: 0 = ok, 1 = not running, 4 = command failed.

ze status

Check if the daemon is running.

ze status

Flag	Purpose
`--host`	SSH host
`--port`	SSH port

Exit codes: 0 = running, 1 = not running.

ze bgp

BGP protocol tools (offline, no daemon needed).

ze bgp decode <hex>              # Decode BGP message hex to JSON
ze bgp encode <route-command>    # Encode route command to BGP hex
ze bgp plugin cli                # Plugin debug shell (5-stage handshake + interactive)
ze bgp plugin cli --name <name>  # Debug shell with custom plugin name

# Also available via YANG verb dispatch (same behavior, no daemon needed):
ze show bgp decode <hex>
ze show bgp encode <route-command>

decode flags:

Flag	Purpose
`--open`	Decode as OPEN message
`--update`	Decode as UPDATE message
`--nlri <family>`	Decode as NLRI for family
`-f <family>`	Address family
`--json`	JSON output
`--plugin <name>`	Load plugin (repeatable)

encode flags:

Flag	Purpose
`-f <family>`	Address family (default: ipv4/unicast)
`-a <asn>`	Local ASN (default: 65533)
`-z <asn>`	Peer ASN (default: 65533)
`-i`	Enable feature
`-n`	Dry run
`--no-header`	Exclude BGP header
`--asn4`	4-byte ASN (default: true)

ze show warnings / ze show errors

Operational report bus. A single place for Ze subsystems to surface operator-visible issues. Warnings are state-based (a condition is currently problematic and may resolve). Errors are event-based (something already happened; no clear API). Both commands query the same in-process report bus and return newest-first JSON snapshots.

ze show warnings                       # JSON: {"warnings": [...], "count": N}
ze show warnings source bgp            # only warnings from the bgp subsystem
ze show errors                         # JSON: {"errors":   [...], "count": N}
ze show errors source l2tp             # only errors from the l2tp subsystem
ze show errors source l2tp count 5     # last 5 errors from l2tp

Issue shape (every entry in both responses):

Field	Type	Description
`source`	string	Subsystem that raised the issue (`bgp`, `config`, `iface`, ...)
`code`	string	Stable kebab-case identifier of the condition or event
`severity`	string	`warning` or `error`
`subject`	string	What the issue is about: peer address, transaction id, file path
`message`	string	Human-readable one-liner
`detail`	object	Optional structured context (family, code/subcode, reason, ...)
`raised`	RFC 3339 time	When the issue first appeared on the bus
`updated`	RFC 3339 time	Most recent raise time (warnings advance; errors equal raised)

Day-one BGP vocabulary (raised by the BGP reactor):

Severity	Source/Code	When raised	When cleared
warning	`bgp / prefix-threshold`	Per-family prefix count crosses the configured warning threshold upward	Per-family count drops below threshold
warning	`bgp / prefix-stale`	`peer { prefix { updated ... } }` date is older than 180 days	Peer re-added with a fresher date, or peer removed
error	`bgp / notification-sent`	This ze instance sends a NOTIFICATION to a peer (code/subcode in `detail`)	Never (errors are events)
error	`bgp / notification-received`	A peer sends a NOTIFICATION to this ze instance	Never
error	`bgp / session-dropped`	An Established session ends without a NOTIFICATION exchange (TCP loss, hold-timer with no notification, peer FIN)	Never

Capacity limits (configurable via env vars):

Env var	Default	Maximum	Purpose
`ze.report.warnings.max`	1024	10000	Cap on active warning set, oldest-by-Updated evicted at cap
`ze.report.errors.max`	256	10000	Ring buffer size for recent error events

Over-limit raise calls are silently rejected and logged at debug level. Field length limits (Source 64, Code 64, Subject 256, Message 1024, Detail 16 keys) prevent any producer from pushing multi-megabyte entries.

Login banner integration: the Ze CLI login banner reads from the same bus, filtered by source bgp. One active warning shows the detail line; multiple warnings collapse to a count line pointing at show warnings.

ze show system

Daemon process introspection. Three sibling commands surface the Go runtime state for the running ze process. Available via daemon SSH (online RPC); YANG registration only.

ze show system memory              # runtime.MemStats (alloc, heap, GC) + hardware enrichment
ze show system cpu                 # goroutine count, logical CPUs, GOMAXPROCS + hardware
ze show system date                # wall-clock time: RFC3339, Unix, timezone

Each response is a flat JSON map with kebab-case keys:

Command	Top-level keys
`show system memory`	`alloc`, `total-alloc`, `sys`, `heap-alloc`, `heap-sys`, `heap-in-use`, `heap-objects`, `stack-in-use`, `num-gc`, `gc-cpu-pct`, `hardware` (optional: physical memory + ECC from `host.DetectMemory()`)
`show system cpu`	`num-cpu`, `num-goroutines`, `max-procs`, `go-version`, `hardware` (optional: `host.DetectCPU()`)
`show system date`	`time` (RFC3339), `unix`, `unix-nano`, `timezone`, `utc-offset-secs`

The hardware subobject under memory and cpu mirrors the data returned by show host memory / show host cpu. Both paths are correct; pick show system * when you want runtime-first with hardware as context, show host * when you want hardware-first.

ze host show

Host hardware inventory. Read-only, no daemon required. Walks sysfs/procfs (and issues best-effort ethtool ioctls for NIC firmware/rings) to produce a structured JSON description of the machine. Defaults to JSON output for pipeline consumption (jq, Prometheus scrapers, SNMP shims); use --text for human-readable summaries.

ze host show                       # Full inventory (all sections), JSON
ze host show cpu                   # CPU only
ze host show nic                   # Physical NICs (virtual interfaces filtered)
ze host show dmi                   # DMI/SMBIOS board identity
ze host show memory                # /proc/meminfo + ECC counters (edac)
ze host show thermal               # hwmon sensors + per-CPU throttle counts
ze host show storage               # Block devices + NVMe firmware
ze host show kernel                # Kernel release, cmdline, microcode, arch flags
ze host show all                   # Every section in one payload
ze host show --text cpu            # Human-readable summary

The same sections are also available as RPCs over ze cli to a running daemon: show host cpu, show host nic, etc. Online and offline paths share the same detection library; the JSON shapes are identical.

Sections:

Section	Fields (kebab-case keys)
`cpu`	`vendor`, `model-name`, `family`, `model`, `stepping`, `logical-cpus`, `physical-cores`, `threads-per-core`, `hybrid`, `scaling-driver`, `hwp-available`, `base-freq-mhz`, `max-freq-mhz`, `microcode`, `cores[]` with per-core `role` (`performance`/`efficient`/`uniform`), `current-freq-mhz`, `core-throttle-count`, `package-throttle-count`
`nic`	Per physical interface: `name`, `driver`, `pci-vendor`, `pci-device`, `mac`, `link-speed-mbps`, `duplex`, `carrier`, `rx-queues`, `tx-queues`, `ring-rx`, `ring-tx`, `firmware-version`
`dmi`	`system-vendor`, `system-product`, `board-`, `bios-`, `chassis-*`
`memory`	`total-bytes`, `free-bytes`, `available-bytes`, `buffers-bytes`, `cached-bytes`, `swap-total-bytes`, `swap-free-bytes`, `ecc-correctable-errors`, `ecc-uncorrectable-errors`, `ecc-present`
`thermal`	`sensors[]` (hwmon: `name`, `device`, `temp-mc`, `alarm`), `throttle[]` (per-CPU `core-throttle-count`, `package-throttle-count`)
`storage`	`devices[]` with `name`, `size-bytes`, `model`, `serial`, `transport` (`nvme`/`sata`/`mmc`/`virtio`/`unknown`), `rotational`, `nvme-firmware-version` (NVMe only)
`kernel`	`release`, `version`, `architecture`, `cmdline`, `boot-time` (RFC3339), `boot-time-unix`, `microcode-revision`, `arch-flags[]` (security-relevant subset: `smep`, `smap`, `ibt`, `user_shstk`, `ibrs`, `ibrs_enhanced`, `ssbd`)

All temperatures are reported in millicelsius (kernel hwmon convention). All sizes in bytes. All frequencies in MHz. Unreadable sysfs files are omitted from the JSON rather than returning null or an empty string. Permission errors are recorded in the inventory's errors[] array.

Virtual interface filtering: ze host show nic only reports physical interfaces. The filter is structural (presence of /sys/class/net/<n>/device/) rather than a driver-name allowlist, so new virtual drivers (wireguard, ipvlan, etc.) are filtered uniformly.

Platform: Linux only. Darwin and other platforms return ErrUnsupported per section; ze host show reports "unsupported on this platform" with exit 0 so scripts can probe gracefully.

ze interface

OS network interface management (standalone, no daemon needed for most commands). Show uses the verb syntax: ze show interface.

ze show interface                  # List all interfaces (also via daemon SSH)
ze show interface brief            # One-line-per-interface summary
ze show interface <name>           # Show details for one interface
ze show interface <name> counters  # Counters only for named interface
ze show interface type <type>      # Filter by type (ethernet, bridge, vxlan, wireguard, ...)
ze show interface errors           # Interfaces with non-zero Rx/Tx error or drop counters
ze show interface --json           # JSON output
ze interface create dummy <name>   # Create a dummy interface
ze interface create veth <n> <p>   # Create a veth pair
ze interface delete <name>         # Delete an interface
ze interface unit add <name> <id> [vlan-id <vid>]  # Add a logical unit
ze interface unit del <name> <id>  # Delete a logical unit
ze interface addr add <name> unit <id> <cidr>      # Add IP address
ze interface addr del <name> unit <id> <cidr>      # Remove IP address
ze interface migrate ...           # Make-before-break migration (requires daemon)

show interface type <type> is case-insensitive; unknown types reject with the sorted list of types actually present on the system. Empty-Type interfaces are hidden from both the response and the valid-types list.

show interface errors skips interfaces without stats and interfaces whose RxErrors, RxDropped, TxErrors, TxDropped counters are all zero. The response includes only the four counter fields per interface for compact diffing across snapshots.

show traffic

Traffic control (TC) state. Queries the active TC backend for qdisc, class, and filter state per interface. Returns "traffic control not available on this platform" when no TC backend is loaded (e.g. on macOS).

ze show traffic                   # Summary of all interfaces with qdiscs
ze show traffic <ifname>          # Detail for one interface

show ip

Kernel routing and neighbor tables. Both commands dispatch through the iface backend; on the netlink backend they read the live kernel state, on VPP they reject under exact-or-reject since the kernel FIB/ARP table is not the authoritative forwarding source there.

ze show ip arp                         # Kernel neighbor table (IPv4 ARP + IPv6 ND)
ze show ip arp --family ipv4           # IPv4 only
ze show ip arp --family ipv6           # IPv6 only
ze show ip route                       # Full kernel routing table (all protocols)
ze show ip route <cidr>                # Filter to an exact CIDR match
ze show ip route default                # Default route(s) (0.0.0.0/0, ::/0)

show ip arp returns per-entry address, mac-address, device, family, and state (reachable, stale, delay, probe, failed, permanent, noarp, incomplete). Unresolved entries (no IP) are skipped. FAILED and INCOMPLETE entries are kept with an empty MAC so operators can diagnose neighbor discovery problems.

show ip route renders the protocol field by name for well-known values (kernel, static, bgp, ra, dhcp, zebra, ze for RTPROT_ZE=250, plus ospf/isis/rip/eigrp/babel) and as a decimal string otherwise. Connected routes have an empty nexthop; the source field carries the preferred-source IP when the kernel reports one.

show firewall

Firewall (nftables) introspection. Requires the firewall { ... } section in config so the firewall plugin loads and applies a backend; without it the handlers reject under exact-or-reject.

ze show firewall ruleset <name>         # Rules + per-term counters for table <name>
ze show firewall group                  # List all known group names (applied sets)
ze show firewall group <name>           # Elements of a named group

show firewall ruleset joins the applied desired state (chains + terms) with kernel counters read back via the nft backend's GetCounters call. Every rule is auto-instrumented with an anonymous counter expression when applied; the term name is stored in nftables' Rule.UserData and recovered on readback so the join is explicit (not index-based). Rejects when no firewall backend is loaded or when the active backend is not nft.

show firewall group reads from the applied-state snapshot, not the kernel -- groups (nftables named sets) are part of the desired state the operator typed into config. Calling with no argument returns { name, tables[], members } per group; a positional name returns the raw elements.

show system uptime

ze show system uptime        # Daemon start time and uptime duration

Returns start-time (RFC3339) and uptime (truncated to seconds). Returns an error when the daemon is not running (context is nil or the reactor is absent).

show bgp summary

ze show bgp summary                  # Every configured peer
ze show bgp ipv4 summary             # Expanded to ipv4/unicast
ze show bgp ipv6 summary             # Expanded to ipv6/unicast
ze show bgp l2vpn summary            # Expanded to l2vpn/evpn
ze show bgp <afi>/<safi> summary     # Full AFI/SAFI form (e.g. ipv4/vpn)

The family argument is validated against the families any peer has actually negotiated; unknown or un-negotiated families reject with the sorted set of currently-negotiated families so the operator sees exactly what is reachable on the running daemon.

ping / traceroute

ze ping <target> [--count N] [--interface IF]
ze traceroute <target> [--probes N] [--interface IF]

Thin wrappers over the OS's ping and traceroute binaries.

clear interface counters

ze clear interface counters                # Reset counters on every managed interface
ze clear interface <name> counters         # Reset counters on one interface

Grammar parallels ze show interface <name> counters -- name before the counters subfield. Bare ze clear interface counters (no name) clears all interfaces. The handler also tolerates clear interface counters <name> and clear interface <name> for scripting convenience, but the canonical form is clear interface <name> counters. Errors in argument shape (unknown trailing keyword, three or more tokens) reject with the usage line rather than silently defaulting to "all".

The clear verb resets runtime/operational state without touching configuration. Backends that expose a real counter-reset syscall (VPP's sw_interface_clear_stats, once wired) zero the kernel counters directly. Linux netlink has no generic counter-reset, so ze falls back to a per-interface baseline: the current raw counter values are captured, and every subsequent show interface [counters] read subtracts the baseline before returning so the operator sees "since last clear" deltas.

Wrap detection: if a subsequent read observes a raw counter lower than its baseline (interface bounce, driver reload, delete+recreate), ze treats it as a kernel-level reset, drops the baseline, and returns the raw value. Subsequent reads resume from the kernel's new zero without underflow.

migrate flags (dispatched to running daemon via SSH):

Flag	Purpose
`--from <iface>.<unit>`	Source interface and unit (required)
`--to <iface>.<unit>`	Destination interface and unit (required)
`--address <cidr>`	IP address to migrate (required)
`--create <type>`	Create new interface: dummy, veth, bridge
`--timeout <duration>`	BGP readiness timeout (default: 30s)

ze exabgp

ExaBGP compatibility tools.

ze exabgp plugin <cmd> [args]    # Run ExaBGP plugin with ze
ze exabgp migrate <file>         # Convert ExaBGP config to ze
ze exabgp migrate --env <file>   # Convert ExaBGP env file to ze config

migrate flags:

Flag	Purpose
`--dry-run`	Show what would be done without output
`--env <file>`	Migrate ExaBGP INI environment file

plugin flags:

Flag	Purpose
`--family <family>`	Address family (repeatable)
`--route-refresh`	Enable route-refresh
`--add-path <mode>`	ADD-PATH mode: receive, send, both

When launched by ze's process manager (as an external plugin), the bridge detects ZE_PLUGIN_HUB_TOKEN and automatically uses TLS connect-back with the SDK. In standalone mode (no env var), it uses stdin/stdout with inline MuxConn framing.

ze schema

Schema discovery.

ze schema list                   # List registered schemas
ze schema show <module>          # Show YANG module content
ze schema handlers               # List handler-to-module mapping
ze schema methods [module]       # List RPCs from YANG
ze schema events [module]        # List notifications
ze schema protocol               # Show protocol version

All subcommands accept --json.

ze yang

YANG analysis.

ze yang completion               # Detect prefix collisions
ze yang tree                     # Print unified tree
ze yang doc [command]            # Command documentation

Flag	Purpose
`--json`	JSON output
`--commands`	Show command tree (tree)
`--config`	Show config tree (tree)
`--min-prefix <N>`	Minimum prefix length (completion, default: 1)
`--list`	List commands (doc)

ze init

Bootstrap the database (interactive or piped).

ze init                          # Interactive setup
ze init -managed                 # Fleet mode
ze init -force                   # Replace existing database

Prompts for: username, password, host (127.0.0.1), port (2222), name (hostname). After credentials are stored, ze init discovers OS network interfaces via netlink and writes initial interface configuration (ethernet, bridge, veth, dummy, loopback) to the database as ze.conf.

ze passwd

Bcrypt-hash a plaintext password for use in system.authentication.user.password. Reads from stdin (piped, single line) or interactive TTY (prompts twice for confirmation). Uses bcrypt.DefaultCost (10), the same cost as ze init.

echo "secret" | ze passwd                                # one-shot pipe
ze passwd                                                # interactive

The output is suitable for direct paste into a YANG password leaf, or as a shell substitution into ze config set ... password "$(echo s | ze passwd)".

--user / -u flag (all client CLIs)

ze cli, ze bgp plugin cli, ze signal, ze config set, ze config edit, and ze interface migrate accept --user <name> (long) and -u <name> (short) to override the bootstrap super-admin username. Without the flag, the CLI uses the username stored in meta/ssh/username by ze init.

Source	Wins over
`--user`/`-u` flag	env, zefs
`ze.ssh.username` env var	zefs
zefs `meta/ssh/username`	(default)

The password for a non-super-admin user must come from ze.ssh.password (env) or an interactive prompt. There is intentionally no --password flag (passwords in argv leak into shell history and ps).

See authentication.md for the full multi-user workflow.

ze start --web

Add the HTTPS web interface alongside the BGP daemon. The web server runs on a separate port and provides configuration viewing, editing, and admin commands.

ze start --web 8443                              # Start daemon + web on port 8443
ze start --web 8443 --insecure-web               # No authentication (forces 127.0.0.1)
ze start --mcp 9718                              # Start daemon + MCP server
ze start --web 8443 --mcp 9718                   # Both web and MCP

Flag	Purpose
`--web <port>`	Start web interface on `0.0.0.0:<port>`
`--insecure-web`	Disable authentication (forces `127.0.0.1`, requires `--web`)
`--mcp <port>`	Start MCP server on `127.0.0.1:<port>` (AI control interface)

The web server uses a self-signed ECDSA P-256 certificate (persisted in zefs) with SANs for localhost, 127.0.0.1, ::1, and the listen address.

See Web Interface Guide for full usage documentation.

ze data

Low-level blob store management.

ze data import <file>...           # Import files into blob
ze data rm <key>...                # Remove entries
ze data ls [prefix]                # List entries
ze data cat <key>                  # Print entry content
ze data registered                 # List all registered key patterns
ze data registered <pattern>       # Show details for a key pattern

Flag	Purpose
`--path <store>`	Blob store path

ze plugin

Plugin management.

ze plugin <name> [args]          # Run plugin CLI handler
ze plugin test                   # Test plugin schema/config

ze completion

Generate shell completion scripts for bash, zsh, fish, and nushell. The scripts provide tab completion for subcommands, flags, plugin names, YANG schema modules, show/run command trees, and argument values (address families, log levels).

ze completion bash
ze completion zsh
ze completion fish
ze completion nushell

Installation

Shell	Quick (current session)	Persistent
Bash	`eval "$(ze completion bash)"`	`ze completion bash > /etc/bash_completion.d/ze`
Zsh	`eval "$(ze completion zsh)"`	`ze completion zsh > ~/.zsh/completions/_ze && autoload -Uz compinit && compinit`
Fish	`ze completion fish \| source`	`ze completion fish > ~/.config/fish/completions/ze.fish`
Nushell	`ze completion nushell \| save -f ($nu.default-config-dir \| path join "completions" "ze.nu")`	Add `source completions/ze.nu` to `config.nu`

ze env

Environment variable management.

ze env registered                # List all registered env vars + log subsystems
ze env registered <key>          # Show details for a specific env var
ze env list -v                   # List with current effective values
ze env get <key>                 # Show single env var details

Flag	Purpose
`-v`, `--verbose`	Show current effective values (list)

ze resolve

Query DNS, Team Cymru, PeeringDB, and IRR resolution services. Offline tool -- no running daemon required.

ze resolve dns a example.com                           # IPv4 address records
ze resolve dns aaaa example.com                        # IPv6 address records
ze resolve dns txt example.com                         # TXT records
ze resolve dns ptr 8.8.8.8                             # Reverse DNS
ze resolve cymru asn-name 13335                        # ASN to org name
ze resolve peeringdb max-prefix 13335                  # IPv4/IPv6 prefix counts
ze resolve peeringdb as-set 13335                      # Registered IRR AS-SETs
ze resolve irr as-set AS-CLOUDFLARE                    # Expand AS-SET to member ASNs
ze resolve irr prefix AS-CLOUDFLARE                    # Lookup announced prefixes

Flag	Subcommand	Purpose
`--server <host>`	dns, irr	Override DNS/whois server
`--dns-server <host>`	cymru	Override DNS server for TXT queries
`--url <url>`	peeringdb	Override PeeringDB API base URL

ze-perf

BGP propagation latency benchmark tool. Separate binary from ze.

ze-perf <command> [flags]

Command	Purpose
`run`	Run benchmark against a BGP DUT
`report`	Generate comparison report from result files
`track`	Track performance history and detect regressions

ze-perf run

Run a BGP propagation benchmark against a device under test (DUT). Establishes sender and receiver sessions with the DUT, injects routes from the sender, and measures how quickly they propagate through to the receiver.

ze-perf run --dut-addr 172.31.0.2 --dut-asn 65000
ze-perf run --dut-addr 172.31.0.5 --dut-asn 65000 --dut-name gobgp --routes 10000 --json
ze-perf run --dut-addr 172.31.0.2 --dut-asn 65000 --family ipv6/unicast
ze-perf run --dut-addr 172.31.0.2 --dut-asn 65000 --force-mp --repeat 10

DUT flags:

Flag	Type	Default	Purpose
`--dut-addr`	string	(required)	DUT BGP address
`--dut-port`	int	179	DUT BGP port
`--dut-asn`	int	(required)	DUT autonomous system number
`--dut-name`	string	`unknown`	DUT implementation name (appears in results)
`--dut-version`	string		DUT version string

Sender/receiver flags:

Flag	Type	Default	Purpose
`--sender-addr`	string	`127.0.0.1`	Sender local address
`--sender-asn`	int	`65001`	Sender autonomous system number
`--sender-port`	int	`0`	DUT port for sender (0 = use `--dut-port`)
`--receiver-addr`	string	`127.0.0.2`	Receiver local address
`--receiver-asn`	int	`65002`	Receiver autonomous system number
`--receiver-port`	int	`0`	DUT port for receiver (0 = use `--dut-port`)

Benchmark flags:

Flag	Type	Default	Purpose
`--routes`	int	`1000`	Number of routes to inject
`--family`	string	`ipv4/unicast`	Address family (`ipv4/unicast` or `ipv6/unicast`)
`--force-mp`	bool	`false`	Force MP_REACH_NLRI for IPv4 unicast
`--seed`	uint64	`0`	Deterministic seed (0 = random)
`--warmup`	duration	`2s`	Warmup delay after session establishment
`--connect-timeout`	duration	`10s`	TCP connection timeout
`--duration`	duration	`60s`	Maximum time to wait for convergence per iteration

Iteration flags:

Flag	Type	Default	Purpose
`--repeat`	int	`5`	Number of benchmark iterations
`--warmup-runs`	int	`1`	Warmup iterations (discarded from results)
`--iter-delay`	duration	`3s`	Delay between iterations
`--batch-size`	int	`0`	UPDATE batch size (0 = single UPDATE per prefix)

Output flags:

Flag	Type	Default	Purpose
`--json`	bool	`false`	JSON output
`--output`	string		Output file path (implies `--json`)

Exit codes: 0 = success, 1 = error (missing flags, validation failure, benchmark failure).

ze-perf report

Generate a comparison report from one or more result JSON files.

ze-perf report result-ze.json result-gobgp.json
ze-perf report --html result-ze.json result-gobgp.json > report.html

Flag	Type	Default	Purpose
`--md`	bool	`true`	Markdown output
`--html`	bool	`false`	HTML output (overrides `--md`)

Reads result JSON files produced by ze-perf run --json and generates a side-by-side comparison table.

ze-perf track

Track performance history and detect regressions from an NDJSON file.

ze-perf track history.ndjson
ze-perf track --check history.ndjson
ze-perf track --html history.ndjson > trend.html
ze-perf track --check --threshold-convergence 15 history.ndjson

Flag	Type	Default	Purpose
`--md`	bool	`true`	Markdown output
`--html`	bool	`false`	HTML output (overrides `--md`)
`--check`	bool	`false`	Check for regressions (exit 1 on regression)
`--last`	int	`0`	Only consider last N entries (0 = all)
`--threshold-convergence`	int	`20`	Convergence regression threshold (%)
`--threshold-throughput`	int	`20`	Throughput regression threshold (%)
`--threshold-p99`	int	`30`	P99 latency regression threshold (%)

Exit codes: 0 = no regression (or report mode), 1 = regression detected or error.

Runtime Commands

Commands sent to the running daemon. Access through three entry points:

Entry	Access	Usage
`ze cli`	Full (interactive)	Exploration, monitoring
`ze show <cmd>`	Read-only	Scripting, dashboards

Note: Some ze show subcommands run locally without a daemon (version, bgp decode/encode, env, schema, yang, completion). These are dispatched via local handlers before attempting SSH connection.

ze cli accepts -c <command> for single-shot execution and --format <format> (default: yaml).

Peer Selector

Many commands take a peer <selector> argument:

Selector	Example	Description
`*`	`peer *`	All peers
Name	`peer upstream1`	By configured peer name
IP address	`peer 10.0.0.1`	By peer IP
ASN	`peer as65001`	By remote ASN, case-insensitive (matches all peers with that ASN)
Glob	`peer 192.168..`	Pattern match
Exclusion	`peer !10.0.0.1`	All except this peer
ASN exclusion	`peer !as65001`	All except peers with this ASN

Peer Commands

Command	Access	Purpose
`peer list`	read-only	List all peers (IP, ASN, state, uptime)
`peer <sel> detail`	read-only	Detailed peer info (config, state, counters, `prefix-updated` date, `prefix-stale` warning)
`peer <sel> capabilities`	read-only	Negotiated capabilities
`peer <sel> statistics`	read-only	Per-peer update statistics with rates
`bgp summary`	read-only	BGP summary table (all peers)
`bgp summary <afi/safi>`	read-only	Per-family summary: filter to peers that negotiated this AFI/SAFI. Shorthands `ipv4`, `ipv6`, `l2vpn` expand to `ipv4/unicast`, `ipv6/unicast`, `l2vpn/evpn`. Unknown or un-negotiated families reject with the list of families currently negotiated on this daemon. Response adds `family` + `peers-in-family`; `peers-established` is the filtered count
`peer <sel> pause`	write	Pause read loop (flow control)
`peer <sel> resume`	write	Resume read loop
`peer <sel> teardown [<code>] [<msg>]`	write	Graceful close with NOTIFICATION
`peer <sel> flush`	write	Block until all queued updates for peer are on the wire

Set Commands

Command	Access	Purpose
`set bgp peer <name> with <config>`	write	Create peer with configuration
`set bgp peer <sel> save`	write	Save running peers to config

Peer Config Keys

Config keys are parsed from the YANG peer-fields schema via ParseInlineArgs. Container prefixes (remote, local) scope sub-keys. The parser walks the YANG tree to determine how many tokens each field consumes (leaf = name + value, container = name + recurse into children).

Key	Value	Required	Description
`remote ip`	IP address	Yes	Peer remote IP address
`remote as`	ASN (uint32)	Yes	Peer AS number
`local as`	ASN (uint32)	No	Local AS override
`local ip`	IP address	No	Local IP for this session
`router-id`	IPv4 address	No	Router ID override
`timer hold-time`	seconds (0-86400)	No	Hold time (default: 90)
`timer connect-retry`	seconds	No	Connect retry interval (default: 120)
`remote connect`	true/false	No	Initiate outbound connections (default: true)
`local accept`	true/false	No	Accept inbound connections (default: true)
`description`	text	No	Peer description
`link-local`	IPv6 address	No	Link-local next-hop
`port`	1-65535	No	Per-peer listen port
`group-updates`	enable/disable	No	UPDATE grouping

Example: set bgp peer upstream1 with remote ip 10.0.0.1 remote as 65001 local as 65000 timer hold-time 90 remote connect false

Del Commands

Command	Access	Purpose
`del bgp peer <sel>`	write	Remove peer

Update Commands

Command	Access	Purpose
`update bgp peer <sel> prefix`	write	Update prefix maximums from PeeringDB

Route Injection

peer <sel> update text <attrs> nlri <family> <op> <prefixes>
peer <sel> update hex <hex-data>
peer <sel> update b64 <b64-data>
peer <sel> raw [<type>] <encoding> <data>

Text format attributes:

Attribute	Syntax
`origin`	`origin set igp` / `egp` / `incomplete`
`nhop`	`nhop set 192.168.1.1` or `nhop set self`
`med`	`med set 100`
`local-preference`	`local-preference set 200`
`as-path`	`as-path set [ 65001 65002 ]`
`community`	`community set [ 65000:100 no-export ]`
`large-community`	`large-community set [ 65000:1:1 ]`
`extended-community`	`extended-community set [ rt:65000:100 ]`

NLRI operations: nlri <family> add <prefixes>, nlri <family> del <prefixes>, nlri <family> eor.

RIB Commands

Command	Access	Purpose
`rib status`	read-only	RIB summary (peer count, routes, families)
`rib routes [received\|sent] [peer] [family]`	read-only	Adj-RIB-In/Out inspection
`rib show best [<prefix>]`	read-only	Best-path per prefix
`rib show best status`	read-only	Best-path computation status
`rib clear in <selector>`	write	Clear Adj-RIB-In (`*` for all peers)
`rib clear out <selector> [family]`	write	Regenerate and re-advertise Adj-RIB-Out (`*` for all peers, optional family filter)
`rib inject <peer> <family> <prefix> [attrs...]`	write	Insert route into Adj-RIB-In as if received from peer
`rib withdraw <peer> <family> <prefix>`	write	Remove route from Adj-RIB-In

Healthcheck Commands

Command	Access	Purpose
`healthcheck show`	read-only	JSON summary of all healthcheck probes
`healthcheck show <name>`	read-only	Detailed status of a single probe
`healthcheck reset <name>`	write	Withdraw route, reset FSM to INIT, immediate re-check. Error if DISABLED.

BMP (RFC 7854)

Command	Access	Purpose
`bmp sessions`	read-only	Show active BMP receiver sessions (router address, sysName, uptime)
`bmp peers`	read-only	Show monitored BGP peers (AS, BGP ID, up/down status)
`bmp collectors`	read-only	Show BMP sender collector connection status

Commit (Atomic Updates)

Command	Access	Purpose
`commit <name> start [peer]`	write	Begin named update window
`commit <name> end`	write	Flush queued updates
`commit <name> eor`	write	Flush updates and send End-of-RIB
`commit <name> show`	read-only	Show queue status
`commit <name> rollback`	write	Discard queued updates
`commit <name> withdraw route <prefix>`	write	Withdraw prefix from window
`commit list`	read-only	List active commits

Cache Commands

Command	Access	Purpose
`cache list`	read-only	List cached message IDs
`cache <id> retain`	write	Pin in cache (prevent eviction)
`cache <id> release`	write	Release from cache
`cache <id> expire`	write	Remove immediately
`cache <id> forward <peer-sel>`	write	Re-inject UPDATE to peer(s)

Batch operations: cache <id1>,<id2> <action> [args].

Static Routes

Command	Access	Purpose
`static show`	read-only	Show all configured static routes in JSON: prefix, action, next-hops with address/weight/BFD status, metric, tag

The static route plugin programs routes directly to the kernel (netlink multipath) or VPP. It auto-loads when the config contains a static { } section. See Static Routes Guide.

Sysctl (Kernel Tunables)

Command	Access	Purpose
`sysctl show`	read-only	Show all active sysctl keys with value, source (config/transient/default), and persistence
`sysctl list`	read-only	List all known sysctl keys with descriptions and types
`sysctl describe <key>`	read-only	Show detail for one key: description, type, range, current value, source
`sysctl set <key> <value>`	write	Set a transient sysctl value (overrides defaults, blocked by config)
`sysctl list-profiles`	read-only	List all registered sysctl profiles (built-in and user-defined) with key counts
`sysctl describe-profile <name>`	read-only	Show detail for one profile: description, all key/value pairs

The sysctl plugin manages kernel tunables with three-layer precedence: config (persistent, from YANG) wins over transient (CLI sysctl set), which wins over defaults (plugin-declared via EventBus). Original values are restored on clean daemon stop.

Config example: sysctl { setting net.ipv4.conf.all.forwarding { value 1; } }

Named profiles group co-dependent tunables for common use cases. Apply them per interface unit: sysctl-profile [ dsr hardened ]. Built-in profiles: dsr, router, hardened, multihomed, proxy. User-defined profiles declared in sysctl { profile <name> { ... } }.

When fib-kernel is loaded, it automatically enables IPv4 and IPv6 forwarding as defaults.

L2TPv2 (Operational)

Command	Access	Purpose
`show l2tp`	run	L2TP subsystem summary (tunnel/session counts)
`show l2tp tunnels`	run	List all active L2TP tunnels
`show l2tp tunnel <tid>`	run	Show one tunnel by local tunnel ID
`show l2tp sessions`	run	List all active L2TP sessions
`show l2tp session <sid>`	run	Show one session by local session ID
`show l2tp statistics`	run	Protocol counters
`show l2tp listeners`	run	Bound UDP listener endpoints
`show l2tp config`	run	Effective runtime configuration
`show l2tp observer <sid>`	run	Per-session event ring snapshot (timestamps, types, RTT, reasons)
`show l2tp observer all`	run	Summary of all active session event rings
`show l2tp cqm <login>`	run	Per-login CQM bucket history (100s echo RTT/loss aggregates)
`show l2tp cqm summary`	run	Aggregate CQM state across all tracked logins
`show l2tp echo <login>`	run	Current echo state for a login (RTT, loss ratio, interval)
`show l2tp reliable <tid>`	run	Reliable transport window state (Ns, Nr, cwnd, retransmits)
`clear l2tp tunnel teardown <tid>`	run	Send StopCCN for one tunnel
`clear l2tp tunnel teardown-all`	run	Send StopCCN for every tunnel
`clear l2tp session teardown <sid> [reason <text...>] [cause <code>]`	run	Send CDN for one session with optional audit reason and disconnect cause
`clear l2tp session teardown-all`	run	Send CDN for every session

The clear l2tp session teardown command accepts optional keyword arguments:

reason <text...>: free-text audit reason, recorded in the per-session event ring
cause <code>: RADIUS Disconnect-Cause value (uint16), recorded alongside the reason

L2TPv2 Web UI

The web interface at /l2tp provides session management and CQM graphing.

URL	Method	Purpose
`/l2tp`	GET	Session list with sortable columns
`/l2tp/<sid>`	GET	Session detail: state, PPP options, CQM chart, event timeline, disconnect
`/l2tp/<login>/samples`	GET	CQM buckets as columnar JSON (uPlot data shape)
`/l2tp/<login>/samples.csv`	GET	CQM buckets as CSV download
`/l2tp/<login>/samples/stream`	GET	SSE stream pushing new CQM buckets every 100s
`/l2tp/<sid>/disconnect`	POST	Disconnect session (requires `reason` form field; optional `cause`)

Disconnect is gated by authz: the clear prefix is denied in the built-in read-only profile. The CQM chart uses vendored uPlot rendered client-side with CSS color variables (--color-l2tp-established, --color-l2tp-negotiating, --color-l2tp-down).

L2TPv2 (Offline Tools)

Command	Access	Purpose
`l2tp decode [--pretty]`	offline	Decode a hex L2TPv2 control message on stdin and emit JSON on stdout

ze l2tp decode runs without a daemon. Input is ASCII hex (whitespace allowed); output is a JSON object with a parsed header and an avps array. Each AVP carries its vendor, numeric type, RFC 2661 catalog name (when vendor 0), flag booleans, and the raw value as lowercase hex. Use --pretty for indented output.

Example:

echo c8020044... | ze l2tp decode --pretty

Exit code is 0 on successful parse, 1 on invalid hex, truncated header, or malformed AVPs; stderr carries the reason.

Event Monitoring

bgp monitor [peer <sel>] [event <types>] [direction <dir>]

Filter	Values
`peer`	IP address, `*`
`event`	update, open, notification, keepalive, refresh, state, negotiated (comma-separated)
`direction`	sent, received

Streaming command: use in interactive ze cli or via SSH.

Metrics

Command	Access	Purpose
`metrics show`	read-only	Prometheus text format metrics
`metrics list`	read-only	List metric names
`metrics pool`	read-only	Per-attribute-pool occupancy, dedup rates, and aggregate totals (13 BGP pools)

Logging

Command	Access	Purpose
`log show`	read-only	List subsystems with current log levels
`log set <subsystem> <level>`	write	Set log level at runtime

Levels: debug, info, warn, err, disabled.

Plugin Configuration (from plugin context)

Command	Access	Purpose
`bgp plugin encoding <json\|text>`	write	Set event encoding
`bgp plugin format <hex\|base64\|parsed\|full>`	write	Set wire format display
`bgp plugin ack <sync\|async>`	write	Set ACK timing

Discovery

Command	Access	Purpose
`help`	read-only	List available subcommands
`command-list`	read-only	List all commands with descriptions
`command-help <name>`	read-only	Detailed help for a command
`event-list`	read-only	List available event types

Interactive CLI Features

Inside ze cli:

Feature	Syntax
Pipe: filter lines	`peer list \| match established`
Pipe: count	`peer list \| count`
Pipe: table format	`rib routes \| table`
Pipe: JSON pretty	`peer list \| json`
Pipe: JSON compact	`peer list \| json compact`
Pipe: disable paging	`peer list \| no-more`
Tab completion	Contextual command/argument completion

Signal Handling

The daemon handles these Unix signals directly:

Signal	Effect
`SIGHUP`	Reload configuration
`SIGTERM` / `SIGINT`	Graceful shutdown
`SIGUSR1`	Dump status to stderr

FilesExpand file tree

command-reference.md

Latest commit

History