Topolograph is a web-based Python tool designed to visualize OSPF and IS-IS network topologies and analyze them offline — with no logins or passwords required.
Topolograph builds OSPF/IS-IS network topology based on Link-State Database (LSDB) data collected from a single network device (thanks to the distributed nature of OSPF and IS-IS 🙂). You can upload LSDB output as a text file, or establish a GRE or BGP-LS session using OSPF Watcher or IS-IS Watcher. BGP-LS carries link-state from either OSPF or IS-IS into Topolograph, depending on which Watcher you use; visualize the topology in a local, Dockerized Topolograph UI.
Once uploaded, the topology represents a snapshot of your network state. After making changes — for example, redistributing routes from BGP into OSPF using route-maps and prefix-lists — you can upload the updated topology and compare it with the previous one to clearly see what has changed.
- No logins or passwords required — accept LSDB data from text files or via REST API
- Docker version available — run a local instance of Topolograph on your PC
- Visualize OSPF and IS-IS network topologies
- Build shortest paths between any nodes
- Discover backup paths, including secondary backup paths
- Simulate link failures and analyze network reaction
- Simulate router failures and observe traffic flow around failed nodes
- Analyze network behavior when IGP link costs change
- Identify the most loaded nodes and links, as well as fault-tolerant elements
- Compare network states across different points in time
- Ingest topology over BGP-LS from OSPF or IS-IS domains (via OSPF Watcher or IS-IS Watcher)
- Detect asymmetric routing paths
- Discover backed-up and non-backed-up networks using the Analytics / Network Heatmap
- Build and visualize arbitrary topologies using YAML-based definitions
Topolograph supports real-time monitoring of changes in OSPF and IS-IS domains using Watcher agents:
| Vendor | LSA1 | LSA2 | LSA5 | SDK nornir driver support |
|---|---|---|---|---|
| Cisco | show ip ospf database router | show ip ospf database network | show ip ospf database external | YES |
| Cisco NX-OS | show ip ospf database router detail | show ip ospf database network detail | show ip ospf database external detail | YES |
| Quagga | show ip ospf database router | show ip ospf database network | show ip ospf database external | YES |
| Ruckus | show ip ospf database link-state router | show ip ospf database link-state network | show ip ospf database external-link-state | YES |
| Juniper | show ospf database router extensive | no-more | show ospf database network extensive | no-more | show ospf database external extensive | no-more | YES |
| Bird | show ospf state all | show ospf state all | show ospf state all | YES |
| Nokia | show router ospf database type router detail | show router ospf database type network detail | show router ospf database type external detail | YES |
| Mikrotik | /routing ospf lsa print detail file=lsa.txt | /routing ospf lsa print detail file=lsa.txt | /routing ospf lsa print detail file=lsa.txt | YES |
| Huawei | display ospf lsdb router | display ospf lsdb network | display ospf lsdb ase | YES |
| Paloalto | show routing protocol ospf dumplsdb | show routing protocol ospf dumplsdb | show routing protocol ospf dumplsdb | YES |
| Ubiquiti1 | show ip ospf database router | show ip ospf database network | show ip ospf database external | YES |
| Allied Telesis | show ip ospf database router | show ip ospf database network | show ip ospf database external | YES |
| Extreme | show ospf lsdb detail lstype router | show ospf lsdb detail lstype network | show ospf lsdb detail lstype as-external | YES |
| Ericsson | show ospf database router detail | show ospf database network detail | show ospf database external detail | YES |
| Fortinet | get router info ospf database router lsa | get router info ospf database network lsa | get router info ospf database external lsa | YES |
| FRRouting | show ip ospf database router | show ip ospf database network | show ip ospf database external | YES |
FRRouting (TE): For richer link data (bandwidth, TE metric, admin group), append the output of show ip ospf database opaque-area to the same file. This is optional; the graph still builds from LSA 1/2/5 alone.
LSA 1 and LSA 2 is mandatory and have to exist in the same file. LSA 5 is optional. The output from all commands should be placed in a single file and then be uploaded to Topolograph.
Topolograph can use Traffic Engineering (TE) link attributes from your LSDB for better visibility and filtering.
- Parsed values: Link-level TE metric, administrative group (affinity), maximum and reservable bandwidth, and unreserved bandwidth per priority. Useful for capacity planning, path analysis, and finding links that meet or exceed certain TE constraints.
- OSPF: Include show ip ospf database opaque-area in the same upload file as your router/network/external LSDB. Type 10 (opaque-area) LSAs carry the TE data; the rest of the graph is built from LSA 1, 2, and 5 as before.
- IS-IS: TE attributes are taken from the IS-IS LSDB when using supported commands (e.g. FRR show isis database detail). No extra command is required beyond your normal IS-IS capture.
- Using TE in Topolograph: Once a diagram is built with TE data, you can filter edges by TE metric or bandwidth via the diagram edges API (e.g. links with TE metric above a threshold or unreserved bandwidth below a value). The same TE attribute names are used for both OSPF and IS-IS.
Filtering TE links via SDK (topolograph-sdk): Use graph.edges_list() with range operators __gt, __lt, __gte, __lte on TE attributes:
# Edges with TE metric >= 100
edges = graph.edges_list(temetric__gte=100)
# Edges with unreserved bandwidth (priority 0) below 1 Gbps
edges = graph.edges_list(unreserved_bw_0__lt=1e9)
# Edges between two nodes with max link bandwidth above 10 Gbps
edges = graph.edges_list(src_node="1.1.1.1", dst_node="2.2.2.2", max_link_bw__gt=1e10)TE attributes: temetric, admin_group, max_link_bw, max_rsrv_link_bw, unreserved_bw_0 … unreserved_bw_7.
| Vendor | Command | Stub network included | External (redistributed) network |
|---|---|---|---|
| Arista | show ipv6 ospf database detail | YES | YES |
| Vendor | Command | Stub network included | External (redistributed) network |
|---|---|---|---|
| Cisco | show isis database detail | YES | No, (need tested LSDB for adding it) |
| Juniper | show isis database extensive | YES, but need tested LSDB for checking it | No, (need tested LSDB for adding it) |
| Nokia | show router isis database detail | YES, but need tested LSDB for checking it | No, (need tested LSDB for adding it) |
| Huawei | display isis lsdb verbose | YES, but need tested LSDB for checking it | No, (need tested LSDB for adding it) |
| ZTE | show isis database verbose | YES, but need tested LSDB for checking it | No, (need tested LSDB for adding it) |
BGP Link-State (BGP-LS) lets a BGP speaker advertise IGP link-state to Topolograph. Topolograph accepts BGP-LS for both OSPF and IS-IS: use OSPF Watcher when your IGP is OSPF, and IS-IS Watcher when it is IS-IS. Setup details are in each project’s README:
Real-time monitoring (including TE link attributes delivered over BGP-LS) appears in the Topolograph UI as updates stream in:
- run commands specifically to your vendor (from Supported vendors table) on a single device ( if you have multiple areas - do it on ABR) save all commands output in a single file with .txt or .log extension and upload the file to Topolograph
- upload programmatically via Rest API. Multi devices LSDBs are supported via API only (v2.34).
- get topology via OSPF Watcher or IS-IS Watcher
- .txt
- .log
YouTube
- OSPF Watcher. Real time Monitoring with instant notification. https://youtu.be/2IHbxmDVMA0
- IS-IS Watcher. Track the whole IS-IS domain from a single router https://youtu.be/7ZQFSe1szk8
- OSPF/IS-IS AI Agent: MCP for Network Protocols, https://youtu.be/92YBRXqZWUo
- BGP-LS in Action: Monitoring IS-IS networks via IS-IS Watcher and Topolograph, https://youtu.be/gL0iqXgPJlE
This demo shows how to get OSPF topology visual and interact with it.
- Upload the file to Topolograph from exicuted commands previously.
- Build the shortest paths
- Emulate a link outage and see backup paths
Pressing on edge we simulate the link outage and can see backup paths
and we can see backup of backup paths as well
It's feasible to change OSPF cost on any edge and get network reaction on the fly!
Build the shortest path under General View and set new OSPF cost in new pop-up-ed form - new path will be repainted
This pop-uped form is available under NetworkReactionOnFailure and shows network traffic pattern changes!
On the demo below we changed OSPF cost from 1 to 22 and OSPF rebuilt the shortest path via bottom link.
Sum it up, available features under GeneralView Tab:
- Build the shortest path, right click on a node and set it as a source or destination.
- Find backup paths, just press on a colored SPT edge and you will simulate link outage. The network reaction will be showed with using different colors.
- OSPF edge cost planning right click on an edge and you can change edge's OSPF cost you see new path of your SPT.
- Find termination node of a network start typing a network in Focus/Source tab and you get a dropdown list with all nodes with this network. Once you choose it - you will be focused on the node.
NetworkReactionOnFailure is covered in how-to
It's possible to simulate a link or router shutdown/outage. The topology will be re-pained with expected changed traffic flow avoiding failed link or router.
- Blue lines show traffic increasing over the link
- Grey lines show traffic decreasing over the link
Try to shutdown backup router and see the graph reaction. If this is a true backup router - there shoudn't be network rebuilding too much
Topolograph AI agent for network assistance with OSPF/IS-IS capabilities. Works with Topolograph MCP.
Interact naturally with OSPF/IS-IS protocols, for instance you can ask:
- Which graphs are currently connected?
- What nodes are in the latest OSPF area 0 graph?
- Which networks are assigned to a specific host?
- What is the route between two IP addresses?
- What happened to the links after topology changes?
When different costs are configured on different links - asymmetric paths could be in the network. The incoming path from W to F is going via C-D, but the outgoing path is via B-A. Paths can go via different ISPs and come with different delays and, probably, losses. The report is aimed at discovering such cases in order to eliminate it.
The topolograph knows what networks are advertised by nodes. When the network is terminated on both routers, using VRRP, both nodes advertise the network. The node is marked by red if it has a lot of unbackuped networks, and vise versa.
- We suggest that if we have multiple links bounded to ECMP and if the main link in ECMP goes down, the backup path should go via the second link in ECMP. passed report
- If backup path goes not via ECMP and chooses completely different path - the report will be treated as failed. failed report
Keep your network inside your organization.
Run your local copy of Topolograph inside your on-premises network using the docker image.
Full schema description is here
Default credentials are available via environment variables in case of using docker-based version. How to set it described in this case.
For a more Pythonic interface to the Topolograph API, use the Topolograph Python SDK:
pip install topolograph-sdkThe SDK provides an object-oriented interface that simplifies working with Topolograph. All examples below show both REST API and SDK usage.
Started from v2.19. Scrab your LSDB using your favourite tools like Ansible, netmiko, Nornir, etc and upload your OSPF network graph to Topolograph via a POST request. The response returns:
- diff comparison with previously uploaded graphs
- link to get all networks
- status about passed checks (are there are asymmetric links in the network, etc)
{'diff': {'compared_with_graph_time': '08Jun2021_20h15m26s_13_hosts',
'graphs_diff': {'all_edges_stats_ll': [{'dst_node': '123.123.110.110',
'link_cost': 10,
'link_status': 'old',
'src_node': '123.123.100.100'],
'new_nodes': [],
'old_nodes': []},
'networks_diff': {'new_subnets_attr_dd_ll': [{'rid': '123.30.30.30',
'subnet': '30.30.30.30/32'}],
'old_subnets_attr_dd_ll': []}},
'graph_time': '08Jun2021_20h15m51s_13_hosts',
'hosts': {'count': 13},
'networks': {'backuped': 17,
'count': 39,
'notbackuped': 22,
'url_link': 'https://topolograph.com/api/network/08Jun2021_20h15m51s_13_hosts'},
'reports': {'ansym_edges_pass_status': False},
'timestamp': '2021-06-08T20:15:51.724000'}
REST API:
import requests
from pprint import pprint as pp
with open('cisco_lsdb_output.txt') as f:
lsdb_output = f.read()
r_post = requests.post('https://topolograph.com/api/graph', auth=('youraccount@domain.com', 'your-pass'),
json={'lsdb_output': lsdb_output, 'vendor_device': 'Cisco', 'igp_protocol': 'ospf'})
pp(r_post.json())
igp_protocol may include ospf or isis
SDK:
from topolograph import Topolograph
# Initialize client
topo = Topolograph(
url="topolograph-url",
token="your-api-token"
)
# Upload LSDB file
with open('cisco_lsdb_output.txt') as f:
lsdb_output = f.read()
graph = topo.graphs.upload(
lsdb_data=lsdb_output,
vendor="Cisco",
protocol="ospf"
)
print(f"Graph uploaded: {graph.graph_time}")
print(f"Hosts: {graph.hosts['count']}")
print(f"Networks: {graph.networks_data.get('count', 0)}")SDK with FRR lab (collecting real data):
from topolograph import Topolograph, TopologyCollector
# Initialize client
topo = Topolograph(
url="topolograph-url",
token="your-api-token"
)
# Collect LSDB from FRR routers
collector = TopologyCollector("inventory.yaml") # Contains FRR router credentials
result = collector.collect()
# Upload collected data
graph = topo.uploader.upload_raw(
lsdb_text=result.raw_lsdb_text,
vendor="FRR",
protocol="isis"
)
print(f"Graph uploaded: {graph.graph_time}")It allows to get the shortest path between two OSPF RID, or it also accepts IP address or IP Subnet as source/destination and returns the following:
- path's cost
- the shortest path
- unbackuped parts of the shortest path (if these links go down, we will lose a connectivity between the source and destination).
src_node and dst_node accepts OSPF RID as a value.
REST API:
r_post = requests.post('https://topolograph.com/api/path', auth=('', ''),
json={'graph_time': '27Dec2022_22h46m01s_7_hosts_ospfwatcher', 'src_node': '192.168.100.100', 'dst_node': '10.1.123.23'})
Reply
r_post.json()
{'cost': 30,
'spt_path_nodes_name_as_ll_in_ll': [['192.168.100.100', '10.1.1.4', '10.1.1.2', '10.1.123.23']],
'unbackup_paths_nodes_name_as_ll_in_ll': [['192.168.100.100', '10.1.1.4']]}
A '192.168.100.100' - '10.1.1.4' link is shown as nonbackuped
The visual path
SDK:
from topolograph import Topolograph
topo = Topolograph(url="topolograph-url", token="your-token")
# Get graph
graph = topo.graphs.get_by_time("27Dec2022_22h46m01s_7_hosts_ospfwatcher")
# Get shortest path
path = graph.paths.shortest("192.168.100.100", "10.1.123.23")
print(f"Path cost: {path.cost}")
for path_nodes in path.paths:
print(f"Path: {' -> '.join(path_nodes)}")
# Unbackuped parts
for unbackup_path in path.unbackup_paths:
print(f"Unbackuped segment: {' -> '.join(unbackup_path)}")removedEdgesAsNodePairsFromSptPath_ll_in_ll accepts a list of edges which will be treated as down links
REST API:
r_post = requests.post('https://topolograph.com/api/path', auth=('', ''),
json={'graph_time': '27Dec2022_22h46m01s_7_hosts_ospfwatcher', 'src_node': '192.168.100.100', 'dst_node': '10.1.123.23',
'removedEdgesAsNodePairsFromSptPath_ll_in_ll': [['10.1.1.4', '10.1.1.2']]})
r_post.json()
{'cost': 40,
'spt_path_nodes_name_as_ll_in_ll': [['192.168.100.100', '10.1.1.4', '10.1.1.3', '10.1.1.2', '10.1.123.23']],
'unbackup_paths_nodes_name_as_ll_in_ll': [['192.168.100.100', '10.1.1.4']]}
The visual path
SDK:
from topolograph import Topolograph
topo = Topolograph(url="topolograph-url", token="your-token")
graph = topo.graphs.get_by_time("27Dec2022_22h46m01s_7_hosts_ospfwatcher")
# Get backup path (simulating link failure)
path = graph.paths.shortest(
"192.168.100.100",
"10.1.123.23",
removed_edges=[("10.1.1.4", "10.1.1.2")]
)
print(f"Backup path cost: {path.cost}")
for path_nodes in path.paths:
print(f"Backup path: {' -> '.join(path_nodes)}")There is a separate method for getting the shortest path, which accepts IP addresses/IP network as an input.
Let's build a path between 192.1.113.99 IP and 192.1.213.0/24 network.
REST API:
r_post = requests.post('https://topolograph.com/api/path/network', auth=('', ''),
json={'graph_time': '27Dec2022_22h46m01s_7_hosts_ospfwatcher', 'src_ip_or_network': '192.1.113.99', 'dst_ip_or_network': '192.1.213.0/24'})
Reply
r_post.json()
{'cost': 20,
'spt_path_nodes_name_as_ll_in_ll': [['10.1.1.1', '10.1.1.4', '10.1.1.2'], ['10.1.1.1', '10.1.1.3', '10.1.1.2']],
'unbackup_paths_nodes_name_as_ll_in_ll': []}
The visual path
SDK:
from topolograph import Topolograph
topo = Topolograph(url="topolograph-url", token="your-token")
graph = topo.graphs.get_by_time("27Dec2022_22h46m01s_7_hosts_ospfwatcher")
# Get shortest path between networks/IPs
path = graph.paths.shortest_network("192.1.113.99", "192.1.213.0/24")
print(f"Path cost: {path.cost}")
for path_nodes in path.paths:
print(f"Path: {' -> '.join(path_nodes)}")We have the following topology
Emulate powering off nodes 10.1.1.2 and 10.1.1.4.
- Link over utilisation will occurs?
- Network reachability will be broken? Some nodes will be isolated?
REST API:
import requests
from pprint import pprint as pp
r_post = requests.post('http://<topolograph-host>/api/network_reaction/node_failure/', auth=(' ', ' '),
json={"graph_time": "25Nov2021_08h20m45s_7_hosts", "failed_nodes_list": ["10.1.1.2", "10.1.1.4"]})
pp(r_post.json())
Reply
{'affectedLinks': {'sptPathsDecreasedInPercent': {},
'sptPathsIncreasedInPercent': {'from': '10.1.1.1',
'to': '10.1.1.3',
'value': 60}},
'disjointedNodes': [['10.1.123.23', '10.1.123.24'],
['192.168.100.100'],
['10.1.1.1', '10.1.1.3']],
'isGraphStillConnected': False}
SDK:
from topolograph import Topolograph
topo = Topolograph(url="topolograph-url", token="your-token")
graph = topo.graphs.get_by_time("25Nov2021_08h20m45s_7_hosts")
# Simulate node failures
reaction = graph.events.get_network_reaction_on_node_failure(
failed_nodes=["10.1.1.2", "10.1.1.4"]
)
print(f"Graph still connected: {reaction['isGraphStillConnected']}")
print(f"Disjointed node groups: {reaction['disjointedNodes']}")
print(f"Affected links: {reaction['affectedLinks']}")Topolograph visualizes topologies based on OSPF/IS-IS LSDB files, but starting from v2.32 it accepts YAML to build a graph. It can be used for building arbitrary topologies (not exactly IGP domains), but moreover it can keep the topology updated via Rest API. It's the first version of Network Diagram as a Service (NDAS)!
OSPF/IS-IS LSDB <-> YAML is interchangeable now in both ways, so it allows to make a design of IGP domain from the scratch or based on uploaded a LSDB, add new links/edges between nodes or change igp's cost and then check network reaction based on our changes.
Build a graph with defined nodes and edges.
REST API:
import requests
yaml_diagram = """
nodes:
10.10.10.1:
label: Router1
10.10.10.2:
label: Router2
edges:
- src: 10.10.10.1
dst: 10.10.10.2
cost: 10
"""
r_post = requests.post('http://<topolograph-host>/api/diagram',
auth=('', ''),
json={'yaml_diagram_str': yaml_diagram})
SDK:
from topolograph import Topolograph
topo = Topolograph(url="topolograph-url", token="your-token")
yaml_diagram = """
nodes:
10.10.10.1:
label: Router1
10.10.10.2:
label: Router2
edges:
- src: 10.10.10.1
dst: 10.10.10.2
cost: 10
"""
# Upload YAML diagram
graph = topo.graphs.upload_diagram(yaml_diagram)
print(f"Diagram uploaded: {graph.graph_time}")node's nameis mandatory. Should be in IP-address format. To change it to any other value - uselabel- Tags of node are optional. Any key (type string): value (str, int, float, dictionary, list) pairs.
There is a graph with 6 nodes. Select all primary nodes (ha_role:primary) in the first DC (dc1)
REST API:
import requests
from pprint import pprint as pp
query_params = {'location': 'dc1', 'ha_role': 'primary'}
r_get = requests.get(f'http://{TOPOLOGRAPH_HOST}:{TOPOLOGRAPH_PORT}/api/diagram/{graph_time}/nodes', auth=(' ', ' '), params=query_params, timeout=(5, 30))
Reply
pp(r_get.json())
[{'ha_role': 'primary',
'id': 1,
'label': '10.10.10.2',
'location': 'dc1',
'name': '10.10.10.2',
'size': 15}]
SDK:
from topolograph import Topolograph
topo = Topolograph(url="topolograph-url", token="your-token")
graph = topo.graphs.get_by_time("18Jan2026_15h53m13s_3_hosts_yaml")
# Query nodes by attributes
nodes = graph.nodes.get(location='dc1', ha_role='primary')
for node in nodes:
print(f"Node: {node.name}, Location: {node.attributes.get('location')}")
# Update node attributes
node = graph.nodes.get_by_id(0)
updated_node = graph.nodes.patch(node.id, {'name': 'renamed_router', 'location': 'dc2'})
print(f"Updated node: {updated_node.name}")
# Or use instance method
node = graph.nodes.get_by_id(0)
updated_node = node.patch(name='new_name', location='dc2')src,dstis mandatory.costis optional. Default is 1. Equal to OSPF/IS-IS cost.directedis optional. Default is false.- Tags of edge are optional. Any key (type string): value (str, int, float, dictionary, list) pairs.
Select all edges over verizon ISP between10.10.10.2and10.10.10.4
REST API:
query_params = {'src_node': '10.10.10.2', 'dst_node': '10.10.10.4', 'isp': 'verizon'}
r_get = requests.get(f'http://{TOPOLOGRAPH_HOST}:{TOPOLOGRAPH_PORT}/api/diagram/{graph_time}/edges', auth=(' ', ' '), params=query_params, timeout=(5, 30))
Reply
pp(r_get.json())
[{'bw': 1000,
'cost': 1,
'dst': '10.10.10.4',
'id': 3,
'isp': 'verizon',
'media': 'fiber',
Let's add a new link with cost 1 between R3 (10.10.10.3) and R4 (10.10.10.4) device and see how network will react on it.
Obviously, we see traffic increase on direct link R3<->R4 and traffic decrease to R2 (10.10.10.2) and R5 (10.10.10.5).
- Telegram group: https://t.me/topolograph
- Main site: https://topolograph.com
- Topolograph MCP: https://github.com/Vadims06/topolograph-mcp-server – MCP interface for Topolograph
- Topolograph SDK: https://github.com/Vadims06/topolograph-sdk – Python SDK with nornir driver for automated LSDB collection
- Docker version of site: https://github.com/Vadims06/topolograph-docker
- Online doc: https://topolograph.com/how-to
If you just upload LSDB and press Delete -> topology will be deleted and added again. Just press Upload LSDB Tab again and then deleting of topology works fine.
Email me admin at topolograph.com and can open the access to the repository.
In order to project supports different vendors you can help us by creating five separate textfsm files for different LSA types for one vendor. Check Wiki for this.
The Topolograph SDK uses a nornir driver to collect LSDB data from network devices. To add support for a new vendor, add the vendor's commands to the command registry in topolograph/collector/commands.py:
COMMAND_REGISTRY = {
"ospf": {
"your_vendor": [
"show ip ospf database router", # LSA1 command
"show ip ospf database network", # LSA2 command
"show ip ospf database external" # LSA5 command (optional)
]
},
"isis": {
"your_vendor": [
"show isis database detail" # IS-IS LSDB command
]
}
}After adding the vendor, submit a pull request to the topolograph-sdk repository. The SDK will automatically use these commands when collecting LSDB data from devices with the specified vendor in the inventory file.
RFC 2328
Footnotes
-
This command applies to the EdgeRouter line and older Unifi USG Gateways. New Unifi Gateway products use the FRRouting Project. ↩