Guide

Static Routes

Ze supports static routes with ECMP, weighted load balancing, BFD-tracked failover, blackhole, and reject. Routes are grouped under named tables for policy-based routing support.

A route in the MAIN table is ranked against every other protocol that offers the same prefix, and the winner is programmed by the FIB plugin. A route in a NAMED table is programmed directly, through netlink or through VPP, because a named table has only one writer and nothing to rank.

Configuration

All routes live under a named table. Use default for the main routing table:

static {
    table default {
        route 0.0.0.0/0 {
            next { hop 10.0.0.1 { } }
        }
    }
}

Named routing tables

Define named tables via the routing-table config block, then reference them in static:

routing-table {
    table lns {
        id 100
    }
}

static {
    table lns {
        route 0.0.0.0/0 {
            next { interface tun100 { } }
        }
    }
}

The same prefix can appear in different tables independently. Routes in non-default tables are not redistributed into BGP.

static filter import and rib filter import apply only to main-table routes. Named-table routes bypass the Loc-RIB and go directly to their configured backend, so neither import attachment filters them. Use a main-table route when it must participate in Loc-RIB policy or compete with another protocol.

Reserved table IDs (0, 253-255) are rejected. A 32-bit build additionally rejects a table ID or route metric above 2147483647, because the netlink bindings carry both in a machine int and would otherwise install the route in the main table at the kernel's default metric without reporting anything. Ze's released targets are 64-bit, where the full uint32 range is available.

Interface-only next-hops

For point-to-point links (PPPoE, GRE tunnels) where the next-hop is the interface itself:

static {
    table default {
        route 0.0.0.0/0 {
            next { interface pppoe0 { } }
        }
    }
}

When the interface is a pppoe-client the configuration declares, the route waits for the session rather than failing. It is committed while the session is down (at boot, before the access concentrator answers, or in the same commit that adds the client), and show static lists it with the next-hop inactive and not skipped. Once the session's device is up, the route is installed through it; when the session drops it is removed, and when the session comes back it is installed again, with no reload. This holds in the main table and in a named table. An interface the configuration does not declare is resolved at commit as before: if no such device exists, the route is skipped with its reason and retried on the next commit.

Interface-only next-hops do not support BFD profiles (BFD requires a peer address). Weight is supported for ECMP:

static {
    table default {
        route 0.0.0.0/0 {
            next {
                interface pppoe0 { weight 3; }
                interface pppoe1 { weight 1; }
            }
        }
    }
}

Mixed ECMP

Gateway and interface-only next-hops can coexist in the same route:

static {
    table default {
        route 0.0.0.0/0 {
            next {
                hop 10.0.0.1 { weight 3; }
                interface pppoe0 { weight 1; }
            }
        }
    }
}

When pppoe0 is a declared pppoe-client, the group follows the session. While the session is down the route goes through 10.0.0.1 alone; once it is up, through both with their weights; after it drops, through 10.0.0.1 alone again. The route is never withdrawn while one member is active.

Multiple next-hops (ECMP)

All next-hops are installed simultaneously as a multipath route:

static {
    table default {
        route 10.0.0.0/8 {
            next {
                hop 192.168.1.1 { }
                hop 192.168.1.2 { }
                hop 192.168.1.3 { }
            }
        }
    }
}

Weighted ECMP

The weight field controls traffic distribution. Higher weight means more traffic. Default is 1 (equal distribution).

static {
    table default {
        route 0.0.0.0/0 {
            next {
                hop 10.0.0.1 {
                    weight 3
                }
                hop 10.0.0.2 {
                    weight 1
                }
            }
        }
    }
}

This sends 75% of traffic via 10.0.0.1 and 25% via 10.0.0.2.

BFD failover

Reference a BFD profile on each next-hop. When the BFD session goes down, that next-hop is removed from the ECMP group and the route is reprogrammed with the remaining active next-hops. When the session recovers, the next-hop is re-added.

bfd {
    profile wan-fast {
        detect-multiplier 3
        desired-min-tx-us 100000
        required-min-rx-us 100000
    }
}

static {
    table default {
        route 0.0.0.0/0 {
            next {
                hop 10.0.0.1 {
                    weight 3
                    bfd-profile wan-fast
                }
                hop 10.0.0.2 {
                    weight 1
                    bfd-profile wan-fast
                }
            }
        }
    }
}

If all BFD-tracked next-hops go down, the route is withdrawn entirely.

The session to a next-hop is single-hop. The daemon at startup, a commit, a SIGHUP reload and ze config validate each refuse a bfd-profile while the bfd section is absent or sets enabled false, so BFD cannot be removed from under a monitored route: remove the bfd-profile lines first. They also refuse a bfd-profile that names no profile under bfd { profile ... }, naming the profiles that exist (the editor completes those names), and one whose profile sets passive, because RFC 5881 §3 requires both ends of a single-hop session to be Active. The passive error names the route and the next-hop.

