Using Graphviz to generate automated system diagrams

If you have created an architecture diagram of your system environment, you probably realize that these manually created diagrams are usually out-of-date the day after you create them. This article explains the basics of the Graphviz application and how you can write scripts that can automate the creation of diagrams so that you always have up-to-date and correct diagrams of your systems. Example scripts are provided that diagram the N-Port ID Virtualization (NPIV) and virtual Small Computer System Interface (VSCSI) configurations of an IBM® POWER® processor-based server.

Share:

Brian K. Smith (ixbrian@gmail.com), System Administrator, Intermountain Healthcare

Photo of Brian SmithWhen this article was written, Brian Smith was a UNIX System Administrator for Intermountain Healthcare in Salt Lake City, Utah. You can follow him on his developerWorks blog.



27 September 2012

Also available in Chinese

Introduction

A picture is worth a thousand words, and this is particularly true in regard to complex computer systems. As system environments become more complex, the importance of diagramming them and documenting them becomes even more important. For example, virtualization technologies have many benefits; however, they generally make the environment more complex and more difficult to understand. Graphviz is a flexible application that can create diagrams and is easily scriptable. This article covers the basics of the Graphviz DOT language and provides example scripts that can be used to diagram the Virtual I/O Server (VIOS) NPIV and VIOS VSCSI architectures of an IBM POWER processor-based server. This article helps you understand the basics of Graphviz and how to start writing scripts to automate creating diagrams.


Obtaining Graphviz

Graphviz is an open source tool that runs on most platforms similar to UNIX® and also on Microsoft® Windows®. Binaries for most platforms are available from the Graphviz home page. AIX binaries are available at perzl.org.

There are multiple tools available in the Graphviz application to produce different types of diagrams (dot, neato, circo, twopi, and so on.) This article focuses on the dot tool which produces hierarchical diagrams.


Basics of the DOT language

After installing Graphviz, you can start creating the diagrams with the tool by creating a DOT file. The DOT file is a text file that describes the elements of a diagram and their relationship so that the tool can produce a graphical representation of this.

Listing 1 shows a very basic DOT file.

Listing 1. Basic DOT file (example1.dot)
graph example1 {
Server1 -- Server2
Server2 -- Server3
Server3 -- Server1
}

There are three nodes in Listing 1 (Server1, Server2, and Server3). The -- defines a connection between the nodes. This example, in the DOT language, is describing that Server1 is connected to Server2, Server2 is connected to Server3, and Server3 is connected to Server1.

After the DOT file has been created, a diagram can be produced by running the dot command as shown in Listing 2. The Tpng specifies that the output format should be PNG and the –o example1.png specifies that the output must be saved to a file named, example1.png.

Listing 2. Generating an image from the DOT file

$ dot example1.dot –Tpng –o example1.png

The image produced by the DOT file in listing 1 is shown in Figure 1.

Figure 1. Diagram produced from example1.dot
Diagram produced from example1.dot

The first example (example1.dot) described an undirected graph, which is a graph that shows connections between nodes without arrows on the lines.

A directed graph shows more than just a connection between nodes; it also shows an arrow on the lines between the nodes which might represent the direction of the flow between nodes. To create a directed graph, specify digraph rather than graph on the first line of your DOT file, and use -> between nodes rather than --.

Listing 3 and Figure 2 show the DOT file and graph, respectively, of a directed graph.

Listing 3. Directed DOT file (example2.dot)
digraph example2 {
Server1 -> Server2
Server2 -> Server3
Server3 -> Server1
}
Figure 2. Directed graph diagram produced from example2.dot
Directed graph diagram produced from example2.dot

You can also easily control the shape, color, and label of each node in your graph. This is done by listing each node name, followed by brackets containing the options. For example, the line Server1[shape=box,label="Server1\nWebServer",fillcolor="#ABACBA",style=filled]defines that the Server1 node should have a box shape, have a label of Server1\nWeb Server (the \n represents a new line), have the color set to the hexadecimal (hex) color #ABACBA, and the color should fill the node.

Building upon the previous examples, Listing 4 and Figure 3 show how to define these extra attributes on the diagram.

Listing 4. Diagram with additional attributes (example3.dot)
digraph example3 {
Server1 -> Server2
Server2 -> Server3
Server3 -> Server1

Server1 [shape=box, label="Server1\nWeb Server", fillcolor="#ABACBA", style=filled]
Server2 [shape=triangle, label="Server2\nApp Server", fillcolor="#DDBCBC", style=filled]
Server3 [shape=circle, label="Server3\nDatabase Server", fillcolor="#FFAA22",style=filled]
}
Figure 3. Graph of additional attributes produced from example3.dot
Graph of additional attributes produced from example3.dot

Writing scripts to create Graphviz diagrams

