New diagram type: network topology

[cristeab]

Is your feature request related to a problem? Please describe. I need to create simple network topologies for testing frameworks involving multiple VMs and switches.

Describe the solution you'd like Simple diagrams showing network connections between the VMs and switches, see this link for some samples: https://github.com/Azure/sonic-mgmt/blob/master/ansible/doc/README.testbed.Topology.md

Describe alternatives you've considered Alternatives for this approach are editing by hand using any image editor that supports drawing rectangles and lines.

[azawawi]

@cristeab Do you have more ideas/examples for this one? I am willing to help out as I need this one as well.

[gildasio]

It would be so nice!!

@azawawi I think that something similar to flowchart as a notation like this:

graph TD;
    Router---Switch1;
    Router---Switch2;
    Switch1---Server;
    Switch2---Server;

Generate something like this:

This image above I created with LibreOffice and VRT extension.

[andrejpk]

It would be useful for cloud situations to allow including some network context (e.g. VNet/VPC). This could be done with indentation like how State diagrams show nexted states.

Also including IP addresses and other metadata is important for some situations. Markup/notes would also be important it some diagrams.

[andrejpk]

networkDiagram
    network: vpc1
        node router
            type router
            meta ip=192.138.33.1
        node switch1
            type switch
            meta model=hp1234
        node switch2
            type switch
            meta model=cisco4321
            meta ip=192.168.33.2
        node server
            type server
           meta os=linux
        router---switch1
        router---switch2
        switch2---server: primary
        switch1---server: secondary

[cristeab]

@azawawi I am thinking at something more detailed, like showing how the physical ports of each switch / network device are connected:

networkDiagram link: startDevice: str-msn2700-01 startPort: Ethernet0 endDevice: str-7260-10 endPort: Ethernet1 bandwidth: 40000 vlanId: 1681 vlanMode: access link: startDevice: str-7260-11 startPort: Ethernet30 endDevice: str-7260-10 endPort: Ethernet64 bandwidth: 40000 vlanId: 1681-1712 vlanMode: trunk

This is very useful to represent graphically a testbed network topology when developing/testing software for switches: https://github.com/Azure/sonic-mgmt/blob/master/ansible/files/sonic_lab_links.csv

[andrejpk]

I think it would better to let the user add arbitrary name/value details instead of trying to think of and standardize every kind of metadata.

Maybe have two ways to define meta; a short line-liner or a list of name=value pairs:

networkDiagram
    network: vpc1
        node router
            type router
            meta ip=192.138.33.1
        node switch1
            type switch
            meta model=hp1234
        node switch2
            type switch
            meta:
                model=cisco4321
                ip=192.168.33.2
        node server
            type server
            meta os=linux
        router---switch1
        router---switch2
        switch2---server: primary
        switch1---server: secondary

[jgreywolf]

Can someone provide another example of how something like this would look? I am not seeing how the examples shared in the first post are different than using flowchart, kind of like:...

Actually, forget that part. I tried to do this using flowcharts, both with and without a subgraph, and while it sort of worked, it did not look very nice

[jgreywolf]

Sorry - wrong button

[meshula]

In case it gives you ideas, I wrote this for my own use - https://github.com/meshula/Wires - it's got an extensive vocabulary and rule set for parsing graphs and attributes, documented in the readme. Here's some samples:

#define TEST1 "\
trivial ---> trivial2 \n\
foo ------->bar"

#define TEST2 "\
trivial ---+                  \n\
           |                  \n\
           )                  \n\
           +---->   trivial2"

#define TEST3 "          \n\
foo -------+             \n\
trivial1 --)-->trivial2  \n\
           +->     bar   "

#define TEST4 "\
sample0 ---------+                 \n\
sample1 -----+   |                 \n\
sample2 -----)---)----->output2    \n\
             +---)----->output1    \n\
                 |                 \n\
                 +--->output0     "

#define TEST5 "\
sample --+                                                                                           \n\
         +-> bassFilter ---> bassGain --------+                                                      \n\
         +-> midFilter ----> midGain ---------+                                                      \n\
         +-> trebleFilter ----> trebleGain ---+---> gain -+---> recorder ------+                     \n\
                                                          +---> monitor  ------+---> oscilloscope    \n\
                                                          +---> analyser                             \n\
                                                          +---> audiocontext                         "

