quick start

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

You have a built ze binary. This page gets a BGP session up in about five minutes. By the end you will have a running daemon, one peer, one announced prefix, and a CLI that talks to the daemon over SSH.

If you have not built Ze yet, read Install first.

Initialize credentials

Ze runs an SSH server on localhost for every CLI call. This keeps the control plane authenticated even when multiple users share the host. You set up the credentials once:

bin/ze init

The prompt asks for a username, a password, an SSH host (defaults to 127.0.0.1), a port (defaults to 2222), and an instance name (defaults to the hostname). Passwords are stored bcrypt-hashed in Ze's local database.

You can script this:

echo -e "admin\nsecret" | bin/ze init

Running ze init a second time refuses with database already exists. If you need to start over, stop the daemon and run ze init --force. The old database is backed up as database.zefs.replaced-<date> before a fresh one is created.

Write a minimal config

Save this as example.conf:

plugin {
    external rib {
        use bgp-rib
    }
}

bgp {
    router-id 10.0.0.1
    local {
        as 65000
    }

    peer test-peer {
        remote {
            ip 10.0.0.2
            as 65001
        }
        local {
            ip 10.0.0.1
        }

        family {
            ipv4/unicast
        }

        process rib {
            receive [ state ]
            send [ update ]
        }

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

Two things to notice. The plugin block loads bgp-rib, the RIB storage plugin: the engine does not know about RIBs on its own. The peer block is self-contained and includes the routes to advertise inline, so you do not need a second config file or an external script for this first test.

Validate and start

Always validate before starting:

bin/ze config validate example.conf

You should see configuration valid: example.conf (add -v to see peer and plugin counts). Then start the daemon:

bin/ze example.conf

Ze logs to stderr. The default level is warn, so silence is a good sign. Add -d for debug logging while you are getting a feel for what is happening:

bin/ze -d example.conf

Verify

Open another terminal. All these commands talk to the daemon over the SSH control channel you set up with ze init:

bin/ze status                      # is the daemon alive?
bin/ze cli -c "peer list"          # list configured peers
bin/ze cli -c "peer test-peer show" # peer state and counters
bin/ze cli -c "bgp monitor"        # live event stream, Ctrl-C to exit

If the peer is in IDLE or CONNECT and stuck there, the other side is unreachable. That is expected for this example: 10.0.0.2 is almost certainly not live on your box.

Test without a real peer

To see a session actually come up, use the bundled sink peer. It accepts any BGP session and replies with keepalives:

bin/ze-test peer --mode sink --port 1179 --asn 65001

Point your config at 127.0.0.1:1179 and restart Ze. The session will go to ESTABLISHED and your announced prefix will appear in the sink peer's log.

Stop and restart

bin/ze signal stop       # graceful shutdown, no GR marker
bin/ze signal restart    # graceful restart with GR marker, preserves routes

Next

• CLI Tour for the interactive editor.
• Web UI Tour for the browser.
• Configuration when you want more than one peer.

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