system

Pre-Alpha. This page describes behavior that may change.

The system { } block carries the identity of the Ze instance and the global settings that do not belong to a specific subsystem. Hostname and domain for archive filenames and log tags, user management for the SSH server, TLS listeners for the web UI and the Looking Glass, logging targets, and a few smaller knobs. The environment { } block sits alongside it and carries the cross-cutting runtime options.

This page covers the operator-facing pieces. The in-tree configuration guide carries the deeper material on any single block.

System identity

system {
    host   router1;
    domain dc1.example.com;
}

host and domain appear in archive filenames, in the SSH banner, and in log lines. Both support $ENV expansion: a value that starts with $ is looked up as an environment variable.

system {
    host   $HOSTNAME;
    domain $DOMAIN;
}

If the environment variable is empty or unset, the literal string is kept. When host is not configured, it defaults to os.Hostname().

Users and SSH

The user database and the SSH host key live in the Ze blob storage (database.zefs) and are created by ze init. ze init is interactive by default and prompts for a username, a password, an SSH host, and an SSH port. Defaults are 127.0.0.1:2222 and an auto-generated ED25519 host key.

Re-initialisation is blocked unless you pass --force. Force moves the old database to database.zefs.replaced-<date> as a backup and creates a new one, and it only works interactively so a piped stdin cannot accidentally wipe your credentials.

The SSH server shares the same user database as the web UI and the REST API. There is one list of users, and every surface reads from it.

Two forms of password are accepted in the config: password "$2a$10$..." (pre-hashed bcrypt) and plaintext-password "secret" (auto-hashed to bcrypt at commit time and removed from the persisted config). The password is never stored in plaintext.

SSH public key authentication

Users can authenticate with SSH public keys instead of (or in addition to) passwords. Supported key types: ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521. Multiple keys per user are supported.

Static DNS nameservers

The system { nameserver { } } block configures static DNS nameservers for the Ze daemon's own resolver:

system {
    nameserver {
        primary 8.8.8.8;
        secondary 8.8.4.4;
    }
}

Web UI listener

environment {
    web {
        enabled true;
        server main {
            ip   0.0.0.0;
            port 3443;
        }
    }
}

When no TLS certificate is configured, Ze generates an ECDSA P-256 self-signed certificate on first start with SANs for localhost, 127.0.0.1, ::1, and the listen address. Real production deployments should put a real certificate in front of the port.

The --insecure-web command-line flag turns off authentication and forces the listener back to 127.0.0.1. It exists for development. Do not use it on a public interface.

Looking Glass listener

environment {
    looking-glass {
        enabled true;
        server main {
            ip   0.0.0.0;
            port 3443;
        }
    }
}

The Looking Glass runs on its own port, separate from the web UI. It is read-only and unauthenticated by design. TLS is optional (tls true).

See looking-glass for the deeper reference.

MCP listener

environment {
    mcp {
        enabled true;
        server main {
            ip   127.0.0.1;
            port 8080;
        }
    }
}

The MCP server defaults to 127.0.0.1:8080. That is deliberate: MCP is local-only unless you explicitly override it. Bearer-token authentication is available through ze.mcp.token or the token leaf.

Logging

environment {
    log {
        level        warn;
        backend      stderr;
        bgp.reactor  debug;
        bgp.routes   info;
        plugin.relay warn;
    }
}

level is the base level for every subsystem. The per-subsystem leaves override it. Backends are stderr (default), stdout, or syslog (with a destination). Full coverage in logging.

DNS resolver

Ze has a built-in cached DNS resolver. Every component uses it, so there is one cache and one set of settings instead of one per subsystem.

environment {
    dns {
        server     8.8.8.8:53;
        timeout    5;
        cache-size 10000;
        cache-ttl  86400;
    }
}

Field	Default	Description
server	""	Upstream DNS server. Empty uses /etc/resolv.conf.
timeout	5	Query timeout in seconds (1 to 60).
cache-size	10000	Maximum cache entries. 0 disables caching.
cache-ttl	86400	Maximum cache TTL in seconds. 0 uses only the response TTL.

The cache respects DNS response TTLs: entries expire at min(response TTL, cache-ttl). Records with TTL 0 are never cached (RFC 1035).

TCP and reactor settings

environment {
    tcp {
        attempts 3;
    }

    reactor {
        update-groups true;
    }
}