#define TEST6 "\
[buffer:sample] ----------+                                                                                           \n\
  file:'human-voice.mp4'  |                                                                                             \n\
                          +-> [filter:bassFilter] ---> [gain:bassGain] --------+                                        \n\
                          |        type:'lowpass'          gain:2.0            |                                        \n\
                          |   frequency:160                                    |                                        \n\
                          |           q:1.2                                    |                                        \n\
                          +-> [filter:midFilter] ----> [gain:midGain] ---------+                                        \n\
                          |        type:'bandpass'          gain:4.0           |                                        \n\
                          |   frequency:500                                    |                                        \n\
                          |           q:1.2                                    |                                        \n\
                          +-> [filter:trebleFilter] ----> [gain:trebleGain] ---+---> gain -----+---> recorder           \n\
                                type:'highpass'            gain:3.0                  gain:1.0  +---> monitor            \n\
                           frequency:2000                                                      +---> oscilloscope       \n\
                                   q:1.2                                                       +---> analyser           \n\
                                                                                               +---> audiocontext         "

[mvandermade]

So you just want to put a picture/icon instead of a box ?

Tip: You could also use fontawesome icons and shapes:

https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggVERcbiAgQiAtLT4gQ3tMZXQgbWUgdGhpbmt9XG4gIEMgLS0-fE9uZXwgRFtMYXB0b3BdXG4gIEMgLS0-fFR3b3wgRVtpUGhvbmVdXG4gIEMgLS0-fFRocmVlfCBGWyhmYTpmYS1kYXRhYmFzZSBEYXRhYmFzZSldXG5cdFx0IiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0

[jgroom33]

806

[jgroom33]

@azawawi

There are a few libraries that do something similar. They seem to be standardizing on cloud provider icon sets.

This one seems to be the closest to the design goals of mermaid: https://diagrams.mingrammer.com/docs/getting-started/examples

This one provides the greatest flexibility, but is more complex: http://go.drawthe.net/

[azawawi]

Sample PlantUML nwdiag-based previous work with syntax:

https://plantuml.com/nwdiag

[luiscachog]

+1 on this idea.

[butterflyx]

Also +1 from me for this idea.

andrejpk nailed it for me with this kind of syntax:

networkDiagram
    network: vpc1
        node router
            type router
            meta ip=192.138.33.1
        node switch1
            type switch
            meta model=hp1234
        node switch2
            type switch
            meta:
                model=cisco4321
                ip=192.168.33.2
        node server
            type server
            meta os=linux
        router---switch1
        router---switch2
        switch2---server: primary
        switch1---server: secondary

@mvandermade : yes, fontawesome might help, but it will never be the same beauty as in the example image gildasio provided

[scotho3]

I commented on #1527 for the same issue - this is exclusively what I use mermaid for - making network documentation, but I have to leave out some connections and draw them by hand (still faster than vizio).

The amount of automated diagrams I could draw with this!

[xeor]

What would be the best way to create network-diagrams while we wait for this? Something that also contains meta-info like ip-addresses and ip/port info..

[jgroom33]

@xeor I've settled on using drawio. There's a plug-in for vscode. The files can be saved as foo.drawio.svg or foo.drawio.png and rendered in markdown.

[go2null]

really need this for drawing a multi-interface server -> example, on a back-channel and front-channel.

[krkn-s]

Hello, I just discovered this open source tool that allows you to make network diagrams from a YAML : http://go.drawthe.net

Hopefully it meets your needs until MermaidJS is able to make network diagrams too.

[justyn]

I would just add to the syntax discussion that it would ideally be possible to label an IP address per connection line in nodes that have multiple interfaces (routers etc).

I think there are basically two ways per-interface IP address can be added visually:

1) Label within the node at the point the connection line meets the node 2) Use two labels per connection line - one at each end, indicating the IP of the node at that end.

A random example from the internet of the first approach, in the central node:

[aronchick]

One thing to add to the great discussion here - is there the ability to have icons attached to nodes? The networking logos are quite good, and having a simple way to swap out a default node picture for a URL would be great

