IS-IS Topology Watcher

IS-IS Watcher is a monitoring tool of IS-IS topology changes for network engineers. It works via passively listening to IS-IS control plane messages through either a specially established IS-IS adjacency (GRE mode) or by receiving BGP-LS updates from a network router (BGP-LS mode). The tool logs IS-IS events and/or export by Logstash to Elastic Stack (ELK), Zabbix, WebHooks and Topolograph monitoring dashboard for keeping the history of events, alerting, instant notification. By encapsulating the solution's elements in containers, it becomes exceptionally quick to start.

IS-IS Watcher detects the following network events:

IS-IS neighbor adjacency Up/Down
IS-IS link cost changes
IS-IS networks appearance/disappearance from the topology
IS-IS TE attributes:
- Administrative Group (color, resource class)
- Maximum Link Bandwidth
- Maximum Reservable Link Bandwidth
- Unreserved Bandwidth
- Traffic Engineering Default Metric

Architecture

Connection Modes

IS-IS Watcher supports two connection modes:

GRE Mode (Traditional)

The FRR container is isolated in an individual network namespace and establishes an IS-IS adjacency over a GRE tunnel with a network device. The XDP IS-IS filter inspects all outgoing IS-IS advertisements. It checks if FRR instance advertises only locally connected network (assigned on GRE tunnel) and no more. If it advertises multiple networks, IS-IS LSP will be dropped. It prevents the network from populating by unexpected network prefixes.

BGP-LS Mode (New)

The watcher connects to a network router via BGP-LS (BGP Link-State) protocol. The router must be configured to advertise IS-IS topology information via BGP-LS. The watcher uses GoBGP (bgplswatcher) to establish a BGP session and receive BGP-LS updates, which are then processed by the IS-IS watcher component. This mode eliminates the need for GRE tunnels and IS-IS adjacencies, making it easier to deploy in environments where GRE tunnels are not feasible.

[!NOTE] isiswatcher:v1.0 is compatible with topolograph:v2.38 , it means that IS-IS network changes can be shown on the network graph.

Functional Role

Watcher stores topology events/state to show historical network state, whereas Topolograph exhibits present network state and potential future outcomes.

Supported IS-IS TLV

| TLV name | TLV | subTLV | |----------------------------------|-----|------------------------| | IS Reachability | 2 | | | Extended IS Reachability (new) | 22 | 3,6,8,9,10,11,12,13,18 | | IPv4 Internal Reachability (old) | 128 | | | IPv4 External Reachability (old) | 130 | | | Extended IPv4 Reachability (new) | 135 | | | IPv6 Reachability | 236 | |

Network architecture

GRE Mode: Number of watchers is equal to the number of IS-IS areas and each Watcher is placed in individual network namespace. IS-IS LSDB sits in watcher's namespace and doesn't interact with other Watchers keeping it isolated.
BGP-LS Mode: Each watcher connects to a BGP-LS capable router. Multiple watchers can connect to the same router if it advertises multiple IS-IS areas, or each watcher can connect to different routers.

Demo

The demo shows how IS-IS watcher detected:

p2p links:

metric cost changes on eth1 interface on router2 from 10 to 11. There were three duplicated logs for each level: L1 and L2.
0100.1001.0002 (router2) went down for L2 after applying "isis circuit-type level-1" on it and router3 detected that.
metric cost changes on eth1 interface on router2 from 11 to 12 only for L1.

broadcast links:

new stub network was added on router6 in L2
0100.1001.0004 went down and 0100.1001.0005 (router5) detected that

Discovering IS-IS logs in Kibana. Examples

Cost attribute, metric

IS-IS cost changes on links

IS-IS adjacency

Logs if IS-IS adjacency was Up/Down or any networks appeared/disappeared.

IS-IS TE metric

Latest events about links with admin group 17 with unreserved bandwidth for priority of 0 less than 100Mbits

Full IS-IS TE log

Topolograph IS-IS Monitoring.

