Skip to content

configuration interfaces

Jump to bottom
Thomas Mangin edited this page Jun 15, 2026 · 8 revisions

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.
pppoe-client No PPPoE client (RFC 2516). Dials AC over a physical Ethernet interface.
xfrm No XFRM interface for route-based IPsec. See IPsec VPN.

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. Units are named (lowercase alphanumeric and hyphens). A default unit is implicit and does not need to be declared. Units with a VLAN tag are declared explicitly.

interface {
    ethernet uplink {
        mac-address 00:1a:2b:3c:4d:5e;
        unit main {
            ipv4 {
                address [ 10.0.0.1/24 ];
            }
            ipv6 {
                address [ fd00::1/64 ];
            }
        }
        unit vlan100 {
            vlan-id 100;
            ipv4 {
                address [ 172.16.0.1/24 ];
            }
        }
    }
}

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

VLAN 802.1p QoS maps

VLAN units support ingress and egress QoS maps that translate between 802.1p PCP values and internal Linux priority levels. Configure them under the unit:

unit vlan100 {
    vlan-id 100;
    qos {
        ingress-map [ 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7 ];
        egress-map  [ 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7 ];
    }
}

Each entry is priority:pcp (ingress) or priority:pcp (egress). Named class-of-service profiles can be assigned at the interface or unit level via the cos plugin. See Class of Service for the full profile and RADIUS integration.

Addressing

IPv4 and IPv6 addresses live under per-family containers inside units. Use bracket syntax for the address list.

unit main {
    ipv4 {
        address [ 10.0.0.1/24 10.0.0.2/24 ];
    }
    ipv6 {
        address [ fd00::1/64 ];
    }
}

Multiple addresses per family 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 inside the per-family containers.

interface {
    ethernet uplink {
        mac-address 00:1a:2b:3c:4d:5e;
        unit main {
            ipv4 {
                dhcp {
                    enabled true;
                }
            }
            ipv6 {
                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 inside the per-family containers on each unit.

Leaf Covers
ipv4 { forwarding } IPv4 forwarding.
ipv4 { arp-filter }, arp-accept, arp-announce, arp-ignore ARP behaviour.
ipv4 { proxy-arp } Proxy ARP.
ipv4 { rpf-check } Reverse path filtering: strict, loose, or disable.
ipv6 { autoconf } SLAAC on the interface.
ipv6 { accept-ra } 0, 1, or 2.
ipv6 { forwarding } IPv6 forwarding.
ipv6 { rpf-check } Reverse path filtering (VPP data plane only on IPv6).

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

Offload and packet steering

Per-interface offload settings live in an offload container on L2 interface kinds (ethernet, veth, bridge, dummy). Each feature is a boolean: true to enable, false to disable, absent to leave at OS default.

interface {
    ethernet uplink {
        mac-address 00:1a:2b:3c:4d:5e;
        offload {
            gro true;
            tso false;
            rps true;
        }
    }
}
Leaf Description
gro Generic Receive Offload. Software-based receive aggregation.
gso Generic Segmentation Offload. Delayed send segmentation.
sg Scatter-Gather I/O. Required by TSO/GSO on most drivers.
tso TCP Segmentation Offload. Hardware-based send segmentation. Disable for VPP.
lro Large Receive Offload. Hardware receive coalescing. Disable on routers/bridges.
hw-tc-offload Hardware TC offload (flower/u32 filter rules in NIC firmware).
rps Receive Packet Steering. Software multi-CPU receive distribution.
rfs Receive Flow Steering. Steer to the CPU running the consuming application.

Applied directly via kernel ioctl (SIOCETHTOOL) or sysfs. No ethtool binary required. Unsupported features are logged as warnings and do not block config commit.

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 {
        encapsulation {
            gretap {
                local  { ip 192.0.2.1; }
                remote { ip 198.51.100.1; }
                mac-address 00:1a:2b:3c:4d:70;
            }
        }
        unit main {
            ipv4 {
                address [ 10.255.0.1/30 ];
            }
        }
    }
    tunnel sit-v6over4 {
        encapsulation {
            sit {
                local  { ip 192.0.2.1; }
                remote { ip 198.51.100.2; }
            }
        }
        unit main {
            ipv6 {
                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 { ip 198.51.100.1; port 51820; }
            allowed-ips [ 10.0.0.0/24 fd00::/64 ];
            persistent-keepalive 25;
        }
        unit main {
            ipv4 {
                address [ 10.10.0.1/24 ];
            }
            ipv6 {
                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 main {
    ipv4 {
        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.

PPPoE client interfaces

Ze supports PPPoE client interfaces for CPE/subscriber use. The pppoe-client kind dials an access concentrator over a physical Ethernet interface, negotiates LCP/auth/IPCP, and presents the resulting PPP session as a routable interface with server-assigned addresses.

interface {
    pppoe-client pppoe0 {
        source-interface eth2;
        authentication {
            username "user@isp.example";
            password "secret";
        }
    }
}
Leaf Description
source-interface Physical Ethernet interface for PPPoE discovery (required).
authentication / username Authentication username sent to the AC (required).
authentication / password Authentication password, stored $9$-encoded on disk (required).
service-name Desired PPPoE service name. Empty means accept any.
ac-name Desired access concentrator name. Empty means accept any.
no-default-route Do not install a default route via the PPP interface.

The kernel PPP interface (pppN) is created dynamically. The name leaf is a config key only.

XFRM interfaces

XFRM interfaces provide route-based IPsec. Traffic routed through the XFRM interface is encrypted by the kernel's XFRM subsystem; traffic arriving on it is decrypted. Ze manages XFRM interface creation and deletion via netlink.

interface {
    xfrm ipsec0 {
        if-id 42;
        unit main {
            ipv4 {
                address [ 10.255.0.1/30 ];
            }
        }
    }
}
Field Type Description
if-id uint32 XFRM interface ID, must match the IPsec SA's if-id.

XFRM interfaces are typically paired with IPsec tunnel configuration. See IPsec VPN for the IKE and SA setup.

Per-interface rate tracking

Ze samples interface counters every second and computes per-interface rates for rx/tx bytes, packets, errors, and drops.

show interface rate              # All interfaces
monitor interface rate           # Live streaming

Twelve Prometheus gauges under ze_interface_* expose the rates. The web UI includes rate columns in the interface table.

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), and 802.1X. The capability table in the in-tree interfaces features page has the full list.

See also

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

Unreviewed draft. This wiki was authored in bulk and has not been reviewed. File corrections on the issue tracker.

AGPL-3.0 | Source on GitHub | Discord | Edit this page

Home

About

First Steps

Configuration

Operation

Interfaces

Plugins

Plugin Development

Chaos Testing

Blueprints

Development

Reference

Clone this wiki locally