Topolograph

May 1, 2026 Β· View on GitHub

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.

Key Features

  • 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

Real-Time Monitoring

Topolograph supports real-time monitoring of changes in OSPF and IS-IS domains using Watcher agents:

Supported vendors for OSPF visualization

VendorLSA1LSA2LSA5SDK nornir driver support
Ciscoshow ip ospf database routershow ip ospf database networkshow ip ospf database externalYES
Cisco NX-OSshow ip ospf database router detailshow ip ospf database network detailshow ip ospf database external detailYES
Quaggashow ip ospf database routershow ip ospf database networkshow ip ospf database externalYES
Ruckusshow ip ospf database link-state routershow ip ospf database link-state networkshow ip ospf database external-link-stateYES
Junipershow ospf database router extensive | no-moreshow ospf database network extensive | no-moreshow ospf database external extensive | no-moreYES
Birdshow ospf state allshow ospf state allshow ospf state allYES
Nokiashow router ospf database type router detailshow router ospf database type network detailshow router ospf database type external detailYES
Mikrotik/routing ospf lsa print detail file=lsa.txt/routing ospf lsa print detail file=lsa.txt/routing ospf lsa print detail file=lsa.txtYES
Huaweidisplay ospf lsdb routerdisplay ospf lsdb networkdisplay ospf lsdb aseYES
Paloaltoshow routing protocol ospf dumplsdbshow routing protocol ospf dumplsdbshow routing protocol ospf dumplsdbYES
Ubiquiti1show ip ospf database routershow ip ospf database networkshow ip ospf database externalYES
Allied Telesisshow ip ospf database routershow ip ospf database networkshow ip ospf database externalYES
Extremeshow ospf lsdb detail lstype routershow ospf lsdb detail lstype networkshow ospf lsdb detail lstype as-externalYES
Ericssonshow ospf database router detailshow ospf database network detailshow ospf database external detailYES
Fortinetget router info ospf database router lsaget router info ospf database network lsaget router info ospf database external lsaYES
FRRoutingshow ip ospf database routershow ip ospf database networkshow ip ospf database externalYES

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.

Supported vendors for OSPFv3 visualization

VendorCommandStub network includedExternal (redistributed) network
Aristashow ipv6 ospf database detailYESYES

Supported vendors for ISIS visualization

VendorCommandStub network includedExternal (redistributed) network
Ciscoshow isis database detailYESNo, (need tested LSDB for adding it)
Junipershow isis database extensiveYES, but need tested LSDB for checking itNo, (need tested LSDB for adding it)
Nokiashow router isis database detailYES, but need tested LSDB for checking itNo, (need tested LSDB for adding it)
Huaweidisplay isis lsdb verboseYES, but need tested LSDB for checking itNo, (need tested LSDB for adding it)
ZTEshow isis database verboseYES, but need tested LSDB for checking itNo, (need tested LSDB for adding it)

Visualization via BGP-LS

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:

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.

How to start

  • 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

Expected file's extension

  • .txt
  • .log

Demo

YouTube

Upload OSPF LSDB to the Topolograph and Building the shortest paths

This demo shows how to get OSPF topology visual and interact with it.

  1. Upload the file to Topolograph from exicuted commands previously.
  2. Build the shortest paths
  3. Emulate a link outage and see backup paths

Pressing on edge we simulate the link outage and can 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

OSPF cost changes on the fly. OSPF cost planning.

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

LLM friendly

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?

Reports

Asymmetric paths

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.

Network heatmap

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.

ECMP backup paths

  • 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
    passed report
  • If backup path goes not via ECMP and chooses completely different path - the report will be treated as failed. failed report
    passed report

Private

Keep your network inside your organization. Run your local copy of Topolograph inside your on-premises network using the docker image.

API

Schema

Full schema description is here

Default credentials

Default credentials are available via environment variables in case of using docker-based version. How to set it described in this case.

Python SDK

For a more Pythonic interface to the Topolograph API, use the Topolograph Python SDK:

pip install topolograph-sdk

The SDK provides an object-oriented interface that simplifies working with Topolograph. All examples below show both REST API and SDK usage.

Details

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'}

API graph upload

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}")

Get the shortest path

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)}")

Get backup 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)}")

get the shortest path for networks

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)}")

Network reaction on a failure

We have the following topology
image

Test case

Emulate powering off nodes 10.1.1.2 and 10.1.1.4.

What we would like to test

  • 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']}")

Yaml based topology

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.

Basic YAML based topology.

Build a graph with defined nodes and edges. https://user-images.githubusercontent.com/20796986/144145217-454c1442-ba6c-4337-a6f2-8dde5d337f1e.png

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 attributes

  • node's name is mandatory. Should be in IP-address format. To change it to any other value - use label
  • Tags of node are optional. Any key (type string): value (str, int, float, dictionary, list) pairs. image
    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')

Edge attributes

  • src, dst is mandatory.
  • cost is optional. Default is 1. Equal to OSPF/IS-IS cost.
  • directed is optional. Default is false.
  • Tags of edge are optional. Any key (type string): value (str, int, float, dictionary, list) pairs. image
    Select all edges over verizon ISP between 10.10.10.2 and 10.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. image 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).

Online Resources. Contacts

Known issues

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.

Contribution.

Adding new feature into core of Topolograph

Email me admin at topolograph.com and can open the access to the repository.

adding new vendor

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.

Adding new vendor support via SDK

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.

Used RFC

RFC 2328

Footnotes

  1. This command applies to the EdgeRouter line and older Unifi USG Gateways. New Unifi Gateway products use the FRRouting Project. ↩