building

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

Building Ze from source is a single command if you have Go 1.26 and a working toolchain on the path. CGO is disabled globally. The Makefile is the source of truth for every build target, and make help lists them all grouped by category. This page is the short version.

Prerequisites

You need Go 1.26 or newer. The repo and the module path are both github.com/ze-software/ze.

go version    # 1.26 or newer
git clone https://github.com/ze-software/ze.git
cd ze

If you only want a ze binary and no checkout, go install works, but it needs the feature tags spelled out because they are off by default:

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_mrt 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' github.com/ze-software/ze/cmd/ze@latest

The shortest path

make build

That builds bin/ze (the daemon and CLI), bin/ze-test (the functional test driver), bin/ze-chaos (the chaos orchestrator), and bin/ze-analyse, and regenerates docs/comparison.html from the markdown source. bin/ze-perf is not included; build it separately with make ze-perf. The version is injected via ldflags from the current date in the form YY.MM.DD.

If you only want the daemon, the per-binary target is faster.

make ze        # bin/ze only
make chaos     # bin/ze-chaos only
make test      # bin/ze-test only
make analyse   # bin/ze-analyse only

Protocol buffer toolchain

Regenerating the gRPC API stubs requires protoc, protoc-gen-go, and protoc-gen-go-grpc on the PATH. These are only needed if you edit api/proto/*.proto; the committed generated Go files are enough for a normal build.

make ze-setup      # Install protoc-gen-go and protoc-gen-go-grpc into $GOBIN

protoc itself is not a Go tool, so install it from your system package manager (brew install protobuf, apt install protobuf-compiler, etc.) or from the protocol buffers release page. After ze-setup finishes, make generate regenerates the proto stubs. See gRPC API for the resulting service surface.

Gokrazy VM appliance

make ze-gokrazy-deps and make ze-gokrazy build a bootable x86_64 VM image with Ze as its only application. The first target fetches the Linux kernel, gokrazy init, and serial-busybox packages into the Go module cache (one-time, ~42 MB). The second target cross-compiles Ze and assembles the image. make ze-gokrazy-run boots the result in QEMU for testing. The full appliance build walkthrough is on the appliance page.

Build tags

Ze uses a unified binary with positive build tags to select personalities. The main binary (bin/ze) is built with the ze_core tag. Other binaries are build-tag variants of the same source:

Binary	Build tag	Purpose
bin/ze	ze_core	Daemon, CLI, SSH server.
bin/ze-test	ze_test	Functional test driver.
bin/ze-chaos	ze_chaos	Chaos testing orchestrator.
bin/ze-perf	ze_perf	Performance benchmark tool.
bin/ze-analyze	ze_analyze	MRT and RIB analysis tool.

Additional tags layer features on top:

Tag	Purpose
ze_distro	Linux distribution features (systemd, package management).
ze_appliance	Appliance management commands.
ze_setup	Build tooling and setup commands.
ze_stripped	Minimal build with reduced feature set.
maprib	Swaps the BART trie RIB for a Go map (benchmarking).

ZE_TAGS=maprib make ze

Feature gates

Beyond the personality tags above, Ze can compile whole subsystems out at build time. Each optional subsystem is guarded by a ze_<feature> build tag. Leaving the tag off drops that subsystem's code from the binary, for a smaller image and less attack surface. A build with a subsystem compiled out does not link it and rejects its config block as unknown.

The default-on set lives in one place, feature-gates.txt, and every consumer derives from it: the Makefile's ZE_FEATURES, the functional-test build tags, the plugin-import generator, the dependency audit, and the generated tag lists in .golangci.yml, gokrazy/ze/config.json and the quickstart go install line. Adding a gate is a one-line edit to that file plus make generate. make ze and make ze-appliance build with every default-on feature; make ze-stripped keeps only the SSH management plane and drops the rest; a bare go build -tags ze_core drops all of them.

Thirty-six subsystems gate today.

Management and API surfaces

Tag	Subsystem
ze_ssh	SSH server (the base operator management plane).
ze_web	Web interface.
ze_lg	Looking Glass.
ze_gnmi	gNMI server.
ze_mcp	MCP server.
ze_rest	REST API transport.
ze_grpc	gRPC API transport.
ze_telemetry	Prometheus / telemetry exporter.

Routing protocols

Tag	Subsystem
ze_bgp	The BGP engine, codec, and every BGP plugin. The largest gate.
ze_bmp	BMP receiver and sender. Requires ze_bgp.
ze_mrt	MRT routing-information export. Independent of ze_bgp.
ze_ospf	OSPF (v2 and v3).
ze_isis	IS-IS.
ze_ldp	LDP.
ze_rsvpte	RSVP-TE.
ze_bfd	BFD engine. The bfd/api client seam stays always-on.
ze_vrrp	VRRP.
ze_mpls	MPLS show-forwarding surface. Kernel MPLS forwarding stays on.
ze_exabgp	ExaBGP compatibility bridge and the ze exabgp root command.

Subscriber, VPN, and dataplane

Tag	Subsystem
ze_l2tp	The BNG: L2TP LNS, PPPoE server and client, subscriber management.
ze_ike	IKEv2 / IPsec control plane.
ze_radius	RADIUS client and AAA backend.
ze_tacacs	TACACS+ AAA backend.
ze_vpp	VPP dataplane and every per-plugin VPP backend.
ze_cos	Class-of-service profiles.
ze_copp	Control-plane policing.
ze_policyroute	Policy-routing engine.

Services and telemetry plugins

Tag	Subsystem
ze_dhcpserver	DHCP server.
ze_ntp	NTP client.
ze_as112	AS112 reverse-DNS sink.
ze_geodns	Geo-aware authoritative DNS.
ze_pxe	Netboot pair: TFTP server plus HTTP image server.
ze_flowexport	NetFlow v9, IPFIX, and sFlow export.
ze_trafficusage	Per-host traffic accounting.
ze_anomaly	Traffic anomaly detection and shaping response.
ze_ddos	DDoS detection and mitigation responders.

Build a hardened, minimal daemon or add specific features on top:

make ze-stripped                                 # SSH only, all optional features dropped
go build -tags 'ze_core ze_ssh ze_web' ./cmd/ze  # SSH plus web only
go build -tags 'ze_core ze_ssh ze_ospf' ./cmd/ze # An OSPF-only router, no BGP

Gates compose independently where the code allows it. REST and gRPC gate separately, so a build can ship one transport without the other. Metric collection stays linked in every build; only the HTTP exporter is behind ze_telemetry, so a no-telemetry binary still records counters but cannot expose them over HTTP.

Two gates depend on another: ze_bmp needs ze_bgp because BMP monitors the BGP RIB, and the l2tp RADIUS auth plugin needs both ze_l2tp and ze_radius. ze_mrt is deliberately independent, and loads inert without a BGP source.

Some contracts stay always-on so a dropped feature degrades rather than breaks. bfd/api is a nil-able seam that BGP, OSPF, and static consume, and every consumer nil-checks it, so a BFD-less build runs those protocols unchanged. Kernel XFRM programming stays on for OSPF RFC 4552 authentication even without ze_ike. A config that selects a compiled-out subsystem is rejected as unknown rather than silently ignored, so ze_tacacs off means system { authentication { tacacs {} } } fails to load instead of falling through to another method.

Tests

The Makefile splits tests into a few targets so you can run only what you need.

Target	What it runs
make ze-unit-test	Go unit tests for everything except cmd/ze-chaos.
make ze-functional-test	Functional tests against a built bin/ze.
make ze-fuzz-test	All fuzz tests.
make ze-chaos-test	Unit and functional chaos suites, and chaos web tests.
make ze-test	Lint, unit, functional, ExaBGP, and fuzz combined.
make ze-verify	The full pre-commit check: lint, unit, functional, and ExaBGP.
make ze-ci	Lint, unit tests, and build.
make ze-verify-changed	Run ze-verify only on packages touched in your branch.

ze-verify is the one that must pass before you submit a patch. ze-ci is a lighter target (lint, unit tests, and build) used in CI.

Test parallelism

The Makefile caps test parallelism at half the available cores so a make ze-verify does not pin every core on the box. If you want to override that, set GOMAXPROCS directly. The Go test cache lives in tmp/go-cache rather than TMPDIR because Unix socket tests can hit the path-length limit on /tmp.

Build outputs

Everything that comes out of the build lands in bin/.

bin/ze            # daemon, CLI, and the SSH server
bin/ze-test       # functional test driver
bin/ze-chaos      # chaos orchestrator
bin/ze-analyse    # MRT and RIB analysis tool

Docker

make ze-docker                                        # Build ze:latest
make ze-docker ZE_DOCKER_IMAGE=myregistry/ze          # Custom image name
make ze-docker ZE_TAGS=maprib                          # With build tags

The image is ~89 MB: a static binary on a scratch base. See Docker for the full guide.

Other useful targets

make help                 # The full list of targets, grouped by category
make generate             # Regenerate plugin imports
make ze-lint              # Run the linter pass
make ze-perf              # Build `bin/ze-perf`. Run benchmarks with `make ze-perf-bench`
make ze-spec-status       # Spec status report
make ze-command-list      # Generated command list
make ze-doc-drift         # Detect docs that have drifted from the code

See also

• Contributing for what to do once you have a working build.
• In-tree CONTRIBUTING.md for the canonical version.
• Plugin development if you are extending Ze rather than modifying the core.

Adapted from main/Makefile and main/CONTRIBUTING.md.