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.

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

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, GRE and IPIP tunnels, 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.

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