tcp/attempts controls the connection retry count. reactor/update-groups toggles the cross-peer UPDATE grouping optimisation: when enabled (the default), peers that share the same encoding context share a single UPDATE build, and the wire bytes are fanned out to every group member. Disable it for ExaBGP-compatibility or when debugging per-peer encoding issues.

PeeringDB integration

system {
    peeringdb {
        url    "https://www.peeringdb.com";
        margin 10;
    }
}

Used by ze resolve peeringdb max-prefix <ASN>, which queries PeeringDB for each peer's ASN and updates the prefix maximums automatically with the configured margin. The URL is configurable for private mirrors.

SSH server

The SSH server is configured under environment { ssh { } }. It is disabled by default and must be explicitly enabled. The host key and user database are created by ze init.

environment {
    ssh {
        enabled true;
        host-key /etc/ze/ssh_host_ed25519_key;
        idle-timeout 600;
        max-sessions 16;
        server main {
            ip   0.0.0.0;
            port 2222;
        }
    }
}

Leaf	Type	Default	Description
enabled	boolean	false	Enable the SSH server.
host-key	string	config dir + ssh_host_ed25519_key	Path to the host key file. Auto-generated if missing.
idle-timeout	uint32	600	Idle timeout in seconds before a session is closed.
max-sessions	uint16	—	Maximum concurrent SSH sessions.

The server list works the same as the web and looking-glass listeners: each entry has a name, an ip (default 0.0.0.0), and a port (default 2222). You can define more than one listener if you need to bind to multiple addresses.

Plugin configuration

Plugins are declared under plugin { }. Use internal with use for built-in plugins and external with run for external process plugins.

plugin {
    # Built-in plugin (in-process, lowest latency)
    internal rib {
        use bgp-rib
    }

    # External plugin (separate process, any language)
    external my-filter {
        run      "/usr/local/bin/my-filter --json";
        encoder  json;
        respawn  true;
        timeout  10s;
    }
}

Leaf	Type	Description
name	string (1..64)	Plugin name (the list key).
use	string	Built-in plugin name. Mutually exclusive with run.
run	string	Command line to execute (external process). Mutually exclusive with use.
encoder	enum: json, text	Event encoding format.
respawn	boolean	Respawn the process if it exits (external only).
timeout	string	Startup timeout (e.g. 10s, 1m).

See External plugins for the full development guide covering the stdin/stdout protocol, event types, and worked examples.

Environment tuning

The environment { } block contains several sub-containers that control process management, plugin API behaviour, debug toggles, and protocol-level knobs. All leaves have sensible defaults; you only need to set them when tuning or troubleshooting.

daemon

Process management. Controls privilege dropping and daemonisation.

environment {
    daemon {
        pid       /run/ze.pid;
        user      zeuser;
        daemonize true;
        drop      true;
        umask     0137;
    }
}

Leaf	Type	Default	Description
pid	string	—	PID file path.
user	string	zeuser	System user for privilege drop.
daemonize	boolean	—	Run as a background daemon.
drop	boolean	true	Drop privileges after startup.
umask	string	0137	File creation mask (octal).

api

Plugin API tuning. Affects how Ze communicates with external processes.

Leaf	Type	Default	Description
ack	boolean	true	Acknowledge API commands.
chunk	int32	1	Maximum lines before yield.
encoder	enum: json, text	json	Default encoder for the plugin API.
compact	boolean	—	Compact JSON encoding for INET.
respawn	boolean	true	Respawn dead plugin processes.
terminate	boolean	—	Terminate Ze if a plugin process dies.
cli	boolean	true	Create the CLI named pipe.

debug

Debug toggles. All are off by default unless noted.

Leaf	Type	Description
pdb	boolean	Enable Python debugger (legacy).
memory	boolean	Track memory usage.
configuration	boolean	Debug configuration parsing.
selfcheck	boolean	Run internal consistency checks.
route	string	Debug a specific route prefix.
defensive	boolean	Enable defensive checks.
rotate	boolean	Rotate debug output files.
timing	boolean	Log operation timing.
pprof	string	pprof HTTP server address (e.g. :6060).

chaos

Fault injection for testing. Disabled unless seed is set to a non-zero value.

Leaf	Type	Default	Description
seed	int64	—	PRNG seed. 0 disables fault injection.
rate	string	0.1	Fault probability per operation (0.0-1.0).

cache