[andrejpk]

One thing to add to the great discussion here - is there the ability to have icons attached to nodes? The networking logos are quite good, and having a simple way to swap out a default node picture for a URL would be great

Agree... a URL or relative file reference

[xu4wang]

Looks good. thanks for sharing the tips.

How shall I use an icon with two fa classes. for example:

So you just want to put a picture/icon instead of a box ?

Tip: You could also use fontawesome icons and shapes:

https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggVERcbiAgQiAtLT4gQ3tMZXQgbWUgdGhpbmt9XG4gIEMgLS0-fE9uZXwgRFtMYXB0b3BdXG4gIEMgLS0-fFR3b3wgRVtpUGhvbmVdXG4gIEMgLS0-fFRocmVlfCBGWyhmYTpmYS1kYXRhYmFzZSBEYXRhYmFzZSldXG5cdFx0IiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0

[rgonzalez028]

from https://community.home-assistant.io/t/live-network-diagram-influxdb-grafana-mermaid/100956 I cleaned the text a bit and here's a more elaborate example:

https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqFlGFr2zAQhv-K0KeW1Y6kkLUNobAloRTSEuIwBvM-yJbWiNmykOWVkuS_75zEdhx76weB7nzvq3tORlscZ0LiMX613GzQehZqlCj9O3DviURC_uJF4pDSTlqTJdxJFPFc5VD1xjX9MYll-elhFiwQJWRACXqOJpF9KBclPuRgMZ9OBqfKn57n2ayA7bYSz8WrXB1S3vczLSP-kJwp93CoMldXlawse1pWgrrs-trzTyeAQOi8rZi9BB9IAIzVYIv1HI3IgLW47gHo851Pe7HA4biBzA74n6MdN7Xfau19mVJGSAd02Hi1LR6jnYlrhuW0O6J70qB0tPmbcvGmbmC98IJHSkbzjg1rNZAX0fGXsFJQiLmBGcU8pXUnU55Ky7vd3NJWN5WQfSxkXaHZZFo28GXUw99zorK16mnVldy1Rya1uGBmZXwYXXOPRjX0q6VCw69d41Hb-MyivEfFLgw-9TjQfzkcmtB_GrKXbz1ot__rIOHGZaY2WBzCnomyy_HgGwy3lnIl4LHYQg6F2G1kKkM8hu3ppQhxqPdQWhgBb8VcKJdZPHa2kDeYFy4L3nVcxceameIw8_SY3P8F0FRzsw

Code:

graph TD
 linkStyle default interpolate basis
 wan1[<center>DSL 100/10 Mb<br><br>10.100.102.1</center>]---router{<center>EdgeRouter-X<br><br>10.20.30.1</center>}
 ip((<center><br>IP<br><br></center>))-.-router
 dns((<center><br>DNS<br><br></center>))-.-router
 wan2[<center>LTE 50/20 Mb<br><br>192.168.1.1</center>]---router
 router---|100Mb|ap[<center>RT-AC1200<br><br>10.20.30.3</center>]
 router---|1Gb|pc(<center>PC<br><br>10.20.30.190</center>)
 router---|1Gb|switch[<center>TL-SG105E<br><br>10.20.30.2</center>]
 subgraph red1
 ap-.-cam1(<center>Camera<br><br>10.20.30.171</center>)
 ap-.-cam2(<center>Camera<br><br>10.20.30.172</center>)
 ap-.-phone(<center>Phone<br><br>10.20.30.191</center>)
 ap-.-ir(<center>IR<br><br>10.20.30.180</center>)
 end
 subgraph red2
 switch---|100Mb|pi1(<center>RPi 3B<br><br>10.20.30.150</center>)
 switch---|1Gb|pi2(<center>RPi 3B+<br><br>10.20.30.151</center>)
 switch---|100Mb|nvr(<center>NVR<br><br>10.20.30.170</center>)
 switch---|1Gb|laptop(<center>Laptop<br><br>10.20.30.192</center>)
 end

This is the rendered chart:

[kriskeillor]

This is a great discussion.

I really appreciate you linking those other resources @jgroom33 (diagrams.mingrammer, drawthenet). As well as the relevant issues linked and the other feature ideas (might be worth opening a new issue). Somewhere in the rabbit hole this LibreOffice IT art pack was shared, which is quite stellar actually.