Blackhole and reject

Blackhole silently discards matching packets. Reject discards and sends an ICMP unreachable reply.

static {
    table default {
        route 192.0.2.0/24 {
            blackhole { }
        }
        route 198.51.100.0/24 {
            reject { }
        }
    }
}

IPv6

IPv6 routes work the same way. For link-local next-hops, specify the outgoing interface:

static {
    table default {
        route 2001:db8::/32 {
            next { hop 2001:db8::1 { } }
        }
        route 2001:db8:1::/48 {
            next {
                hop fe80::1 {
                    interface eth0
                }
            }
        }
    }
}

Route attributes

static {
    table default {
        route 172.16.0.0/12 {
            description "internal networks"
            metric 100
            tag 42
            next { hop 10.0.0.1 { } }
        }
    }
}
  • description: operator note (not programmed to kernel)
  • metric: kernel route priority (lower is preferred)
  • tag: opaque value for route policy matching in redistribute

The tag is not programmed to the kernel, because Linux has no route tag attribute. It travels with the route into redistribution, where it does two things. A redistribute { destination <proto> { import static { filters [ T ]; final accept; } } } rule whose policy { match T { tag [ N ]; } } instance reads the tag imports only the routes carrying N. And when the route reaches OSPF, Ze writes the tag into the External Route Tag of the AS-external LSA (RFC 2328 Appendix A.4.5), unless a modify instance on the ospf filter export chain sets another tag with set tag. OSPF redistribution shows the chain.

The tag also rides on the path the route installs in the Loc-RIB, so a static filter import or rib filter import chain can match it: a match instance with action reject; tag [ 4242 ]; hides every static route tagged 4242 and leaves the others selected. A route with no tag leaf carries no tag, so it never meets a tag condition; tag 0 is a real tag. Route Policy at the Loc-RIB covers the chains.

CLI

ze> show static

Shows all configured static routes with their prefixes, next-hops, weights, and BFD status in JSON format.

Route programming

A main-table route is programmed with RTPROT_ZE (protocol 250) by the FIB plugin. A named-table route is programmed with RTPROT_STATIC (protocol 251) by the static plugin itself. On config reload, the plugin computes the diff between old and new routes and applies only the changes.

Kernel ECMP uses RTA_MULTIPATH with per-next-hop weight mapped from the weight field (kernel weight = weight - 1). The kernel carries that share in one octet, so a weight above 255 is capped at 255.

A main-table route needs a FIB plugin, and Ze loads one for you. The system RIB selects the winner and a FIB plugin writes it. Write no fib { ... } block and Ze loads the plugin for the data plane your config already selects at interface { backend }: fib-kernel for netlink, which is the default, and fib-vpp for vpp.

Write fib { kernel { } } or fib { vpp { } } when you want to set one of that plugin's own leaves, or to pick a plugin other than the one Ze would load. Your block always wins. A configuration whose static routes are all in named tables needs no FIB plugin at all, because static programs those routes itself.

When your config selects a data plane no plugin programs, or one this build was compiled without, ze refuses to start or reload it, and ze doctor reports doctor-plugin-no-dataplane-writer at error severity beforehand, in the same words, with the fix the refusal names. An explicit fib { ... } block is never reported: its plugin is the writer.

Administrative distance

rib { distance { static N } } decides which route the kernel forwards on when a static route and a dynamic protocol both offer one prefix. Lower wins. The default is 10, which beats eBGP at 20 and every IGP.

rib {
    distance {
        static 250
    }
}

At 250 a static route LOSES the prefix to an eBGP route at 20, and the kernel forwards on the BGP next-hop. At 5 it keeps the prefix. The RIB looks the number up each time it ranks, so a commit or reload that changes only the distance re-ranks the routes already installed, and the kernel moves to the new winner. The number applies to main-table routes: a named-table route has nothing to be ranked against.

One route can carry its own distance, which wins over static N for that route alone:

static {
    table default {
        route 10.0.0.0/8 {
            distance 3
            next { hop 192.0.2.1 { } }
        }
    }
}

A reload that changes rib { distance { static } } leaves such a route at its own number.

show rib reports the winner per prefix with the protocol that holds it.

Redistribute

Static routes register as protocol "static" in the redistribute framework. BGP redistribute can import static routes:

redistribute {
    destination bgp {
        import static
    }
}

Every route in the default table is redistributed, blackhole and reject routes included, as FRR and BIRD do. A discard route is the usual way to originate an aggregate: install blackhole { } for the covering prefix and import it into BGP or OSPF, and the more specific routes keep forwarding.