configuration interfaces

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

Ze manages Linux network interfaces through the iface component, backed by pure netlink. No iproute2 shell-outs. The model is two-layer JunOS-style: physical interfaces at the top level, logical units underneath. Interfaces are named by the operator, bound to physical hardware by their MAC address, and discovered automatically when you run ze init.

This page covers the configuration surface. The in-tree features list is the authoritative capability map and the ground truth for which features exist today.

The type list

interface {
    ethernet uplink {
        mac-address 00:1a:2b:3c:4d:5e;
    }
    ethernet mgmt {
        mac-address 00:1a:2b:3c:4d:5f;
        mtu         1500;
    }
    bridge fabric {
        mac-address 00:1a:2b:3c:4d:60;
        stp         true;
    }
    dummy blackhole {
    }
    loopback {
    }
}

Type	MAC required	Notes
ethernet	Yes	Physical Ethernet interface.
veth	Yes	Virtual Ethernet pair.
bridge	Yes	Bridge interface. STP optional.
dummy	No	Virtual dummy interface.
loopback	No	Container, no key.
tunnel	Depends	GRE/IPIP/SIT/IP6TNL. gretap and ip6gretap require MAC.
wireguard	No	WireGuard encrypted tunnel with peer reconciliation.

Name and MAC binding

The name under interface { ethernet <name> { } } is a label you choose. It is not the OS interface name. The MAC address is the physical binding, and it must be unique within each list. This separation means you can rename the config entry without losing the binding to the hardware: the OS interface can keep its current name while your Ze config calls it something descriptive.

For ethernet, veth, and bridge interfaces, mac-address is required. For dummy and loopback, it is not.

Discovery during ze init

ze init discovers every OS network interface via netlink and writes initial configuration entries. Each discovered interface gets an entry named after its OS name at discovery time, with mac-address populated and a hidden os-name leaf preserving the original name.

The generated config is a starting point. Rename the entries to something descriptive, and the MAC binding keeps the link to the physical hardware.

Logical units

A physical interface can carry multiple logical units, in the JunOS sense. Unit 0 is implicit and does not need to be declared. Units 1 and above are declared explicitly and typically carry a VLAN tag.

interface {
    ethernet uplink {
        mac-address 00:1a:2b:3c:4d:5e;
        unit 0 {
            address 10.0.0.1/24;
        }
        unit 100 {
            vlan-id 100;
            address 172.16.0.1/24;
        }
    }
}

Creating a unit with a VLAN tag creates a VLAN subinterface. Removing the unit removes the subinterface.

Addressing

IPv4 and IPv6 addresses live under units in CIDR notation.

unit 0 {
    address 10.0.0.1/24;
    address fd00::1/64;
}

Multiple addresses per unit are supported. The monitor subscribes to netlink multicast and emits bus events on address added, address removed, and DAD completion. IPv6 addresses with IFA_F_TENTATIVE are held until DAD completes.

DHCP

DHCPv4 and DHCPv6 are handled by the iface-dhcp plugin. Enable per-unit.

interface {
    ethernet uplink {
        mac-address 00:1a:2b:3c:4d:5e;
        unit 0 {
            dhcp {
                enabled true;
            }
            dhcpv6 {
                enabled true;
            }
        }
    }
}

Both address families can run concurrently. Leases are installed directly via netlink and the bus emits interface/dhcp/lease-acquired, lease-renewed, and lease-expired events with the address, prefix, router, DNS servers, and lease time.

Bridges

Bridges carry member ports in their sub-container.

interface {
    bridge fabric {
        mac-address 00:1a:2b:3c:4d:60;
        stp true;
        member [ port1 port2 ];
    }
    ethernet port1 {
        mac-address 00:11:22:33:44:55;
    }
    ethernet port2 {
        mac-address 00:11:22:33:44:56;
    }
}

Member ports are listed on the bridge itself, referring to ethernet interfaces by their Ze name, not by the OS name.

Per-interface tuning

A handful of per-interface sysctls are exposed as config leaves.

Leaf	Covers
ipv4 { forwarding }	IPv4 forwarding.
arp-filter, arp-accept, arp-announce, arp-ignore	ARP behaviour.
ipv4 { proxy-arp }	Proxy ARP.
ipv6 { autoconf }	SLAAC on the interface.
accept-ra	0, 1, or 2.
ipv6 { forwarding }	IPv6 forwarding.
rp-filter	Source validation.