I think its important to remember that network topologies are meant to describe networks. Mermaid does this visually. NetJSON describes the actual features of a network, such as "network configuration of devices, monitoring data, routing information, and network topology". However, NetJSON has pretty weak visualization tools. Their docs link to openwisp-network-topology as one implementation, but personally I don't really like the organic layout and it's really lacking the crispness of mermaid and other examples shared here (@justyn's is particularly good, and IP addressing individual connections is another awesome feature). I would prefer a non- or semi-hierarchical layout as others discussed. There's also netjsongraph.js which seems decent although (a) the site hosting the examples, nodeshot.org, is down (apparently just for me) and (b) it also seems to be organic-only, and I don't see those fancy router/switch/PC/etc. symbols we all know and love.

But back to my point, it seems the best tool to define networks is the well-established NetJSON, and Mermaid should be used to visually describe them. After all it's a diagramming tool, not a mapping tool. A utility to process NetJSON into Mermaid would be really useful. It would still require the new diagram type as described here, in #806 , #867, #1527, etc.

edit: Additional NetJSON visualizers, would be great to see Mermaid (or a Mermaid utility, rather) on this list one day.

---

For fun, I've attached a network topology design (pdf) I made in Mermaid. I'm happy with it but there are a lot of issues.

1. It doesn't look anything like a standard IT diagram, reducing perceived professionalism and ease of comprehension.
2. The actual network topology is intermixed with visual data in the source.
3. Sometimes the visualization 'breaks'. Not talking about a bug, its just ordered in a way I don't like and I feel forced to redefine the topology to create an easy-to-follow visual. In some ways I think this is beneficial, because it forces me to reconsider decisions and often the prettier topology seems the more effective. But sometimes it's just a weird mermaid hiccup.

I plan to transition to NetJSON to describe this network as it, and the level of detail required, grow. I'll keep everyone posted on visualization efforts.

[go2null]

related: https://github.com/mermaid-js/mermaid/issues/1652 "Labels on edge connections"

[CWempe]

I want to support @justyn regarding the need to define ip addresses to interfaces rather than devices. There should even be a way to lable an interface (e.g. eth0, Fa0/12 Ethernet 1).

like this:

[giosueDelgado]

I'm interested also

[AkechiShiro]

Could you please refrain from putting comments on interest and please react to already existing comments @giosueDelgado, you're notifying everyone about something, that doesn't make this issue move in any way forward.

Btw, I'm interested to work on this if possible, any new progress @kriskeillor ? Was any of the work you discussed done ? Or is being still worked on ? If so where, is there any PRs? Draft PRs ? Forks ?

[Matthieu-LAURENT39]

I would also be interested on working on this, network diagrams are my main use-case for mermaid and i'd love to help implement this feature

[kriskeillor]

@AkechiShiro I developed the network diagram simultaneously in Mermaid and EPlan. Afaik the EPlan diagram was utilized, but I am no longer on the project.

To be honest, I don't think Mermaid was a good choice for developing the network diagram. I was more or less reinventing the wheel and when I presented the effort, it was actually laughed at. Fortunately the EPlan diagram was better received.

There are lots of problems with using Mermaid as a network diagramming tool:

• It's not an industry standard, so interoperability is low or nonexistent
  • You can't take advantage of any tools like simulation or import/export, unlike some of the other tools I mentioned in my first post
• You can't fully control the placement or layout of items, which can obviously lead to some visualizations that are substandard or simply don't emphasize the information you want to emphasize
• There isn't dedicated software for Mermaid network diagrams which could speed up work with automation or macros
  • For my design, I had five sub-networks which were essentially duplicates of each other, but all changes had to be made individually to each

If you use markdown/mermaid for your typical word processing, throwing some small conceptual network diagrams in with Mermaid is easy and convenient - but to actually develop full-scale networks and define connections, addresses, technical specs, etc. I don't think mermaid (or any markdown tool) packs enough punch.

[AkechiShiro]

Thanks for your detailed answer @kriskeillor, however EPlan is a proprietary software and is not freely available right ? If it was, I could have given it a try easily but still thanks for your recommendation, I wasn't aware of EPlan as a diagram software.

[kriskeillor]

Correct @AkechiShiro, it is paid software (and expensive to boot). It's also geared towards electrical diagrams (building systems, automation, process engineering, etc.) not specifically intended for IT infrastructure - although it can be massaged to fit.

Perhaps NetJSON would better fit your needs?

[bktycrg]

https://kubernetes.io/docs/contribute/style/diagram-guide/

Parsed and supported natively within Mermaid as-is (using it within Obsidian myself). Would be worth looking up common representations and annotations for (just spitballing here):

a DEVICE, which has zero or more INTERFACES an INTERFACE, which is assigned an address on a NETWORK a NETWORK, which is a pool of addresses and related settings a SWITCH, which is a common connector within a given NETWORK a ROUTER, which is a DEVICE that exists at the boundaries of one or more NETWORKS

[bktycrg]

Minor update: ended up going with Terraform-moderated k8s which (though this wasn't the deciding factor) made automated graphing from static IAC trivial: https://github.com/pcasteran/terraform-graph-beautifier

[ppenguin]

Just skimmed this after trying to visualise my own network topology pre-overhaul in Mermaid. Actually I'm transitioning from PlantUML because I find Mermaid more intuitive and visually pleasing.

Nevertheless I think @azawawi 's pointer appears to be very on-point as an example what would be needed:

Sample PlantUML nwdiag-based previous work with syntax:

https://plantuml.com/nwdiag

And in fact @andrejpk 's suggestion would conceptually come very close to that from a DX POV.

If on top of that we would be inspired by NetJSON for the actual data structure, we could have the best of both worlds:

1. an intuitive, no-boilerplate, mermaid-native syntax for visualising network topology
2. straightforward translation possibility (by using a simple converter) from NetJSON to Mermaid

As we can see in @bktycrg 's kubernetes and in @rgonzalez028 's examples, Mermaid already supports (most of???) the necessary primitives, so with extensive use of subgraphs one could probably achieve the desired result already, but at too much effort. That is to say, the challenge of an additional network syntax would be mostly in parsing and less in rendering?

What I would additionally need for my current topic, is the easy addition of another "layer" within a "host-like" primitive, which is services and/or containers. I haven't seen this in NetJSON (but I only skimmed the spec), but in fact it's almost the same as a "subnet-hosts" hierarchy conceptually, so maybe it could be covered in a similar, generic way?

[TheBigBear]

I am confused, as some items here have been closed as done? Is there a way to do a network topology mermaid diagram now, or not? If, yes, where do find the required info on how to make one?

[bbrendon]

No. Check out d2lang. You can do some with that as long as you don’t go overboard

On Fri, May 3, 2024 at 03:10 TheBigBear @.***> wrote:

I am confused, as some items here have been closed as done? Is there a way to do a network topology mermaid diagram now, or not? If, yes, where do find the required info on how to make one?

— Reply to this email directly, view it on GitHub https://github.com/mermaid-js/mermaid/issues/1227#issuecomment-2092703173, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABQR2PN7BNMSTUFE3DLSXYDZANO7RAVCNFSM4KMSX22KU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMBZGI3TAMZRG4ZQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[natohutch]

bump

[MerzDaniel]

As Mermaid is natively supported by Github this would be a really nice feature

[lxwulf]

+1 from my side, would really appreciate this too.

[ergonap]

just wanted to say even today I was looking to make a network diagram, and would appreciate being able to do it in mermaid

[snooops]

I have to admit, without wanting anyone to quit mermaid - it has it's pro arguments, i like d2lang :)

[lxwulf]

@snooops when you explain to me how to create (pretty) network diagrams, I'm with you. 😊 I already tried it out and could do some diagrams in the direction of a network diagram, but it looked not that great. But maybe I missed something. 🤷‍♂️

[snooops]

@lxwulf Currently i switched from mermaid and even quit d2lang and trying this: https://playground.likec4.dev/w/tutorial/

[gonzaleztroyano]

+1

[neclimdul]

Just a reminder, every time you +1 comment you ping everyone who has ever commented or subscribed. Be polite, thumbs up and use the subscribe button. That's what its there for.