Skip to content

a. Reference

Jump to bottom
Leonardo Furtado edited this page Mar 2, 2026 · 1 revision

Reference

This page is a lookup resource. It collects command references, schema definitions, glossary terms, and frequently used quick-access values across the labs. Use it alongside the lab-specific and conceptual documentation, not as a replacement for it.

Containerlab Command Reference

Deploy a lab

clab deploy -t <path/to/topology.clab.yml>

Deploy from within the lab directory:

cd ceos-4s4l/
clab deploy -t ceos-4s4l.clab.yml

Destroy a lab

clab destroy -t <path/to/topology.clab.yml>

Add --cleanup to also remove the auto-generated Containerlab directory:

clab destroy -t ceos-4s4l/ceos-4s4l.clab.yml --cleanup

List running labs

clab inspect --all

List nodes in a running lab

clab inspect -t <path/to/topology.clab.yml>

Generate a topology graph

clab graph -t <path/to/topology.clab.yml>

Opens an interactive topology graph in a web browser. Useful for quickly visualizing link assignments.

netlab CLI Reference

Install the automation package

cd automation/
pip install -e .[test]

Installs the netlab CLI into your active Python virtual environment. The [test] extra installs pytest and test dependencies.

netlab validate

Runs validation checks from the intent file.

netlab validate [OPTIONS]
Option Type Default Description
--lab string — Required. Lab directory name (e.g., ceos-4s4l).
--mode string all Validation phase: intent, underlay, control-plane, dataplane, or all.
--profile string default Connection profile. Selects gNMI credentials and port.
--out path reports/<lab>-validate-<ts>.json Path for JSON report output.
--report path reports/<lab>-validate-<ts>.md Path for Markdown report output.

Examples:

# Full validation, default output paths
netlab validate --lab ceos-4s4l

# Only intent and underlay phases
netlab validate --lab ceos-4s4l --mode intent
netlab validate --lab ceos-4s4l --mode underlay

# Write report to a custom path
netlab validate --lab ceos-4s4l --out /tmp/report.json

netlab baseline

Captures an operational snapshot of the lab.

netlab baseline [OPTIONS]
Option Type Default Description
--lab string — Required. Lab directory name.
--out path baselines/<lab>-<ts>.json Output path for baseline JSON.
--profile string default Connection profile.

Example:

netlab baseline --lab ceos-4s4l --out baselines/ceos-4s4l-$(date +%Y%m%d).json

netlab drift

Detects configuration and state drift between a stored baseline and the live network.

netlab drift [OPTIONS]
Option Type Default Description
--lab string — Required. Lab directory name.
--baseline path — Required. Path to a previously saved baseline JSON.
--out path reports/<lab>-drift-<ts>.json Output path for drift report JSON.
--profile string default Connection profile.

Exit codes: 0 = no drift errors, 1 = one or more ERROR-level drift findings.

Check Kind Reference

Seven kinds of checks are available in the intent file. Each is described below with full parameter documentation.

config_contains

Asserts that a configuration string is present in the device's running config.

- name: my-check
  kind: config_contains
  nodes: [leaf1, leaf2]
  match: "interface Vxlan1"
  require_all: true      # Optional, default: true
Parameter Required Description
nodes Yes List of node names to check.
match Yes Substring to search for in the running config.
require_all No If true, all nodes must match. If false, at least one must match. Default: true.

interfaces_up

Checks that all interfaces matching a description prefix are operationally up.

- name: my-check
  kind: interfaces_up
  nodes: [leaf1]
  match: "to-"          # Matches description prefix
Parameter Required Description
nodes Yes List of node names.
match Yes Prefix string matched against the interface description field.

bgp_established

Checks that all BGP sessions on the target nodes are in the Established state.

- name: my-check
  kind: bgp_established
  nodes: [leaf1, leaf2, spine1]
Parameter Required Description
nodes Yes List of node names.

evpn_routes_present

Asserts that EVPN route types are populated in the BGP table on the target nodes.

- name: my-check
  kind: evpn_routes_present
  nodes_from_group: leaves
  route_types: [mac-ip, ip-prefix]   # Optional
Parameter Required Description
nodes or nodes_from_group Yes Node selection.
route_types No List of EVPN route types to check. Default: checks that any EVPN routes exist.

ping_targets

Runs ICMP pings from a source node to a list of target IPs.

- name: my-check
  kind: ping_targets
  nodes: [l4h1]
  targets:
    - "192.168.10.12"
    - "192.168.10.13"
    - "192.168.10.14"
  interface: bond0.10    # Optional, source interface
  count: 3               # Optional, ping count
