isis

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

Ze implements IS-IS (Intermediate System to Intermediate System, ISO/IEC 10589 as updated by RFC 1195 / RFC 5305 / RFC 5308 / RFC 5301) as a native link-state interior gateway protocol that runs directly over Layer 2. It builds adjacencies, floods a link-state database, runs SPF, and installs the resulting routes into the kernel FIB through the same Loc-RIB path as every other protocol (AdminDistance 115, tagged RTPROT_ze).

IS-IS runs as the isis plugin. It needs a raw AF_PACKET socket (CAP_NET_RAW); without it the engine forms no adjacencies.

Levels and areas (NET addressing)

IS-IS routers belong to an area and operate at Level 1 (intra-area), Level 2 (inter-area / backbone), or both. The router's identity comes from its Network Entity Title (net): at least one NET is required, and the System ID is derived from the 6 octets before the NSEL of the first NET unless an explicit system-id is given.

Leaf	Meaning
net	Network Entity Title, e.g. 49.0001.0000.0000.0001.00. Area address + System ID + NSEL.
level	l1, l2, or l1-l2 (operate at both levels).
system-id	Optional explicit 6-octet System ID; must match the System ID embedded in the first NET.
hostname	Dynamic hostname advertised in TLV 137 (RFC 5301).
lsp-lifetime	Maximum LSP age in seconds (default 1200).

Interface configuration

Interfaces are configured under a single interfaces { } container holding a keyed interface <name> list. The name is the Ze logical interface name, which equals the kernel device by default but can be bound to a different kernel device through an os-name selector; IS-IS resolves the logical name to its kernel device through the shared iface resolver.

isis {
    net 49.0001.0000.0000.0001.00
    level l1-l2
    lsp-lifetime 1200
    hostname r1
    interfaces {
        interface eth0 {
            circuit-type point-to-point
            metric 10
            hello-interval 10
            hold-multiplier 3
            priority 64
            address-family ipv4-unicast { }
        }
        interface eth1 {
            passive true
        }
    }
}

Leaf	Meaning
circuit-type	broadcast (LAN) or point-to-point.
metric	Link cost advertised in the wide-metric IS Reachability TLV.
hello-interval	Seconds between Hellos.
hold-multiplier	Hold time = hello-interval * hold-multiplier.
priority	DIS election priority on broadcast circuits (0..127, default 64).
passive	Form no adjacency, but still advertise the interface prefix.
address-family	Enable ipv4-unicast and/or ipv6-unicast on the circuit.

Per-interface level-1 { } / level-2 { } containers override metric, timers, and DIS priority per level, and carry the per-circuit auth-key-chain used for Hellos.

LAN versus point-to-point

A point-to-point circuit forms a single adjacency with the neighbour directly: no DIS, no pseudo-node. It uses the P2P IIH PDU and three-way handshake (RFC 5303, TLV 240).

A broadcast (Ethernet, multi-access) circuit does not form a full mesh. Routers exchange LAN IIH PDUs, elect a Designated IS (DIS) per level, and represent the segment as a single pseudo-node.

DIS election. Every router advertises a DIS priority (0..127, default 64) in its LAN Hello. The highest priority wins; an equal priority breaks to the higher interface MAC. Priority 0 is allowed (it lowers preference but does not stop a MAC-tiebreak win). Election runs independently for Level 1 and Level 2, so one router can be the L1 DIS and another the L2 DIS on the same segment.

Pseudo-node. The elected DIS originates a pseudo-node LSP that lists every router on the segment as a neighbour at metric 0. Every router then advertises the LAN as a single link to the pseudo-node, so a LAN with N routers appears as one node with N spokes instead of an N*(N-1) mesh. This is automatic; nothing to configure beyond the priority. If the DIS leaves, the survivors elect a new DIS and a router that loses the role purges its pseudo-node before yielding, so the topology never shows a stale LAN node. Election is damped against flaps.

Adjacencies