Attribute deduplication cache. Reduces memory when many peers share identical path attributes.

Leaf	Type	Default	Description
attributes	boolean	true	Cache path attributes for deduplication.

bgp

Protocol-level BGP environment knob.

Leaf	Type	Default	Description
openwait	int32	120	Seconds to wait for OPEN after TCP connect.

Serial console

For headless CPE devices, Ze can configure serial console ports. Works on both gokrazy (no systemd) and standard Linux via termios. On systemd hosts, detects active serial-getty and skips the device with a warning.

system {
    console {
        device ttyS0 {
            speed 115200;
        }
    }
}

Field	Type	Default	Description
device/<name>	list key	--	Serial device name (bare name, e.g. ttyS0, ttyUSB0).
device/<name>/speed	enum	115200	Baud rate: 9600, 19200, 38400, 57600, 115200.

Connection tracking

Declarative connection tracking management under system { conntrack { } }. Controls helper module loading, table sizing, per-protocol timeouts, and TCP behavior flags.

system {
    conntrack {
        module [ ftp sip ];
        table-size 262144;
        hash-size  65536;
        accounting;
        tcp {
            timeout-established 7200;
            be-liberal;
        }
    }
}

Helper modules

Loaded via modprobe on boot. Load-only: removing a module from config stops loading on next boot but does not unload at runtime.

Module	Kernel module
ftp	nf_conntrack_ftp
h323	nf_conntrack_h323
sip	nf_conntrack_sip
pptp	nf_conntrack_pptp
tftp	nf_conntrack_tftp
sane	nf_conntrack_sane
irc	nf_conntrack_irc
amanda	nf_conntrack_amanda
netbios-ns	nf_conntrack_netbios_ns
snmp	nf_conntrack_snmp
nfs	nf_conntrack_nfs
sqlnet	nf_conntrack_sqlnet

Table sizing

Field	Type	Range	Description
table-size	uint32	1..2097152	Maximum conntrack table entries (nf_conntrack_max).
hash-size	uint32	1..2097152	Hash table buckets (nf_conntrack_buckets).
expect-max	uint16	1..65535	Maximum expected connections (nf_conntrack_expect_max).

Global flags

Field	Effect
accounting	Enable per-connection byte/packet counters.
timestamp	Enable per-connection timestamps.

Sysctl values are routed through the sysctl plugin via EventBus. Keys managed by conntrack are rejected if also set in sysctl { } (dual-setting prevention).

CLI

show system conntrack       # Live state from /proc/sys

Storage SMART management

YANG-modeled disk health monitoring under storage { }. SMART auto-enables on detected ATA and NVMe devices and polls health periodically. Temperature alerting is three-tier: an informational warning, a rate-of-change warning, and a critical error, all raised on the report bus. Scheduled self-tests run short daily and extended weekly (with a day-of-week constraint), and an in-progress test is detected so duplicate tests are skipped. It is pure ioctl, with no smartctl binary, so it is gokrazy-safe. ze doctor verifies SMART accessibility when enabled.

show storage smart

Per-device output covers health, temperature, power-on hours, error count, NVMe percent-used and available-spare, and the self-test schedule.

PKI certificate store

The pki { } block holds CA certificates and device certificates with private keys, shared by the IPsec and TLS consumers. Certificates are parsed from base64-DER, private keys are detected as PKCS8/SEC1/PKCS1, and key material uses $9$ sensitive encoding. The store validates chains, checks expiry (health degraded at 30 days, down when expired), and raises report-bus warnings as expiry approaches.

show pki certificates
show pki certificate <name>
show pki certificate <name> pem
show pki certificate <name> bundle pem
show pki certificate <name> fingerprint

The pem and bundle pem sub-commands export PEM for downstream consumers; fingerprint shows the certificate fingerprint.

Self-update

Ze can periodically check for updates, and optionally download, verify, and install them automatically. The full feature covers fleet-scale rollout with spread scheduling, maintenance windows, and server-side pause.

Check-only (default)

system {
    update-check {
        url      "https://updates.example.com/ze/version.json";
        interval 86400;
    }
}

Field	Type	Default	Description
url	string	--	HTTPS URL serving the version manifest.
interval	uint32	86400	Check interval in seconds (range 60..604800, default daily).

Automated updates