Monitoring dashboard allows to see events on the timeline and on the topology. Red timelines show link (~adjacency) down events, green one - up link (~adjacency).
Events are grouped by IS-IS level (L1/L2).
Here is a demo of checking events on Monitoring dashboard ./docs/isisdemo_with_topolograph_au.mp4

IS-IS topology change notification/alarming via Zabbix. Examples

Zabbix's dashboard with active alarms. It's universal method to track OSPF and IS-IS events. The screenshot is taken from OSPF watcher.

Zabbix IS-IS neighbor up/down alarm

This alarm tracks all new IS-IS/OSPF adjacencies or when a device loses its neighbor. The screenshot is taken from OSPF watcher.

Zabbix IS-IS Cost changed on transit links

Transit links are all links between active IS-IS/OSPF neighbors. If cost on a link was changed it might affect all actual/shortest paths traffic follows. The screenshot is taken from OSPF watcher.

Zabbix alert if IS-IS network was stopped announcing from node

If a subnet was removed from IS-IS/OSPF node (the node withdrew it from the announcement) it means the network from this node became unavailable for others, this event will be logged too. The screenshot is taken from OSPF watcher.

Slack notification

HTTP POST messages can be easily accepted by messengers, which allows to get instant notifications of IS-IS/OSPF topology changes: The screenshot is taken from OSPF watcher.

Quick lab

Containerlab

Containerlab's topology is placed under containerlab folder. Local README includes instructions how to run it. IS-IS topology changes are printed by Watcher in a text file only. IS-IS watcher containerlab

./containerlab/frr01/prepare.sh
sudo clab deploy --topo ./containerlab/frr01/frr01.clab.yml

How to connect IS-IS watcher to real network

Table below shows different options of possible setups, starting from the bare minimum in case of running Containerlab for testing and ending with maximum setup size with Watcher, Topolograph and ELK. The following setup describes setup №1 and №2. | № | Deployment size | Number of compose files | Text file logs | View changes on network map | Zabbix/HTTP/Messengers notification | Searching events by any field any time | |---|--------------------------------------------------------------------------------------------|-------------------------|----------------|-----------------------------|-------------------------------------|----------------------------------------| | 1 | Bare minimum. Containerlab | 0 | ✅ | ❌ | ❌ | ❌ | | 2 | 1. Local Topolograph <br>2. local compose file with ELK disabled (commented) | 2 | ✅ | ✅ | ✅ | ❌ | | 3 | 1. Local Topolograph <br>2. local compose file with ELK enabled | 3 | ✅ | ✅ | ✅ | ✅ |

Setup №2. Text logs + timeline of network changes on Topolograph

Choose a Linux host with Docker installed
Run script:

curl -O https://raw.githubusercontent.com/Vadims06/topolograph-docker/master/install.sh
chmod +x install.sh
sudo ./install.sh

It will:

Install Docker, Containerlab, Git, and conntrack (if not already installed)
Install and start Topolograph
Guide you through IS-IS Watcher setup (GRE or BGP-LS mode)
Configure watcher for either local Containerlab or network device deployment
Start Logstash for log export

Alternatively, you can setup manually:

Setup Topolograph

launch your own Topolograph on docker using topolograph-docker
create a user for API authentication using Local Registration form on the Topolograph page, add your IP address in API/Authorised source IP ranges. Set variables in .env file:

[!NOTE]

TOPOLOGRAPH_HOST - set the IP address of your host, where the docker is hosted (if you run all demo on a single machine), do not put localhost, because ELK, Topolograph and IS-IS Watcher run in their private network space

TOPOLOGRAPH_PORT - by default 8080

TOPOLOGRAPH_WEB_API_USERNAME_EMAIL - by default ospf@topolograph.com or put your recently created user

TOPOLOGRAPH_WEB_API_PASSWORD - by default ospf

TEST_MODE - if mode is True, a demo IS-IS events from static file will be up

Isiswatcher

Install / Use

README