Now that you understand the basics of the Graphviz DOT language, you can start creating scripts to dynamically create a DOT file. This allows you to dynamically create diagrams that are always accurate and up-to-date.

The first example in Listing 5 is a bash shell script that connects to a Hardware Management Console (HMC) and gathers information about the managed servers and logical partitions (LPARs) and creates a DOT output with this information.

Listing 5. hmc_to_dot.sh
#!/bin/bash

HMC="$1"

serverlist=`ssh -q -o "BatchMode yes" $HMC lssyscfg -r sys -F "name" | sort`

echo "graph hmc_graph{"

for server in $serverlist; do
    echo " \"$HMC\" -- \"$server\" "
    lparlist=`ssh -q -o "BatchMode yes" $HMC lssyscfg -m $server -r lpar -F "name" | sort`
    for lpar in $lparlist; do
             echo "    \"$server\" -- \"$lpar\" "
    done
done

echo "}"

The script is run by providing an HMC server name as an argument to the script. The script sets the first parameter passed as the $HMC variable. The $serverlist variable is set by connecting to the HMC and getting a list of all the managed servers under that HMC’s control. These managed servers are looped through, and for each one, the script prints a line of "HMC" -- "server" which instructs Graphviz to draw a line between each HMC and its managed servers. Also, for each managed server, the script connects to the HMC again and gets a list of LPARs on that managed system, then loop through them printing a line of "server" -- "LPAR".This instructs Graphviz to draw a line between each managed server and its LPARs.

This script requires that you have Secure Shell (SSH) key authentication setup between the server on which you are running the script and your HMC.

Listing 6 shows the output of the script.

Listing 6. “./hmc_to_dot.sh hmc_name” output
graph hmc_graph{
 "hmc01" -- "test520"
    "test520" -- "lpar2"
    "test520" -- "lpar3"
 "hmc01" -- "test570"
    "test570" -- "aixtest01"
    "test570" -- "aixtest02"
    "test570" -- "aixtest03"
 "hmc01" -- "test510"
    "test510" -- "lpar1"
}

You can easily generate the graph from the script by running the following command: ./hmc_to_dot.shhmc_server_name|dot-Tpng-ohmc_graph.png

This runs the script that dynamically creates the DOT language and then pipes this output to the dot command which in turn creates the diagram as a file named, hmc_graph.png. Figure 4 shows the diagram created.

Figure 4. Diagram created from the hmc_to_dot.sh script
Diagram created from the hmc_to_dot.sh script

More complex scripts

The following two scripts show some of the possibilities of using scripts to dynamically create diagrams. Both of these are Perl scripts and their output can be piped to the dot command to generate the diagrams.

These two scripts require that you have the SSH key authentication setup between the server on which you are running the script and your HMC. The scripts are designed to work with the systems that have a single VIOS or dual Virtual I/O Servers, and depending on your environment, they might need to be tweaked.

The first script gathers information from the HMC and Virtual I/O Servers in order to dynamically create a diagram of the NPIV architecture in an IBM PowerVM® environment. This NPIV architecture diagram makes it very easy to see how physical host bus adapters (HBAs) are mapped through to virtual HBAs and LPARs. This script is run with the HMC name as the first parameter and the managed system name as the second parameter.

Scripts such as these can be run through cron daily so that you have self-documenting diagrams that are accurate and up-to-date.

Listing 7. vio_npiv_info.pl – Creating the NPIV diagram
 Download :- vio_npiv_info.pl
Figure 5. Diagram created from vio_npiv_info.pl
Diagram created from vio_npiv_info.pl

The final example script gathers information from the HMC and Virtual I/O Servers and produces a diagram of the VSCSI adapter mappings in a PowerVM environment. This script is run with the HMC name as the first parameter and the managed system name as the second parameter.

Listing 8. vio_vscsi_info.pl – Creating the VSCSI diagram
Download :- vio_vscsi_info.pl
Figure 6. Diagram created from vio_vscsi_info.pl
Diagram created from vio_vscsi_info.pl

Click to see larger image

Figure 6. Diagram created from vio_vscsi_info.pl

Diagram created from vio_vscsi_info.pl

Conclusion

With today’s dynamic environment of virtualization, systems are constantly changing and it is difficult to manually keep documentation and diagrams up-to-date and accurate. This article has presented the basics of Graphviz and how to write scripts that harness the power of Graphviz to create up-to-date, accurate, and automated diagrams of your environment. You can run these scripts from cron and place the diagrams on a web server so that your diagrams are re-created as often as you would require and are easily accessible through a web browser.


Resources

The Graphviz website has excellent documentation and you can download Graphviz for most platforms from here.

The perzl.org website has AIX binaries of Graphviz available.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX
ArticleID=837337
ArticleTitle=Using Graphviz to generate automated system diagrams
publish-date=09272012