Routers discover each other by exchanging Hellos (IIH). When the holding time on a circuit elapses without a Hello, the adjacency times out and is torn down. Inspect adjacencies with show isis neighbor (system-id, interface, level, state, hold time).

clear isis adjacency tears down every adjacency without closing the circuit; each neighbour re-learns from the next Hello, driving a full LSP re-origination and SPF re-run.

Link-state database and SPF

Each router floods Link State PDUs (LSPs) describing its own links and reachable prefixes; the union of every router's LSPs forms the link-state database (LSDB). LSPs are stored verbatim (a single owned copy of the PDU bytes) with parsed freshness metadata, and re-flood byte-for-byte even when they carry TLVs Ze does not understand. Sequence numbers, Fletcher checksums, aging, purges, and 256-fragment fragmentation follow ISO/IEC 10589.

From the synchronised LSDB, Ze runs a Dijkstra SPF over the topology and extracts routes. Inspect the database with show isis database (one row per LSP) or show isis database detail (each LSP's TLVs decoded), and recent SPF runs with show isis spf-log (time, level, trigger, duration, node count).

ECMP

When SPF finds several equal-cost paths to a prefix, all of them are installed as next-hops, so traffic load-shares across equal-cost links. The installed routes appear (with their next-hops) in show isis route.

Wide metrics

Ze originates wide metrics only (RFC 5305 / RFC 5308). The Extended IS Reachability TLV (22) carries a 24-bit metric; the Extended IP Reachability (TLV 135, IPv4) and IPv6 Reachability (TLV 236) TLVs carry a full 32-bit metric. Narrow IS Reachability (TLV 2) is decoded for interop but never originated. An IPv6 prefix advertised with a metric above MAX_V6_PATH_METRIC (0xFE000000) is decoded but excluded from SPF (RFC 5308 sec 2).

Dual-stack IPv6

Ze runs IPv6 over the same IS-IS instance as IPv4 (RFC 5308, single-topology). Enable address-family ipv6-unicast on a circuit and both families ride a single shared shortest-path tree, so one adjacency carries IPv4 and IPv6 reachability.

isis {
    net 49.0001.0000.0000.0001.00
    level l1-l2
    interfaces {
        interface eth0 {
            address-family ipv4-unicast { }
            address-family ipv6-unicast { }
        }
    }
}

With IPv6 enabled, the node advertises the IPv6 NLPID 0x8E in the Protocols Supported TLV (129), carries its link-local address in the Hello TLV 232 and its non-link-local addresses in the LSP TLV 232, advertises IPv6 prefixes as TLV 236 (link-local prefixes are never advertised), and extracts IPv6 routes from the same Dijkstra tree (no second SPF). Inspect them with show isis route ipv6.

Single-topology assumes the IPv4 and IPv6 topologies are congruent. On a non-congruent topology (an IPv4-only or IPv6-only link, or per-family metric differences) an IPv6 route may resolve to a next-hop with no IPv6 reachability. RFC 5120 Multi-Topology is not implemented; for the common congruent dual-stack deployment, single-topology is correct and simpler.

Authentication

IS-IS PDUs can be authenticated so a router accepts adjacencies and link-state information only from peers that share a key. Three types are carried in the Authentication TLV (type 10):

Type	Wire code	Standard	Use
cleartext	1	ISO/IEC 10589	Sanity check only; the password rides the wire in clear.
hmac-md5	54	RFC 5304	HMAC-MD5 integrity protection.
hmac-sha-256 (and -1/224/384/512)	3	RFC 5310	Generic cryptographic authentication; SHA-256 recommended.

Keys are configured as named key-chains, each holding one or more keys with a key-id, algorithm, $9$-encoded secret, and optional send-lifetime / accept-lifetime windows for hitless rotation. The secret is stored with the reversible $9$ encoding (like PPPoE and WireGuard keys) so it never appears as plaintext in show configuration, logs, or backups.

isis {
    net 49.0001.0000.0000.0001.00
    key-chains area-key {
        key 1 {
            algorithm hmac-sha-256
            secret $9$....               # entered plaintext, $9$-encoded on commit
        }
    }
    key-chains iih-key {
        key 1 { algorithm hmac-sha-256  secret ... }
    }
    level-1 { auth-key-chain area-key }       # L1 LSP/CSNP/PSNP
    interfaces {
        interface eth0 {
            level-1 { auth-key-chain iih-key }    # L1 Hellos on this circuit
        }
    }
}

Hellos (IIH) authenticate with the per-interface chain; LSPs and the CSNP/PSNP sequence-number PDUs authenticate with the per-level chain (the area key for Level 1, the domain key for Level 2). The two are independent. A PDU that arrives with no Authentication TLV, with the TLV not first, or with a digest no current key matches is rejected before it can form an adjacency or enter the database, and ze_isis_auth_failures_total{level,interface} is incremented. Authenticated purges are enforced per RFC 5304.

Redistribution

IS-IS plugs into Ze's protocol-agnostic redistribution framework in both directions, using the same redistribute { } block as every other protocol.

Export IS-IS into BGP. IS-IS registers a single redistribution source named isis. Both levels (L1 and L2) export under it; the single name is what lets loop prevention auto-reject IS-IS self-import.

redistribute {
    destination bgp {
        import isis
    }
}

Import other protocols into IS-IS. An isis consumer turns connected, static, and BGP routes into Extended IP Reachability (TLV 135, IPv4) or IPv6 Reachability (TLV 236) entries in the node's own LSPs, which flood like any other prefix.

redistribute {
    destination isis {
        import connected
        import static
        import bgp
    }
}

Each redistributed prefix gets a fixed default metric. TLV 135 carries no external bit (a redistributed IPv4 route is an ordinary reachability entry); TLV 236 sets the external (X) bit for IPv6. destination isis { import isis } is accepted by the schema but is a no-op (loop prevention rejects redistributing IS-IS into itself). IS-IS also advertises its own enabled and passive interface prefixes as internal reachability, so loopbacks and edge networks are reachable without running the protocol on them.

Observability

show isis neighbor            # adjacencies: system-id, interface, level, state, hold time
show isis database            # LSDB summary (one row per LSP)
show isis database detail     # LSDB with each LSP's TLVs decoded
show isis route               # IS-IS-computed IPv4 routes
show isis route ipv6          # IS-IS-computed IPv6 routes (RFC 5308)
show isis interface           # circuits: type, metric, hello/hold, passive, DIS, adjacency count
show isis hostname            # system-id -> dynamic hostname (TLV 137, RFC 5301)
show isis spf-log             # recent SPF runs: time, level, trigger, duration, node count

clear isis adjacency          # tear down all adjacencies; they re-form from the next Hello
clear isis counters           # reset the SPF-run log

Every show isis ... command routes its JSON through the pipe machinery, so you can append | json, | table, | text, | count, | match <pat>, | resolve, or | origin. clear isis counters clears only the observational SPF-run history; the monotonic Prometheus series are process counters and are intentionally not reset.

The neighbour and database views are also available in the web UI at /isis and /isis/database, refreshing live over Server-Sent Events. Metrics are exported under the ze_isis_* prefix (adjacencies, LSDB, flooding/SNP, DIS, SPF, authentication, redistribution, and the raw L2 transport). ze doctor reports readiness problems (doctor-isis-raw-socket, doctor-isis-net-missing, doctor-isis-system-id-mismatch) before the engine starts; each is explainable with ze explain <code>.

Offline decode

ze isis-decode reads one IS-IS PDU from stdin (ASCII hex or raw bytes) and prints a JSON view, without a daemon. Add --pretty for indented output.

echo 831b0100... | ze isis-decode --pretty

See also

• OSPF for the other native link-state IGP.
• Redistribution for the protocol-agnostic redistribute framework.
• FIB for how IS-IS routes reach the kernel.
• MPLS / LDP / RSVP-TE for label distribution over the IGP.
• BFD for sub-second failure detection.
• Plugins for the plugin list.

Adapted from docs/guide/isis.md.