From ea4d90566eefbfe8d6286dbe6ccac9375e40ba71 Mon Sep 17 00:00:00 2001 From: Ivan Pepelnjak Date: Tue, 3 Sep 2024 17:50:41 +0200 Subject: [PATCH] Doc fix: explain the details of setting Graphviz/D2 output defaults --- docs/netlab/create.md | 3 ++- docs/netlab/graph.md | 1 + docs/outputs/d2.md | 21 +++++++++++++++------ docs/outputs/graph.md | 10 ++++++---- 4 files changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/netlab/create.md b/docs/netlab/create.md index ea8434d6a..45f923198 100644 --- a/docs/netlab/create.md +++ b/docs/netlab/create.md @@ -88,13 +88,14 @@ Without specifying the output format(s), **netlab create** creates a provider co You could specify one or more output formats with the `-o` CLI parameter. For more details please read the [output formats](../outputs/index.md) part of the documentation. +(netlab-create-set)= ## Setting Topology Parameters from Command Line The following CLI flags can be used to change individual topology parameters: * `-d` sets default device type (**defaults.device**) * `-p` sets virtualization provider (**provider**) -* `-s` uses `key=value` format to set specified topology element value. The key could be a hierarchical dotted name. +* `-s` uses the `key=value` format to set the specified topology element's value. The key could be a hierarchical dotted name. * `--plugin` specifies additional plugins not listed in lab topology or system defaults (example: multilab plugin) ### Example diff --git a/docs/netlab/graph.md b/docs/netlab/graph.md index db957c3a8..53ae5bf40 100644 --- a/docs/netlab/graph.md +++ b/docs/netlab/graph.md @@ -1,3 +1,4 @@ +(netlab-graph)= # Creating Physical or BGP Topology Graphs **netlab graph** command creates a graph description in [Graphviz](https://graphviz.org/) or [D2](https://d2lang.com/) format from the transformed lab topology data (usually stored in `netlab.snapshot.yml`) created by **netlab create** command. It's replicating the functionality of **netlab create -o graph:_name_** command with a more convenient user interface. diff --git a/docs/outputs/d2.md b/docs/outputs/d2.md index 8d6933a9d..f29c11ab1 100644 --- a/docs/outputs/d2.md +++ b/docs/outputs/d2.md @@ -15,16 +15,16 @@ The network topology graph description contains nodes and links but no placement ## Modifying Graph Attributes -Graphing routines use **default** topology settings to modify the node- or link parameters of the generated D2 file: +Graphing routines use **[default](defaults)** topology settings to modify the node- or link parameters of the generated D2 file: * **outputs.d2.interface_labels** (default: False) -- Add IP addresses to links in **topology** graph. Results in a cluttered image. * **outputs.d2.groups** (default: None) -- use the specified list of groups (or all groups when set to *True*) to create graph clusters * **outputs.d2.node_address_label** (default: True) -- add node loopback IP addresses or IP addresses of the first interface (for hosts) to node labels. * **outputs.d2.node_interfaces** (default: False) -- add list of interfaces and their IP addresses to nodes[^DG]. -* **outputs.d2.as_clusters** (default: True) -- use BGP autonomous systems to cluster nodes in topology graph. BGP AS clusters are always used in BGP graphs. +* **outputs.d2.as_clusters** (default: True) -- use BGP autonomous systems to cluster nodes in the topology graph. BGP AS clusters are always used in BGP graphs. * **outputs.d2.rr_sessions** (default: True) -- draw IBGP sessions between BGP route reflectors and clients as directional connections. -[^DG]: The results look disgusting. If you find a better way to get it done please submit a PR. Thank you! +[^DG]: The results look disgusting. If you find a better way to get it done, please submit a PR. Thank you! ## Modifying Shape and Connection Attributes @@ -66,12 +66,16 @@ ebgp: ## Specifying D2 Attributes -You could specify D2 attributes in your topology file, in per-user topology defaults, or in system defaults ([more details](../defaults.md)). You could also specify them with `-s` parameter of **netlab create** command ([more details](../netlab/create.md)). +You could specify D2 attributes in your [topology file](defaults-topology) (where you would have to prefix them with **defaults**), in [per-user topology defaults](defaults-user-file), or with [environment variables](defaults-env) (even [more details](../defaults.md)). You could also specify them with the `-s` parameter of the **[netlab create](netlab-create)** command, yet again prefixed with **defaults** ([more details](netlab-create-set)). -Use the `netlab create -o yaml:defaults.outputs.d2` to show the actual D2 defaults including topology file defaults and user defaults, for example: +Use the **netlab show defaults outputs.d2** [command](netlab-show-defaults) to show the current D2 defaults, including topology file defaults and user defaults, for example: ``` -$ netlab create -o yaml:defaults.outputs.d2 +% netlab show defaults outputs.d2 + +netlab default settings within the outputs.d2 subtree +===================================================== + as_clusters: true ebgp: source-arrowhead: @@ -94,10 +98,15 @@ lan: shape: rectangle style: border-radius: 8 + font-size: 20 node_address_label: true router: shape: oval + style: + font-size: 20 rr_sessions: true switch: shape: hexagon + style: + font-size: 20 ``` diff --git a/docs/outputs/graph.md b/docs/outputs/graph.md index 061f4d6b0..cd3bb68d8 100644 --- a/docs/outputs/graph.md +++ b/docs/outputs/graph.md @@ -4,16 +4,16 @@ **Note**: The network topology graph description contains nodes and links but no placement information. *graphviz* is pretty good at figuring out how to draw the required graph, but it pays out to test out various [layout engines](https://graphviz.org/docs/layouts/) (hint: use the name of the layout engine as the [CLI command](https://graphviz.org/doc/info/command.html)). -The *graph* output module is invoked by specifying `-o graph` parameter in **netlab create** command. It takes an optional destination file name (default: `graph.dot`). +The *graph* output module is invoked with the **[netlab graph](netlab-graph)** command or by specifying the `-o graph` parameter in the **netlab create** command. It takes an optional destination file name (default: `graph.dot`). A single formatting modifier can be used to specify the graph type: -* **topology** (default) -- Include, physical links, and multi-access- and stub subnets. When the network topology contains BGP information, the graph groups nodes into autonomous systems. Alternatively, you could set **defaults.outputs.graph.groups** attribute to use topology **[groups](../groups.md)** to group graph nodes. +* **topology** (default) -- Display inter-node links, multi-access- and stub subnets. When the network topology contains BGP information, the graph groups nodes into autonomous systems. Alternatively, you could set **defaults.outputs.graph.groups** attribute to use topology **[groups](../groups.md)** to group graph nodes. * **bgp** -- Include autonomous systems, nodes, and BGP sessions. With the **rr** option (specified with `netlab create -o graph:bgp:rr`), RR-client sessions are drawn as directed arrows. ## Modifying Graph Attributes -Graphing routines use **default** topology settings to modify the node- or link parameters of the generated DOT file: +Graphing routines use **[default](defaults)** topology settings to modify the generated DOT file's node- or link parameters. You can change these defaults. * **outputs.graph.interface_labels** -- Add IP addresses to links in **topology** graph. Results in a cluttered image (but feel free to fix that and submit a pull request). * **outputs.graph.colors._object_** -- Specify background color for *as*, *node*, *stub* subnet, *ibgp* or *ebgp* session. @@ -21,7 +21,9 @@ Graphing routines use **default** topology settings to modify the node- or link * **outputs.graph.groups** -- use the specified list of groups (or all groups when set to *True*) to create graph clusters * **outputs.graphs.node_address_labels** -- add node loopback IP addresses or IP addresses of the first interface (for hosts) to node labels. -You could specify these attributes in your topology file, in per-user topology defaults, or in system defaults ([more details](../defaults.md)). You could also specify them with `-s` parameter of **netlab create** command ([more details](../netlab/create.md)). The system defaults in *netlab* release 1.2.4 are included below: +You could specify these attributes in your [topology file](defaults-topology) (where you would have to prefix them with **defaults**), in [per-user topology defaults](defaults-user-file), or with [environment variables](defaults-env) (even [more details](../defaults.md)). You could also specify them with the `-s` parameter of the **[netlab create](netlab-create)** command, yet again prefixed with **defaults** ([more details](netlab-create-set)). + +The system defaults in *netlab* release 1.9.1 are included below; you can always inspect them with **netlab show defaults outputs.graph** ``` outputs: