2.7.4. Network Diagram

sphinxcontrib-nwdiag is a Sphinx extension for embedding network diagrams. You can embed network diagrams with the .. nwdiag::, .. rackdiag:: and .. packetdiag:: directives.

PyPI Package

https://pypi.org/project/sphinxcontrib-nwdiag/

Documentation

http://blockdiag.com/en/nwdiag/sphinxcontrib.html

Git Repository

https://github.com/blockdiag/sphinxcontrib-nwdiag

Sphinx extension for embedding network diagrams using nwdiag.

Features

  1. Generate network-diagram from dot like text (basic feature).

  2. Multilingualism for node-label (utf-8 only).

Directive Body Diagram

.. nwdiag::

For more details, see sphinxcontrib-nwdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. nwdiag::
   :align: center
   :scale: 75

   nwdiag {
       network dmz {
           web01;
           web02;
       }
   }
Which gives
blockdiag dmz web01 web02

Description Table

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
.. nwdiag::
   :align: center
   :scale: 75
   :desctable:

   nwdiag {
       network dmz {
           web01 [address = "192.168.0.1", description = "web server01"];
           web02 [address = "192.168.0.2", description = "web server02"];
       }
       network internal {
           web01 [address = "172.0.0.1"];
           db01 [address = "172.0.0.2,172.0.0.20", description = "database server"];
       }
   }

which gives
blockdiag dmz internal 192.168.0.1 172.0.0.1 web01 192.168.0.2 web02 172.0.0.2 172.0.0.20 db01

Name

Description

web01

web server01

web02

web server02

db01

database server

Include Diagram

Network

the example
1
2
3
4
5
.. nwdiag:: nwdiag/example.diag
   :caption: Peer networks and grouping nodes (Network Diagram example)
   :align: center
   :scale: 75
   :width: 480
which gives
blockdiag front 192.168.0.0/24 inet router web01 web02

Figure 2.49 Peer networks and grouping nodes (Network Diagram example)

which needs

The example above comes from the original Sample diagrams: nwdiag web page and processed the following file content:

Listing 2.8 Network Diagram example file (nwdiag/example.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
nwdiag {
    inet [shape = cloud];
    inet -- router;

    network front {
        address = "192.168.0.0/24";
        router;
        web01;
        web02;

        // define network using defined nodes
        group db {
            web01;
            web02;
        }
    }
}

Rack

.. rack::

For more details, see sphinxcontrib-nwdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
1
2
3
4
.. rackdiag:: rackdiag/example.diag
   :caption: Multiple racks with multiple and blocked units (Rack Diagram example)
   :align: center
   :height: 480
Which gives
blockdiag 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 1 2 3 4 5 6 7 8 9 10 11 12 1 2 3 4 5 6 7 8 9 10 11 12 UPS [2U] DB Server Web Server 1 Web Server 2 Web Server 3 Web Server 4 Load Balancer L3 Switch UPS [2U] DB Server Web Server Web Server Web Server Load Balancer L3 Switch Server Server Server Server N/A [8U]

Figure 2.50 Multiple racks with multiple and blocked units (Rack Diagram example)

Which needs

The example above comes from the original Sample diagrams: rackdiag web page and processed the following file content:

Listing 2.9 Rack Diagram example file (rackdiag/example.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
rackdiag {
    default_fontsize = 10;

    // define 1st (height) rack
    rack {
        16U;

        // define rack items
        1: UPS [2U, fontsize = 14];
        3: DB Server;
        // put 2 units to rack-level 4
        4: Web\nServer 1;
        4: Web\nServer 2;
        5: Web\nServer 3;
        5: Web\nServer 4;
        7: Load Balancer;
        8: L3 Switch;
    }

    // define 2nd rack
    rack {
        12U;

        // define rack items
        1: UPS [2U, fontsize = 14];
        3: DB Server;
        4: Web Server;
        5: Web Server;
        6: Web Server;
        7: Load Balancer;
        8: L3 Switch;
    }

    // define 3rd rack (with not available units)
    rack {
        12U;

        1: Server;
        2: Server;
        3: Server;
        4: Server;
        5: N/A [8U, fontsize = 14];
    }
}

Packet

.. packet::

For more details, see sphinxcontrib-nwdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
1
2
3
4
.. packetdiag:: packetdiag/example.diag
   :caption: Structure of TCP Header (Packet Diagram example)
   :align: center
   :width: 480
Which gives
blockdiag 0 16 32 Source Port Destination Port Sequence Number Acknowledgment Number Data Offset Reserved URG ACK PSH RST SYN FIN Window Checksum Urgent Pointer (Options and Padding) Data

Figure 2.51 Structure of TCP Header (Packet Diagram example)

Which needs

The example above comes from the original Sample diagrams: packetdiag web page and processed the following file content:

Listing 2.10 Packet Diagram example file (packetdiag/example.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
packetdiag {
    colwidth = 32;
    node_height = 40;
    default_fontsize = 12;

    0-15: Source Port;
    16-31: Destination Port;
    32-63: Sequence Number;
    64-95: Acknowledgment Number;
    96-99: Data\nOffset;
    100-105: Reserved;
    106: URG [rotate = 270];
    107: ACK [rotate = 270];
    108: PSH [rotate = 270];
    109: RST [rotate = 270];
    110: SYN [rotate = 270];
    111: FIN [rotate = 270];
    112-127: Window;
    128-143: Checksum;
    144-159: Urgent Pointer;
    160-191: (Options and Padding);
    192-223: Data [colheight = 3];
}