Topology Graph (Graphviz) Output Module

graph output module create a graph description of network topology or routing protocols in Graphviz DOT format. You can use that description with Graphviz commands to create topology- or routing protocol diagrams in numerous output formats.

Note: The graph descriptions contain nodes and links, but no placement information. Graphviz is pretty good at figuring out how to draw the required graph, but it pays off to test out various layout engines (hint: use the name of the layout engine as the CLI command) and node ranks.

Creating Graph Description File

The graph output module is invoked with the netlab graph command or by specifying the -o graph parameter in the netlab create command. It takes an optional destination file name (default: graph.dot).

The -t parameter of the netlab graph command or a formatting modifier in the netlab create -o parameter can be used to specify the graph type:

• topology (default) – Display inter-node links, multi-access-, and stub subnets. When the network topology contains BGP information, the graph groups nodes into autonomous systems. Alternatively, you could set defaults.outputs.graph.groups attribute to use topology groups to group graph nodes.

• bgp – Include autonomous systems, BGP routers, and color-coded BGP sessions.

• isis – Create a diagram of IS-IS routing, including areas, color-coded circuit types, and edge subnets (does not work with IS-IS running over VLANs)

Tip

The ‑f parameter of the netlab graph command or a formatting modifier of the ‌netlab create ‑o parameter can include BGP formatting parameters. For example, netlab graph -t bgp -f rr draws RR-client sessions as directed arrows.

Use the dot command (or another Graphviz command) to create a graph from a graph description file. The Graphviz commands take the -T argument to specify the output format (for example, png or svg) and the -o argument to specify the output file. For example, use the following command to create graph.png:

$ dot graph.dot -T png -o graph.png

Modifying Global, Link, and Node Attributes

You can set the graph title with graph.title or defaults.graph.title topology attribute.

You can use the graph link and node attributes to change the style of individual nodes or links. The following attributes are built into netlab[1]:

• graph.color – line color (color Graphviz attribute)

• graph.fill – fill color (fillcolor Graphviz attribute)

• graph.width – line width (penwidth Graphviz attribute)

You can also use the graph.format parameter to specify the Graphviz attributes for individual nodes or links[2]. For example, to change the width of a node to 2 inches, use:

nodes:
  spine:
    graph.format.width: 2

Likewise, to turn a link into a dashed line, use:

links:
- interfaces: [ a,b ]
  graph.format.style: dashed

Influencing the Graph Layout

netlab uses the node graph.rank attribute to:

1. Tell Graphviz that nodes with the same graph.rank should be at the same rank (vertical position) in the graph

2. Sort nodes in link definitions to ensure the graph edges are always defined as going from nodes with a lower rank to nodes with a higher rank. The order of nodes in the graph edges influences the Graphviz layout engine.

The default value of the graph.rank attribute is 100, allowing you to push some nodes (with rank below 100) toward the top of the graph and others (with rank above 100) toward the bottom.

You can also use the graph.rank on links to influence how Graphviz draws multi-access links.

Finally, the link/interface graph.linkorder attribute allows you to specify the node order in individual links. The default graph.linkorder value is 50 for interfaces and 100 for subnets (multi-access links), resulting in subnets being “below” nodes unless you change the link- or interface graph.linkorder value.

Modifying Graph Appearance

Graphing routines use defaults topology settings to modify the generated DOT file’s node- or link parameters. These defaults influence how your graphs look:

• outputs.graph.as_clusters (default: True) – use BGP AS numbers to create graph clusters

• outputs.graph.groups – use the specified list of groups (or all groups when set to True) to create graph clusters

• outputs.graph.interface_labels – Add IP addresses to links in topology graph. Results in a cluttered image (but feel free to fix that and submit a pull request).

• outputs.graphs.node_address_label (default: True) – add node loopback IP addresses or IP addresses of the first interface (for hosts) to node labels.

These default settings modify how the topology graphs look:

• outputs.graph.topology.vlan (default: False) – draw VLAN links in a different color. Use wider lines for VLAN trunk links.

Tip

You can specify the above formatting parameter in the graph format CLI argument, for example, netlab create -o graph:topology:vlan or netlab graph -t topology -f vlan.

These default settings modify how the BGP graphs look:

• outputs.graph.bgp.all (default: False) – show all lab devices in the BGP graph. By default, the BGP graphs include only lab devices running BGP

• outputs.graph.bgp.rr (default: True) – draw arrows on BGP sessions to indicate peer-to-peer versus reflector-client sessions

• outputs.graph.bgp.vrf (default: False) – draw VRF BGP sessions as dotted lines

• outputs.graph.bgp.af.af (default: all address families) – when one or more af parameters (valid keys: ipv4, ipv6, vpnv4, vpnv6, 6pe, evpn) are set to True, the graph is limited to BGP sessions of the specified address families.

• outputs.graph.bgp.novrf (default: False) – do not include VRF BGP sessions in the graph

Tip

You can specify the above BGP parameters in the graph format CLI argument, for example, netlab create -o graph:bgp:vrf or netlab graph -t bgp -f vrf.

Graph Object Styles

Finally, you can also change the formatting of individual graph objects with the outputs.graph.styles.object defaults:

Object	Description
graph	Generic graph formatting
node	Device formatting
edge	Link formatting
as	Autonomous system/group container formatting
stub	Subnet formatting
title	Graph title formatting
ibgp	IBGP session formatting
ebgp	IBGP session formatting
vrf	BGP VRF session formatting
localas_ibgp	Local-AS IBGP session formatting
confed_ebgp	Confederation EBGP session formatting
level-1	IS-IS level-1-only link
level-2	IS-IS level-2-only link
level-1-2	IS-IS level-1-2 link
vlan_access	VLAN access link
vlan_trunk	VLAN trunk link

Each styles parameter is a dictionary of Graphviz attributes and their values.

You could specify the graph defaults in your topology file (where you would have to prefix them with defaults), in per-user topology defaults, or with environment variables (even more details). You could also specify them with the -s parameter of the netlab create command, yet again prefixed with defaults (more details).

To display the current Graphviz styles, use the netlab show defaults outputs.graph.styles command.

Tip

Older netlab releases (prior to release 25.09) used different default settings to change a few graph parameters. You can still change those defaults, but don’t use them in new projects:

• outputs.graph.colors.object – Specify background color for as, node, stub subnet, ibgp or ebgp session.

• outputs.graph.margins.as – Inner margin for graph clusters (BGP autonomous system or groups).

Sample Graphs

The lab topologies used for platform integration testing contain numerous examples of graph attributes:

• Leaf-and-spine topology used to create topology graphs and test node- and link attributes and custom formatting.

• EVPN topology used to create BGP graphs

• IS-IS topology used to create IS-IS graphs and test node ranking

You’ll find further graph-creation tips on the ipSpace.net blog.

---

[1]

You can extend the Graphviz styling capabilities and add new graph attributes. See Extending D2 Style Attributes for details.

[2]

Link attributes are applied to links between nodes or to the node representing a multi-access subnet.