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, and 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
• 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:

• OSPF Watcher
• IS-IS Watcher

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.

• Please check README of IS-IS Watcher how to setup BGP-LS session.

• 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.

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
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.

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.

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

Upload you OSPF network via python. Supposed that you saved commands output into cisco_lsdb_output.txt.

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=('[email protected]', 'your-pass'), 
                          json={'lsdb_output': lsdb_output, 'vendor_device': 'Cisco', 'igp_protocol': 'ospf'})
  pp(r_post.json())

igp_protocol may include ospf or isis

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.

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

removedEdgesAsNodePairsFromSptPath_ll_in_ll accepts a list of edges which will be treated as down links

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

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.

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

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?
  Test request:

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}

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.

• 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.
  There is a graph with 6 nodes. Select all primary nodes (ha_role: primary) in the first DC (dc1)

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

• 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.
  Select all edges over verizon ISP between 10.10.10.2 and 10.10.10.4

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
• 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.

For adding scrapping OSPF by NAPALM - please create three additional methods and ping me to add it to topolograph. The example based on Cisco IOS NAPALM

    def get_ospf_router_lsa_raw_output(self):
        command_router = 'show ip ospf database router'

        show_ospf_lsdb_router_lsa_output = self._send_command(command_router).strip()
        return show_ospf_lsdb_router_lsa_output

    def get_ospf_network_lsa_raw_output(self):
        command_network = 'show ip ospf database network'

        show_ospf_lsdb_network_lsa_output = self._send_command(command_network).strip()
        return show_ospf_lsdb_network_lsa_output


    def get_ospf_external_lsa_raw_output(self):
        command_external = 'show ip ospf database external'

        show_ospf_lsdb_external_lsa_output = self._send_command(command_external).strip()
        return show_ospf_lsdb_external_lsa_output

RFC 2328