Network diagrams sit at the heart of every infrastructure team's workflow. They show how devices connect, where traffic flows, and which segments depend on each other. Yet most engineers still build these diagrams by hand in Visio or draw.io, updating them manually every time the network changes. A Bash script to generate network architecture diagrams removes that friction. It reads your inventory data, runs on any Linux machine, and produces a visual output you can share, version-control, and regenerate on demand. If you manage more than a handful of devices, automating diagram creation saves hours every month and cuts down on stale documentation.

What does a Bash script for network diagrams actually do?

At its core, a Bash script that generates network architecture diagrams reads structured data like a CSV file, an inventory from Ansible, or output from SNMP queries and feeds that data into a diagramming engine. The script itself doesn't draw boxes and lines. Instead, it acts as the glue between your network data and a rendering tool such as Graphviz, which uses the DOT language to produce visual graphs.

The typical pipeline looks like this:

  1. Collect device and connection data (from a file, API, or command output).
  2. Transform that data into a DOT-format graph description.
  3. Run Graphviz (or a similar tool) to render the diagram as PNG, SVG, or PDF.

Bash handles steps one and two well because it excels at reading files, piping data, and writing output. If you're already working in a Linux environment, you don't need to install Python or Node.js just to draw a few boxes.

When would you use Bash instead of a full programming language?

Bash works best for small-to-medium networks with a predictable structure. If your infrastructure has fewer than 50 devices and you keep an up-to-date inventory file, a Bash script is quick to write and easy to maintain. It's also useful in CI/CD pipelines where you want to regenerate a diagram every time someone pushes a change to your network-as-code repository.

For larger or more dynamic environments think auto-scaling cloud topologies with hundreds of nodes a Python-based generator with libraries like networkx and pydot gives you more flexibility. You can explore that approach in this guide to building a Python network topology diagram generator. But for straightforward, repeatable documentation tasks, Bash gets the job done with minimal dependencies.

How do you build the script step by step?

Step 1: Prepare your network inventory

Start with a simple CSV or text file that lists your devices and their connections. A minimal format might look like this:

Router1,Switch1,eth0
Switch1,Server1,eth2
Switch1,Server2,eth3
Router1,Firewall1,eth1

Each line represents a link: DeviceA,DeviceB,Interface. You can generate this file manually, pull it from a CMDB, or scrape it from device configurations.

Step 2: Write the DOT generation logic

The Bash script reads each line and writes it into DOT syntax. A basic approach uses a while read loop:

#!/bin/bash
echo "digraph network {" > network.dot
echo " rankdir=LR;" >> network.dot
while IFS=',' read -r src dst iface; do
  echo " \"$src\" -> \"$dst\" [label=\"$iface\"];" >> network.dot
done < inventory.csv
echo "}" >> network.dot

This produces a valid DOT file. The rankdir=LR directive lays out the graph left-to-right, which usually reads better for network topologies. You can adjust this to TB (top-to-bottom) depending on your layout preference.

Step 3: Render the diagram

Run Graphviz to convert the DOT file into an image:

dot -Tpng network.dot -o network.png

If you need SVG output for web embedding or scalable PDFs for printing, just swap the flag: -Tsvg or -Tpdf.

Step 4: Add device styling

Raw Graphviz output looks plain. You can add shapes and colors directly in the script to distinguish device types. For example, assign rectangles to routers, switches as boxes with a different fill color, and servers as ellipses. Add these declarations inside the loop based on device naming conventions or a lookup table in your inventory.

Understanding the underlying syntax helps here. If you want a deeper look at how DOT and other scripting languages describe diagram structures, check out this reference on network diagram scripting language syntax.

What are common mistakes people make?

  • Hardcoding device names. Embedding specific hostnames directly in the script means you rewrite it every time the network changes. Always read from an external file.
  • Not quoting node names. Device names with hyphens or dots (like core-sw-01.building.local) break the DOT parser if they aren't wrapped in quotes.
  • Skipping error handling. If the inventory file is missing or malformed, the script silently produces an empty or broken diagram. Add a check that the input file exists and has content before processing.
  • Overcomplicating the first version. Start with a flat list of connections. Get the basic diagram working. Then layer in styling, subgraph clusters for VLANs or sites, and conditional formatting.
  • Ignoring output format needs. PNG works for quick emails, but SVG is better for wikis and documentation portals. Pick the right format for your audience.

How can you group devices by location or function?

Graphviz supports subgraphs, which let you cluster related nodes visually. In your Bash script, you can generate subgraph blocks by grouping devices that share a site code or role prefix:

echo " subgraph cluster_dc1 {" >> network.dot
echo " label=\"Data Center 1\";" >> network.dot
echo " style=dashed;" >> network.dot
echo " \"core-sw-01\";" >> network.dot
echo " \"dist-sw-01\";" >> network.dot
echo " }" >> network.dot

Nodes whose names match a pattern (like starting with dc1-) get placed inside the cluster automatically. This makes the diagram much easier to read for multi-site environments.

Can you integrate this into a CI/CD pipeline?

Yes, and this is where the approach really pays off. Store your inventory file in Git alongside the Bash script. Add a pipeline step that runs the script and commits the updated diagram image back to the repository. Every time someone modifies the network configuration or inventory, the diagram regenerates automatically.

In a GitLab CI or GitHub Actions setup, the step is straightforward: install Graphviz in the runner, execute the script, and use git to push the new artifact. The diagram stays current without anyone opening a drawing tool.

What about labeling interfaces and link speeds?

Extend your inventory format to include extra columns interface name, bandwidth, link status and pass those as DOT edge attributes:

echo " \"$src\" -> \"$dst\" [label=\"$iface\\n$speed\", fontsize=10];" >> network.dot

This adds context directly on the diagram. Engineers can see at a glance which links are 10Gbps, which are 1Gbps, and which interfaces connect where, without cross-referencing a spreadsheet.

Practical checklist before you start

  1. Create or export your network inventory as a CSV with at least source, destination, and interface columns.
  2. Install Graphviz on your system: sudo apt install graphviz or brew install graphviz.
  3. Write the Bash script to read the CSV and output a valid DOT file.
  4. Render the DOT file to your preferred image format.
  5. Add device-type styling and subgraph clusters for readability.
  6. Test with a small subset of devices before running against your full inventory.
  7. Store the script and inventory in version control for traceability.
  8. Set up a pipeline job to regenerate the diagram on every inventory change.

Next step: Pick five devices from your network, write their connections in CSV format, and run through the script above. You'll have a working diagram in under 15 minutes. From there, expand the inventory, add styling, and wire it into your automation workflow.