Parameter Required Description
nodes Yes The source node (typically a Linux host).
targets Yes List of IP addresses to ping.
interface No Source interface for pings.
count No Number of ICMP probes per target. Default: 3.

l2_neighbor_absent

Asserts that a given IP address does NOT appear as an ARP neighbor on a specific interface. Used to verify L2 isolation — that hosts in different broadcast domains cannot resolve each other at Layer 2.

- name: my-check
  kind: l2_neighbor_absent
  nodes: [l4h1]
  interface: bond0.20
  targets:
    - "192.168.30.13"   # Remote rack host — should be absent
    - "192.168.30.14"
Parameter Required Description
nodes Yes The source node (typically a Linux host).
interface Yes Interface on which to check ARP neighbors.
targets Yes IP addresses that must NOT appear in the ARP table.

intent_distinct

A metadata-level check is performed without connecting to any device. Asserts that two values declared within the intent file itself are not equal to each other.

services:
  vlan20_rackA_vni: 10200
  vlan20_rackB_vni: 10300

checks:
  - name: rack-vni-must-differ
    kind: intent_distinct
    values:
      - "{{services.vlan20_rackA_vni}}"
      - "{{services.vlan20_rackB_vni}}"
Parameter Required Description
values Yes A list of exactly two value expressions to compare. They must be different for the check to pass.

Intent File Schema Reference

An intent file is a YAML document with three top-level keys: inventory, services (optional), and checks.

inventory

inventory:
  nodes:
    <node-name>:
      role: eos            # Node type: "eos" for Arista cEOS
      groups: [leaves]     # Optional list of group names for node grouping

services (optional)

Free-form key-value store. Can hold VNI assignments, subnet definitions, or any other design parameters. Values can be referenced in check parameters using template syntax.

checks

checks:
  - name: <unique-string>        # Required. Unique identifier for the check.
    kind: <check-kind>           # Required. One of the seven supported check kinds.
    nodes: [<name>, ...]         # Node list. One of the nodes or nodes_from_group is required.
    nodes_from_group: <group>    # Alternatively, reference a group from inventory.
    tags: [<tag>, ...]           # Optional. Used for phase filtering.
    # Additional parameters per check kind (see Check Kind Reference above)

Glossary

Anycast Gateway: A routing design where multiple switches share the same gateway IP and MAC address. Hosts see a stable gateway address regardless of which switch they are connected to. Implemented in EOS with ip virtual-router mac-address and ip address virtual on SVIs.

Baseline: A JSON snapshot of the live operational state of a lab, captured with netlab baseline. Used as a reference point for drift detection.

BGP Route-Target (RT): A BGP extended community used in VPN and EVPN configurations to define which VPN routes a router imports and exports. In this repository, RTs encode both the ASN scope (65000 for global, 65001 for DC1, etc.) and the service identifier (VNI or VRF).

Carrier-Supporting-Carrier (CsC): A VPN service model where an inner carrier (such as an ISP) uses the MPLS transport of an outer carrier (the backbone provider) as a customer. Requires handling of labeled BGP routes and multi-level MPLS encapsulation.

Clos fabric: A multi-tier network topology where each node in a lower tier connects to every node in the next tier. In a two-tier Clos (leaf-spine), every leaf connects to every spine, producing full bisectional bandwidth and ECMP resilience.

Config Drift: A difference between the state captured in a baseline and the live state collected during a drift run. Structural drift (changed BGP table, missing interface) is a high-signal. Raw config text drift should be interpreted carefully due to platform canonicalization.

Containerlab: A CLI tool that deploys container-based network topologies. Reads .clab.yml topology files and creates one container per node, connecting them with virtual interfaces as declared in the links section.

DCI (Data Center Interconnect): The physical and logical connectivity between geographically separated data centers. In this repository, the DCI for ceos-2dc-4s4l comprises two dedicated router pairs with MPLS LDP on the WAN links.

ECMP (Equal-Cost Multi-Path): Forwarding behavior where traffic to a destination is load-balanced across multiple next-hops of equal metric. In these labs, every leaf has four ECMP paths to any remote loopback via the four spine switches.

ESI-LAG (Ethernet Segment Identifier - Link Aggregation Group): EVPN multihoming mechanism where two or more PEs share the same ESI for a dual-homed attachment circuit. Allows all-active forwarding across both links without requiring MLAG.

