Guide

Quick Start

Run two Ze peers on one Linux host and verify that each receives a route. The supplied lab uses loopback addresses and ports above 1024. It needs no external router or development test peer. Ze is pre-release software; use an isolated lab.

To run Ze as a service, in a container or as an appliance instead, see Choose a deployment path.

Build

git clone https://github.com/ze-software/ze.git
cd ze
./ze version

Install Go and Git first. The Go version in go.mod is the supported toolchain; the launcher selects that version and builds bin/ze with Ze's patched standard library when the binary is absent. A first build takes longer than starting an existing binary. Windows is not a supported runtime platform.

Optional: install the built command on PATH

From the same checkout, select the patched toolchain before using go install. This installs the daemon on your Go binary path; it does not create a system service. The default feature tags below are derived from feature-gates.txt.

GOROOT="$(go run ./internal/le/go/stdpatch/goroot)"
export GOROOT GOTOOLCHAIN=local PATH="$GOROOT/bin:$PATH"
CGO_ENABLED=0 go install -tags 'ze_core ze_distro ze_anomaly ze_as112 ze_bfd ze_bgp ze_bmp ze_copp ze_cos ze_ddos ze_dhcpserver ze_exabgp ze_flowexport ze_geodns ze_gnmi ze_grpc ze_ike ze_isis ze_l2tp ze_ldp ze_lg ze_mcp ze_mpls ze_ntp ze_ospf ze_policyroute ze_pxe ze_radius ze_rest ze_rsvpte ze_ssh ze_tacacs ze_telemetry ze_trafficusage ze_vpp ze_vrrp ze_web' ./cmd/ze

The remaining commands use ./ze from the checkout. For a Linux service, follow Linux installation. For a container, use Docker. For an immutable VM or hardware image, use VM Appliance.

Local two-peer lab

The files examples/quickstart/r1.conf and r2.conf declare both ends of the session, explicit import/export policy, and a BGP RIB. Each announces one prefix: 192.0.2.0/24 from r1 and 198.51.100.0/24 from r2. SSH listens on 127.0.0.1:2221 and 127.0.0.1:2222. Both peers use AS 65001 for iBGP. The BGP transport uses 127.0.0.1:1179 and 127.0.0.2:2179; advertised next hops are the documentation addresses 192.0.2.1 and 192.0.2.2. These next hops support route inspection in this control-plane lab; they do not establish forwarding connectivity.

These files contain the known lab username and password lab / lab. They bind management to loopback and disable resolver file output. Do not use these credentials on a production system. Explicit-file startup creates the private store beside each file, so each peer must have its own directory. No ze init step is needed for this configured-user lab; the later initialization section covers a real installation.

Run the following from the repository root in one shell:

mkdir -p tmp
ZE_LAB_DIR="$(mktemp -d "$PWD/tmp/quickstart.XXXXXX")"
mkdir "$ZE_LAB_DIR/r1" "$ZE_LAB_DIR/r2"
cp examples/quickstart/r1.conf "$ZE_LAB_DIR/r1/ze.conf"
cp examples/quickstart/r2.conf "$ZE_LAB_DIR/r2/ze.conf"
./ze config validate "$ZE_LAB_DIR/r1/ze.conf"
./ze config validate "$ZE_LAB_DIR/r2/ze.conf"

./ze start "$ZE_LAB_DIR/r1/ze.conf" >"$ZE_LAB_DIR/r1.log" 2>&1 &
R1_PID=$!
./ze start "$ZE_LAB_DIR/r2/ze.conf" >"$ZE_LAB_DIR/r2.log" 2>&1 &
R2_PID=$!

On Linux, both loopback addresses are available. On macOS, add the second address once before starting the peers: sudo ifconfig lo0 alias 127.0.0.2.

Verify a session and received routes

Run these commands in the same shell. If a listener is still starting, inspect the log files and retry the command after it is ready.

ZE_SSH_PASSWORD=lab ./ze cli --remote 127.0.0.1:2221 --user lab -c "show bgp peer list"
ZE_SSH_PASSWORD=lab ./ze cli --remote 127.0.0.1:2221 --user lab -c "show bgp rib | received"
ZE_SSH_PASSWORD=lab ./ze cli --remote 127.0.0.1:2222 --user lab -c "show bgp rib | received"

The peer list must show an established session. The r1 received RIB must contain 198.51.100.0/24; r2 must contain 192.0.2.0/24. A configured peer or an open management port alone is not this success check. This lab verifies control-plane route exchange; it does not install forwarding routes on the host.

Stop and keep or remove the lab

kill -TERM "$R1_PID" "$R2_PID"
wait "$R1_PID" "$R2_PID"
printf 'Lab files and stores: %s\n' "$ZE_LAB_DIR"

SIGTERM uses Ze's normal shutdown path. Keep the directory if you want to inspect the stores and logs or restart the lab. To discard this lab after both processes stop, remove the directory printed above. It contains only this run's copies.

