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 unknown. Ze does not fall back to os.Hostname() automatically: the operator decides.

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.

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 { external { } }. Use use for built-in plugins and run for external process plugins.

plugin {
    # Built-in plugin (in-process, lowest latency)
    external rib {
        use      bgp-rib;
        encoder  json;
    }

    # 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.

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.

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