Ze writes these directly to /proc/sys/net/ipv4/... or /proc/sys/net/ipv6/... via procfs.

Traffic mirroring

Ingress and egress mirroring via tc mirred is supported and idempotent. The mirror container under an interface names the source and the destination, and Ze manages the tc setup and cleanup.

BGP integration

The BGP reactor subscribes to the interface bus. When an address is added or removed on a unit that a BGP listener is bound to, the reactor starts or stops the listener automatically. When an address is migrated make-before-break (see below), the reactor signals bgp/listener/ready once the new listener is up, and the old listener is torn down only after that.

Make-before-break migration

When you move an address from one interface or unit to another, Ze runs a five-phase migration.

1. Add the new address.
2. Wait for DAD on the new address.
3. Signal BGP readiness on the new address.
4. Update the local state.
5. Remove the old address.

Each phase has a rollback path, so a failure during migration does not leave the interface in a broken state. The CLI command is:

ze interface migrate --from uplink.0 --to new-uplink.0 --address 10.0.0.1/24 --timeout 30s

Tunnel interfaces

Ze supports GRE, IPIP, SIT, and IP6TNL tunnel families via netlink.

interface {
    tunnel gre-to-dc2 {
        type gretap;
        mac-address 00:1a:2b:3c:4d:70;
        local  192.0.2.1;
        remote 198.51.100.1;
        unit 0 {
            address 10.255.0.1/30;
        }
    }
    tunnel sit-v6over4 {
        type sit;
        local  192.0.2.1;
        remote 198.51.100.2;
        unit 0 {
            address fd00::1/64;
        }
    }
}

Type	Description
gre	GRE point-to-point tunnel.
gretap	GRE L2 tunnel (carries Ethernet frames). Requires mac-address.
ipip	IPv4-in-IPv4 tunnel.
sit	IPv6-in-IPv4 tunnel.
ip6gre	GRE over IPv6.
ip6gretap	GRE L2 over IPv6. Requires mac-address.
ip6tnl	IPv6-in-IPv6 tunnel.

WireGuard interfaces

WireGuard interfaces are configured under interface { wireguard <name> { ... } }. Ze manages the interface via wgctrl and reconciles peers on config reload.

interface {
    wireguard wg0 {
        private-key "<base64 key>";
        listen-port 51820;
        peer remote-site {
            public-key "<base64 key>";
            endpoint 198.51.100.1:51820;
            allowed-ips [ 10.0.0.0/24 fd00::/64 ];
            persistent-keepalive 25;
        }
        unit 0 {
            address 10.10.0.1/24;
            address fd00::1/64;
        }
    }
}

Peers are reconciled on commit: added peers are created, removed peers are deleted, changed peers are updated in place. Interface deletion during reconciliation is also handled.

Route priority

The route-priority leaf on a unit controls the metric applied to routes learned from DHCP or other dynamic sources on that interface. Lower values mean higher priority.

unit 0 {
    dhcp { enabled true; }
    route-priority 100;
}

VPP interface backend

When VPP is configured, interfaces can use the VPP backend instead of netlink:

interface {
    backend vpp;
}

The VPP backend manages interface lifecycle (create, delete, admin up/down, MTU), addressing, bridge port membership, and monitoring via GoVPP. See VPP for the full data plane story.

IPv6 Router Advertisements

Ze manages IPv6 default routes from Router Advertisements. When an interface has accept-ra enabled, RA-derived default routes are installed and removed as advertisements arrive and expire.

Interface scanning

The ze interface scan command discovers all OS interfaces via netlink and reports them, useful for initial setup and troubleshooting.

What is not implemented

A few things you would expect on a more mature network OS are not in Ze. The honest list: bonding and LACP, VXLAN, VRF route isolation, VRRP, physical-layer tuning (speed, duplex, autoneg, offloads), and 802.1X. The capability table in the in-tree interfaces features page has the full list.

See also

• In-tree interfaces feature page for the capability matrix.
• Operation: command reference for ze interface and ze show interface.
• FIB for how routes reach the kernel forwarding table after interfaces are configured.
• VPP for the VPP data plane integration.

Adapted from main/docs/features/interfaces.md and main/docs/guide/configuration.md.