Use an existing router as the peer

The remainder shows initialization and a configuration for an external peer. Replace the addresses and ASNs with your network's values and configure the other router's BGP session as well. The local lab above supplies both ends when you do not have another router.

Initialize

Ze runs an SSH server on localhost for CLI access (ze cli, ze show, ze signal). This keeps the control plane authenticated even in multi-user environments. Initialize the folder that will hold the example config:

export ZE_CONFIG_DIR="$PWD"
./ze init

This prompts for username, password, SSH host (default 127.0.0.1), port (default 2222), and node name (default: hostname). Credentials are stored locally with bcrypt-hashed passwords. For scripting (later fields fall back to their defaults):

printf 'admin\nREPLACE_WITH_A_STRONG_PASSWORD\n' | ./ze init

Initialization creates a private database/ tree in the selected folder. Every directory under the store is 0700 and every frame file 0600, owned by the caller. Running ze init a second time refuses either an existing tree or a database.zefs seed. To reinitialize, use --force; this preserves the old tree as database.replaced-<stamp> before publishing the fully seeded replacement.

./ze signal stop             # stop daemon first
./ze init --force            # prompts for confirmation, then backs up and reinitializes

--force --yes confirms replacement in a script. Replacement refuses while any process owns the store, regardless of the selected SSH target. Ordinary startup refuses an existing blob without converting it. The diagnostic names ze init --from <blob>, which imports a local blob; the URL form is storage-2. Appliance first boot already imports its seed. ze init --seed writes an explicit blob artifact for appliance builders.

Ze terminal lab

Create ZeFS and commit over SSH

Create the ZeFS database, edit the active configuration through Ze's SSH management plane, and verify the committed setting.

Reproducible
Ze 26.10.093 minutes 7 secondsmacOS and LinuxTerminalZe recorder Plain-text transcript
Read the demonstration transcript
$ ze init
username: admin
password: ***
host [127.0.0.1]: 
port [2222]: 
name [ze]: 
discovered 1 interface(s), wrote initial config
initialized /src/tmp/terminal-demos/state/zefs-config/config/database
$ ze config list
ze.conf
$ ze data check

$ ssh ze-demo show bgp

$ ssh ze-demo
ze# set environment cli format default table
ze# show | compare
ze# commit
Session committed
ze# exit
ze> exit
$ ze cli -c 'show bgp'
$ ze cli -c 'show bgp | text'
$ ze cli -c 'show bgp | display router-id local-as peers-established'
$ ze cli -c 'show bgp | display router-id | fill alpha'
$ ze cli -c 'show bgp | peers'
$ ze cli -c 'show bgp | raw' | head -14
$ ze cli -c 'show bgp | raw' | ze pipe text

`ze init` asks for the operator account, the SSH address and port, and the instance name. The password is not echoed, and Enter accepts the default shown in brackets. The instance name defaults to the hostname, here `ze`, so Ze reads `ze.conf`, the configuration `ze init` writes. `ze init` creates `database.zefs`. The first BGP summary uses the default text format. The SSH editor commits the format setting back to ZeFS, not to a second flat file, and the same operational command immediately uses the committed default. The last commands show the two ways to override that default, and they are different pipes. `show bgp | text` is Ze's own operator, inside the quoted command, and it wins over the committed setting. Then `| raw` on its own shows what every one of these renderings is made from: the payload as the daemon holds it, unrendered. The last command sends that same payload across a real shell pipe, and `ze pipe text` formats it on this side, which is how output captured earlier is formatted later. The command is `ze pipe` rather than `ze format` because the operator language also carries `match`, `count`, `first`, `last` and `resolve`, so `format` would name one clause of it. Every command answers with structured data, so `text`, `table`, `json`, `yaml` and `ndjson` all render the same payload. Three commands in the middle choose WHICH of that payload to read. `display` names the fields wanted, in the order wanted, and shows those alone. `fill` brings back the fields it did not name, and `alpha` orders them by field name. `peers` is an alias, which is a name for a pipe expression, so one word answers the per-peer rows without the totals beside them. Each command declares its own column order, so a table leads with the fields an operator reads first rather than with the alphabet.

Minimal Config

Save as example.conf:

static {
    table default {
        route 172.16.0.0/24 {
            next {
                hop 10.0.0.1 {
                }
            }
        }
    }
}

redistribute {
    destination bgp {
        import static
    }
}

bgp {
    router-id 10.0.0.1
    session {
        asn {
            local 65000
        }
    }

    peer test-peer {
        connection {
            remote {
                ip 10.0.0.2
            }
            local {
                ip 10.0.0.1
            }
        }

        session {
            asn {
                local 65000
                remote 65001
            }
            family {
                ipv4/unicast {
                    prefix {
                        maximum 1000000
                    }
                }
            }
        }

        filter {
            export {
                final accept
            }
        }

        update {
            attribute {
                origin igp
                next-hop 10.0.0.1
            }
            nlri {
                ipv4/unicast add 192.168.1.0/24
            }
        }
    }
}

