fleet

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

Fleet mode is Ze's answer to "I have 20 boxes and I want to manage their config from one place". A central hub process holds per-client configurations. Remote Ze instances connect to the hub over TLS, authenticate with a per-client token, and fetch their own configuration. If the hub is unreachable, clients fall back to their last cached config and continue running.

This is not the plugin transport layer (that is also TLS and also uses plugin { hub { } }, but for plugin RPCs). The fleet layer is built on top, and the same plugin { hub { } } block carries both.

The shape of it

    Central hub                        Remote nodes
    ┌──────────┐                  ┌──────────┐
    │ ze hub   │ <-- TLS -------  │ ze edge-01│
    │          │                  └──────────┘
    │ configs/ │ <-- TLS -------  ┌──────────┐
    │ edge-01  │                  │ ze edge-02│
    │ edge-02  │                  └──────────┘
    └──────────┘

The hub stores per-client configurations under its data directory. Each remote node connects, authenticates with its unique token, and receives the configuration the hub has stored for it. The config is applied through the normal commit workflow, which means rollback still works at the remote, and the archive still keeps a copy locally.

Bootstrap

On a new remote node:

ze init --managed

ze init --managed creates a managed client database. It prompts for the SSH username and password (for local CLI access), the host and port for the SSH server, and the instance name used to identify the client to the hub.

Non-interactive bootstrap:

echo -e "admin\nsecret\n10.0.0.1\n2222\nedge-01" | ze init --managed

--force replaces an existing database (moved to database.zefs.replaced-<date> as a backup). It is interactive only.

Hub configuration

The hub declares which clients can connect. Each client has its own token.

plugin {
    hub {
        server local {
            ip     127.0.0.1;
            port   1790;
            secret "local-plugin-secret-minimum-32-chars!!";
        }

        server central {
            ip     0.0.0.0;
            port   1791;
            secret "remote-plugin-secret-minimum-32-chars!";

            client edge-01 { secret "client-1-token-minimum-32-chars!!!!"; }
            client edge-02 { secret "client-2-token-minimum-32-chars!!!!"; }
        }
    }
}

Every server block is a TLS listener with its own secret (for the plugin RPC layer) and a list of clients (for the fleet layer). A client authenticates with its own per-client token, not the server secret. Secrets must be at least 32 characters.

Client configuration

A managed client declares one outbound client block naming the hub it connects to.

plugin {
    hub {
        server local {
            ip     127.0.0.1;
            port   1790;
            secret "local-plugin-secret-minimum-32-chars!!";
        }

        client edge-01 {
            host   10.0.0.1;
            port   1791;
            secret "client-1-token-minimum-32-chars!!!!";
        }
    }
}

The server local block is still required: every Ze instance needs at least one local server for its own plugins and SSH. The client edge-01 block is the outbound managed connection to the central hub.

Managing the fleet

From the hub, every client configuration is a file under the hub's config directory (typically edge-01.conf, edge-02.conf). You edit them with the normal editor, with history, archive, and rollback.

ze config edit edge-01.conf
ze config history edge-01.conf
ze config archive backup edge-01.conf

When you commit an edit, the hub notifies the connected client. The client fetches the new config, runs the same validators the editor ran, and applies it through its local commit workflow. If validation fails on the client, the change is rejected there and the client keeps the previous config.

Resilience

Partition tolerance. Every client caches its last known good config locally. A client can start up, run, and reconfigure from its cache without ever reaching the hub.

Fallback. If the hub is unreachable at startup, the client starts with the cached config. If the hub becomes unreachable mid-operation, the client keeps running with its current config until the hub comes back.

Reconnect. Clients detect connection loss, back off, and reconnect automatically. When the connection is re-established, they fetch any updated config.

CLI overrides

A few flags override the in-config hub settings. Useful for operational edge cases.

ze --server 10.0.0.1:1791 --name edge-01 --token <secret> start

Flag	Purpose
--server <addr>	Override the hub address.
--name <name>	Override the client name.
--token <secret>	Override the auth token.

These are for ad-hoc starts. The config file is the normal path.

The hub as a process

The hub is just Ze running in hub mode. There is no separate binary. ze hub starts the hub component alongside the normal daemon, and the plugin { hub { server } } blocks declare which listeners to bring up. You can run a standalone hub (no BGP) by giving it a minimal config with just the hub block, and you can run a hub on the same box as a BGP speaker if you prefer.

See also

• Starting and stopping for ze init --managed.
• Archive and rollback for the per-client archive story.
• In-tree fleet guide for the full reference.

Adapted from main/docs/guide/fleet-config.md.