EVPN (Ethernet VPN): A BGP address family that carries MAC/IP reachability information in the control plane. Used in this repository as the control plane for VXLAN overlays. Key route types: Type 1 (Ethernet auto-discovery), Type 2 (MAC/IP advertisement), Type 3 (inclusive multicast), Type 4 (Ethernet segment), Type 5 (IP prefix).

gNMI (gRPC Network Management Interface): A protocol for network management and telemetry, typically running on TCP port 6030 for Arista EOS. The automation framework collects evidence from EOS nodes primarily via gNMI.

Intent: In this repository, "intent" refers to the declarative YAML specification of what the network should look like and how it should behave. The intent.yml file in each lab is the source of truth for what netlab validate checks.

IS-IS: Intermediate System to Intermediate System, a link-state routing protocol used as the IGP in the Nokia lab. With SR extensions, IS-IS also distributes Segment Routing prefix-SIDs alongside standard topology information.

LACP (Link Aggregation Control Protocol, 802.3ad): Protocol that negotiates multi-link aggregation between a host (or switch) and its connected peer. In this repository, Linux hosts use bond0 with LACP mode active, and the network side configures Port-Channels with LACP.

L3VNI: A Virtual Network Identifier used for Layer-3 inter-subnet routing in EVPN symmetric IRB. In this repository, VNI 10000 is the L3VNI for the TENANT1 VRF, bound to VLAN 4094 on every leaf.

Route Distinguisher (RD): A BGP attribute that makes EVPN or VPN routes unique in the BGP table even when the same prefix exists in multiple VRFs or VNIs. In this repository, RDs are set to auto for VLAN routes and manually set using the leaf's Loopback0 IP for VRF routes (e.g., 10.1.255.11:10000).

Segment Routing (SR-MPLS): An MPLS forwarding model where the path a packet takes through the network is encoded as an ordered list of Segment IDs in the packet header. Each SID corresponds to a node or adjacency in the network. Eliminates the need for per-flow state at intermediate nodes.

VTEP (VXLAN Tunnel Endpoint): A device that performs VXLAN encapsulation and decapsulation. In this repository, leaves are VTEPs. Spines are not VTEPs — they forward encapsulated VXLAN traffic as regular IP traffic.

VXLAN (Virtual Extensible LAN): An encapsulation protocol that wraps L2 Ethernet frames in a UDP/IP packet for transport across an L3 network. UDP port 4789 is used in this repository for all VXLAN traffic.

Lab Node Summary Tables

ceos-4s4l — Node Overview

Node ASN Loopback0 Loopback1 Role
spine1 65000 10.255.0.1 — EVPN route server
spine2 65000 10.255.0.2 — EVPN route server
spine3 65000 10.255.0.3 — EVPN route server
spine4 65000 10.255.0.4 — EVPN route server
leaf1 65101 10.255.1.1 10.255.2.1 VTEP, Rack A
leaf2 65102 10.255.1.2 10.255.2.2 VTEP, Rack A
leaf3 65103 10.255.1.3 10.255.2.3 VTEP, Rack B
leaf4 65104 10.255.1.4 10.255.2.4 VTEP, Rack B

ceos-2dc-4s4l — DC1 Node Overview

Node ASN Loopback0 Loopback1 Role
dc1-spine1–4 65001 10.1.254.1–4 — DC1 route servers
dc1-leaf1–4 65101–65104 10.1.254.11–14 10.1.255.11–14 DC1 VTEPs
dc1-router1 65151 10.1.254.21 10.1.255.21 DCI VTEP/WAN edge
dc1-router2 65152 10.1.254.22 10.1.255.22 DCI VTEP/WAN edge

Branch and PR Naming Conventions

Type Pattern Example
New lab lab/<name> lab/frr-bgp-unnumbered
Lab improvements fix/<lab>-<issue> fix/ceos-4s4l-esi-typo
Documentation docs/<topic> docs/evpn-tutorial-update
Automation feature automation/<feature> automation/gnmi-nokia-adapter

Pull requests should include a description of what changed, why it changed, and how the change was tested. For labs, "tested" means deployed the lab end-to-end and confirmed that netlab validate --mode all (or the relevant manual validation scripts) pass.

License Summary

Material License Implications
Code (topology files, configs, scripts, automation framework) AGPL-3.0 Open source; derivative works must also be open-sourced under AGPL if distributed or offered as a network service.
Documentation and written content CC BY-NC-SA 4.0 Free to use and share with attribution; no commercial use; derivatives must use the same license.
Vendor images (cEOS, SR OS) Commercial/vendor Not included. Must be licensed and obtained separately.

Clone this wiki locally