This advertises two prefixes to test-peer, one by each of the routes Ze gives you to get a prefix into BGP:

  • Redistribution (172.16.0.0/24): a static route pulled into BGP by the top-level redistribute { destination bgp { import static } } block. Every source protocol (static, connected, kernel, ospf, isis, ...) redistributes into any destination the same way -- this is how interface and interior-gateway routes reach your peers.
  • Direct announcement (192.168.1.0/24): a prefix declared inline on the peer in its update {} block, sent when the session establishes. The automatic End-of-RIB marker follows Ze's own routes and the separate peer-up registration barrier, not a plugin's session-ready route report (owner ruling, 2026-09-18). behavior { manual-eor true } suppresses that automatic marker, not the routes.

The filter { export { final accept } } block is required: test-peer is an EBGP peer (AS 65001), and with no export policy Ze sends an EBGP peer no routes at all (RFC 8212 Section 3), originated ones included. See BGP policy.

Advanced: a process binding attaches a plugin or your own external program to a peer (the ExaBGP-style event API), including making a peer RIB-backed so it stores and re-advertises received routes. It is not needed for the config above; see Plugins.

Validate

./ze config validate example.conf

Expected output:

configuration valid: example.conf

Start

./ze start example.conf

With no file, ze start uses the config the store names, and refuses with exit 1 if the store's instance name cannot be read; ze doctor checks the store.

The config path goes behind the start keyword. A bare ./ze example.conf is rejected with unknown command: example.conf (exit 1); global flags such as -d are consumed before the keyword, so they stay ahead of it.

An explicit path selects the store in that file's folder, before ZE_CONFIG_DIR or the default path. If neither a tree nor a seed exists there, startup creates a private tree. Every explicit-file start reads the supplied file; daemon commits update that file and stored history. Bare ze start uses the stored active config instead. Keep ZE_CONFIG_DIR set in the second terminal so CLI commands read the credentials from the same folder.

Ze logs to stderr. You should see something like:

level=INFO  msg="hub ready" subsystem=hub plugins=1 peers=1 listen=":179"
level=INFO  msg="peer connecting" subsystem=bgp.reactor peer=test-peer address=10.0.0.2

Silence means the default log level (warn) has nothing to report -- that's normal. To see all activity:

./ze -d start example.conf  # debug logging

Verify

In another terminal:

# Check daemon is running
./ze status

# List peers
./ze cli -c "show bgp peer list"

# Show peer details
./ze cli -c "show bgp peer test-peer detail"

# Watch live events (streams until Ctrl-C)
./ze cli -c "monitor event"

Test Without a Real Peer

Use the local two-peer lab above for route verification. Developers who only need a protocol sink can start the repository's test peer through the le launcher:

# Terminal 1: start a sink peer (accepts sessions, replies keepalive)
./le test peer --mode sink --port 1179 --asn 65001

For this optional sink, copy the external-peer configuration to its own directory and change its peer's connection block to dial 127.0.0.1:1179:

        connection {
            remote {
                ip 127.0.0.1
                port 1179
            }
            local {
                ip 127.0.0.2
            }
        }

The sink's --asn 65001 matches the peer's session { asn { remote 65001 } }.

The two ends carry different addresses on purpose, even here. One machine can hold both, so a loopback demo is the one place a session can be written with one address at each end, and BGP does not work that way: next-hop self then puts the peer's OWN address on the wire, and Ze refuses to advertise that, because RFC 4271 Section 5.1.3 forbids telling a peer to reach a destination through itself. The session still establishes, so the symptom is routes that never arrive rather than an error. On Linux the whole 127.0.0.0/8 range is available; on macOS add the alias once with sudo ifconfig lo0 alias 127.0.0.2, which ./le setup install also does. The refusal is originatedNextHopIsPeerOwn (internal/component/bgp/reactor/forward_next_hop.go), and precomputeNextHop (internal/component/bgp/reactor/peer_forward_facts.go) is what resolves next-hop self to the local address.

The sink accepts whatever it is sent, so this demo works either way until you announce a route; the address split is what keeps it working when you do.

Stop

./ze signal stop             # graceful shutdown
./ze signal restart          # graceful restart (preserves routes via GR)

Next Steps

  • Use Ze with an AI agent -- ze create agent skill sets Claude Code or Codex up to test Ze
  • Configuration -- peer groups, capabilities, static routes
  • Plugins -- RIB, route server, RPKI, graceful restart
  • CLI Reference -- interactive CLI, route injection, monitoring
  • Logging -- log levels, backends, per-subsystem tuning
  • Operations -- SSH setup, signals, health checks, troubleshooting
  • Lifecycle -- configuration rollback, software updates, recovery order
  • Choose a deployment path -- a lasting installation, with its upgrade and removal steps