version: "1.0.1" name: protocol-participation description: "Live BGP and OSPF control-plane participation — peer with real routers, inject/withdraw routes, query RIB/LSDB, adjust metrics, GRE tunnel status. Use when injecting or withdrawing BGP routes, checking BGP peer state, querying the OSPF LSDB, or testing route advertisement in a lab." license: Apache-2.0 user-invocable: true metadata: { "openclaw": { "requires": { "bins": ["python3"], "env": ["NETCLAW_ROUTER_ID"] } } }

Protocol Participation — BGP + OSPF + GRE

MCP Server

Tools

BGP Tools

bgp_get_peers

List BGP peer sessions with state, AS, IP, uptime, and prefix counts.

Returns: { peers: [{peer, peer_as, state, local_addr, is_ibgp, uptime, prefixes_received, prefixes_sent}], count }

bgp_get_rib

Query the Loc-RIB (best routes). Optionally filter by prefix.

Returns: { routes: [{network, next_hop, as_path, local_pref, med, origin, communities}], count }

bgp_inject_route

Inject a route into the BGP RIB and advertise to peers.

Returns: { success, network, route_info }

bgp_withdraw_route

Withdraw a route from the BGP RIB and send withdrawal to peers.

Returns: { success, network }

bgp_adjust_local_pref

Change the LOCAL_PREF for a route in the RIB.

Returns: { success, network, old_local_pref, new_local_pref }

OSPF Tools

ospf_get_neighbors

List OSPF neighbors with state, address, priority, and router ID.

Returns: { neighbors: [{neighbor_id, state, address, priority}], count }

ospf_get_lsdb

Query the OSPF Link State Database.

Returns: { lsdb: [{type, advertising_router, ls_id, sequence, age}], count }

ospf_adjust_cost

Change the OSPF cost on an interface.

Returns: { success, interface, old_cost, new_cost }

GRE Tools

gre_tunnel_status

Check GRE tunnel status via system commands (ip tunnel show, ip addr show).

Returns: { tunnels: [...], addresses: [...], count }

Meta Tools

protocol_summary

Consolidated BGP + OSPF + GRE state summary in a single call.

Returns: { router_id, local_as, lab_mode, bgp: {configured, peer_count, peers, rib_size}, ospf: {configured, neighbor_count, neighbors}, gre: {tunnels, addresses, count} }

Environment Variables

FRR Lab Testbed

A Docker-based 3-router FRR topology is provided in lab/frr-testbed/ for testing:

NetClaw (AS 65001) ──GRE── Edge1 (AS 65000) ──OSPF── Core (RR) ──OSPF── Edge2
  host/WSL                  1.1.1.1              2.2.2.2           3.3.3.3
  172.16.0.2                172.16.0.1
  eBGP                      iBGP→Core            iBGP hub          iBGP→Core

# Start lab
cd lab/frr-testbed && docker compose up -d
 
# Create GRE tunnel (requires sudo)
sudo bash scripts/setup-gre.sh
 
# Verify
bash scripts/verify.sh

Workflows

1. Route Injection with Change Control

servicenow-change-workflow → CR approved
→ bgp_inject_route(network, next_hop, local_pref)
→ bgp_get_rib(prefix) → verify route in table
→ pyats-routing → verify on remote devices
→ gait-session-tracking → record change

2. Traffic Engineering via LOCAL_PREF

bgp_get_rib() → current routes
→ bgp_adjust_local_pref(network, local_pref)
→ bgp_get_peers() → verify advertisement
→ gait-session-tracking

3. OSPF Cost Manipulation

ospf_get_neighbors() → verify adjacencies
→ ospf_adjust_cost(interface, cost)
→ ospf_get_lsdb() → verify LSA update
→ pyats-routing → verify SPF reconvergence
→ gait-session-tracking

4. Protocol Health Check

protocol_summary() → full state snapshot
→ bgp_get_peers() → check all Established
→ ospf_get_neighbors() → check all Full
→ gre_tunnel_status() → check all tunnels up
→ gait-session-tracking

5. Controlled Route Withdrawal

servicenow-change-workflow → CR approved
→ bgp_get_rib(prefix) → verify route exists
→ bgp_withdraw_route(network)
→ bgp_get_rib(prefix) → verify withdrawal
→ pyats-routing → verify removal on peers
→ gait-session-tracking

6. Lab Testing (no CR required)

NETCLAW_LAB_MODE=true
→ bgp_inject_route / bgp_withdraw_route
→ bgp_get_rib → verify
→ ospf_adjust_cost → test convergence
→ protocol_summary → snapshot

Integration with Other Skills

Safety Rules

1. NEVER inject or withdraw routes without an approved ServiceNow CR — unless NETCLAW_LAB_MODE=true
2. ALWAYS verify current RIB (bgp_get_rib) before injecting to prevent routing loops
3. ALWAYS verify peer state (bgp_get_peers) before advertising — only to Established peers
4. ALWAYS record protocol changes in GAIT (gait-session-tracking)
5. GRE tunnels require sudo — the install wizard handles initial setup; runtime queries via gre_tunnel_status do not require elevated privileges
6. Lab mode (NETCLAW_LAB_MODE=true) relaxes the CR requirement for the FRR testbed — never set this in production

Guardrails

• Route mutations are gated — ServiceNow CR approval required in production
• Read operations are always safe — bgp_get_peers, bgp_get_rib, ospf_get_neighbors, ospf_get_lsdb, gre_tunnel_status, protocol_summary
• GRE is the default tunnel transport — native Linux kernel support, every major vendor supports it (Cisco, Juniper, Arista, FRR, Nokia), RFC 2784/2890 compliant
• Raw sockets require root for protocol speakers — BGP (TCP/179), OSPF (IP/89), GRE (IP/47)
• No secrets in protocol state — RIB/LSDB queries return routing information, not credentials