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

Todo

activate “Network Diagram” extension.

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:

   .. include:: nwdiag-directive-body-example.rsti

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:

   .. include:: nwdiag-description-table-example.rsti

Include Diagram

Network

the example
1
2
3
4
5
.. nwdiag:: nw.diag
   :caption: Peer networks and grouping nodes (Network Diagram example)
   :align: center
   :scale: 75
   :width: 640

:which gives:

   .. nwdiag:: nw.diag
      :caption: Peer networks and grouping nodes (Network Diagram example)
      :align: center
      :scale: 75
      :width: 640
which needs

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

Listing 2.5 Network Diagram example file (nw.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:: rack.diag
   :caption: Multiple racks with multiple and blocked units (Rack Diagram example)
   :align: center
   :height: 480

:which gives:

   .. rackdiag:: rack.diag
      :caption: Multiple racks with multiple and blocked units (Rack Diagram example)
      :align: center
      :height: 480
Which needs

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

Listing 2.6 Rack Diagram example file (rack.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:: packet.diag
   :caption: Structure of TCP Header (Packet Diagram example)
   :align: center
   :width: 640

:which gives:

   .. packetdiag:: packet.diag
      :caption: Structure of TCP Header (Packet Diagram example)
      :align: center
      :width: 640
Which needs

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

Listing 2.7 Packet Diagram example file (packet.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];
}