system {
    update-check {
        url https://update.example.com/version.json;
        interval 3600;
        auto-apply true;
        spread 1800;
        maintenance-window {
            start 02:00;
            end 06:00;
        }
        restart {
            time 03:00;
        }
    }
}

Field	Type	Default	Description
auto-apply	boolean	false	Enable automated download, verify, and stage.
spread	uint32	3600	Maximum random delay before download (deterministic per device+version).
maintenance-window/start	string	--	Start of binary replacement window (HH:MM).
maintenance-window/end	string	--	End of binary replacement window (HH:MM).
restart/time	string	--	Restart time (HH:MM). Use restart { immediate; } for immediate restart.

SHA-256 verified download, atomic binary replacement via rename with .prev rollback. Manual CLI commands: update system firmware {check,download,apply,restart,rollback}. See Self-Update for the full guide.

ze update-serve

Standalone update server for build infrastructure:

ze update-serve --listen :8080

Serves an enhanced manifest at /version.json, binaries at /<goos>/<goarch>, and SHA-256 digests. Supports file-based and SIGUSR1 pause toggling.

System readiness: ze doctor

Offline pre-start checks to verify the environment is ready.

ze doctor
ze doctor --json config.conf
ze explain <code>

ze doctor detects the runtime platform (gokrazy, systemd, container, plain-linux, darwin) and probes its capabilities, then runs platform-aware coherence checks (gokrazy /perm writability, container read-only root, machine-id presence). It is config-driven: it verifies the runtime dependencies the config declares, including BGP MD5 support, the VPP API socket, the IPsec path, NTP/RPKI/BMP reachability, writable destinations, and random-seed persistence.

Checks: config syntax, YANG validation, TLS certs, VPP socket and version, kernel modules, interfaces, SSH host key, listener conflicts, plugins, storage integrity, dangling config references, disk space, DNS resolver, clock skew. --json emits stable diagnostic codes; ze explain <code> gives remediation guidance. Exit code 0 means ready. See Health Checks for the full check list.

Tech-support bundle: ze support

ze support generates an offline tech-support archive with 20 pure-Go collection modules (no shell-outs, gokrazy-safe), one JSON file per module.

ze support
ze support --module config,routes
ze support --exclude crashes
ze support --since 1h
ze support --sensitive --reason "ticket-1234"
ze support --json

Privacy-by-default keeps secrets out unless --sensitive is given. The archive is named ze-support-<hostname>-<timestamp>.tar.gz. See Health Checks for the module list.

Runtime health

show health

The health registry aggregates status from running components (bgp, fib, firewall, iface, plugins, vpp, ipsec, pki, l2tp). Reports healthy, degraded, or down. The /health HTTP endpoint returns HTTP 503 when any component is down. See Health Checks.

Crash capture

Automatic stderr redirect captures panic stack traces from any goroutine. Forwarded to syslog and persisted to crash files on disk. Crash reports are enriched with build and runtime metadata (version, build date, uptime) and ring buffer context (last 64 log entries before the panic). Panics caught by the bubbletea TUI produce a full crash report rather than a bare stack trace.

show crashes
show crashes latest

Crash directory: /perm/ze/crash/ on gokrazy, fallback chain for other platforms. Configurable via ze.crash.dir and ze.crash.keep environment variables.

Debug flags

Persistent per-subsystem debug flags are stored in ZeFS and survive daemon restarts. They are applied after the config-driven log levels during startup. Resolution is three-tier: a global override wins, then a per-subsystem key, then the default (off). Hierarchical prefixes work, so enabling bgp covers all bgp.* subsystems.

ze debug enable bgp
ze debug enable all
ze debug disable bgp.reactor
ze debug show

Config schema stamp

Config files carry a schema version stamp. On load, Ze checks the stamp against its current schema version. When loading a config from a newer version, downgrade recovery kicks in: incompatible fields are pruned and a warning is logged.

Graceful listener migration

When a config reload changes listener endpoints (web UI, Looking Glass, REST, gRPC, MCP), Ze migrates gracefully: the new listener starts before the old one stops. In-flight connections on the old listener are drained before close.

See also

• Overview for the surrounding config model.
• Editor workflow for the commit workflow.
• Logging for the log surface.
• Looking Glass, Web UI, MCP for the operator surfaces these blocks configure.
• Health Checks for the health registry and report bus.
• Self-Update for the full self-update guide.
• Production Diagnostics for the diagnostic commands.

Adapted from main/docs/guide/configuration.md.