From 26a5e00aa1891ac63a933869f3514d5598173ddf Mon Sep 17 00:00:00 2001
From: thl-cmk <thl-cmk@outlook.com>
Date: Sat, 28 Oct 2023 15:11:40 +0000
Subject: [PATCH] Update README.md
---
README.md | 77 +++++++++++++++++++++----------------------------------
1 file changed, 29 insertions(+), 48 deletions(-)
diff --git a/README.md b/README.md
index 2e1fa20..1730be2 100644
--- a/README.md
+++ b/README.md
@@ -62,31 +62,24 @@ To use this tool:
---
### Usage
-Usage with CDP (this is the default):
+Usage with CDP and STATIC (this is the default):
```
~/local/lib/topology_data/create_topology_data.py -s Core01 -d
```
-Usage with LLDP:
+Usage with LLDP and STATIC:
```
-~/local/lib/topology_data/create_topology_data.py -s Core01 -d --lldp
+~/local/lib/topology_data/create_topology_data.py -s Core01 -d -l LLDP STATIC
```
-Usage with CDP merged into LLDP
-```
-~/local/lib/topology_data/create_topology_data.py -s Core01 -d -m CDP LLDP
-```
-
-<details><summary>Help output from create_topology_data.py -h</summary>
+<details><summary>Help output from create_topology_data.py --help</summary>
```
-OMD[build]:~$ ~/local/bin/topology_data/create_topology_data.py -h
-usage: create_topology_data.py [-h] [-d] [-m {CDP,LLDP} {CDP,LLDP}] [-o OUTPUT_DIRECTORY]
- [-s SEED_DEVICES [SEED_DEVICES ...]] [-u USER_DATA_FILE] [-v]
- [--check-user-data-only] [--data-source DATA_SOURCE] [--debug]
- [--dont-compare] [--inventory-columns INVENTORY_COLUMNS] [--keep-domain]
- [--keep KEEP] [--lldp] [--lowercase] [--min-age MIN_AGE]
- [--path-in-inventory PATH_IN_INVENTORY] [--time-format TIME_FORMAT]
- [--uppercase]
+OMD[build]:~$ ~/local/bin/topology_data/create_topology_data.py --help
+usage: create_topology_data.py [-h] [-d] [-o OUTPUT_DIRECTORY] [-s SEED_DEVICES [SEED_DEVICES ...]]
+ [-l {CDP,CUSTOM,LLDP,STATIC} [{CDP,CUSTOM,LLDP,STATIC} ...]]
+ [-u USER_DATA_FILE] [-v] [--check-user-data-only] [--debug] [--dont-compare]
+ [--keep-domain] [--keep KEEP] [--lowercase] [--min-age MIN_AGE]
+ [--time-format TIME_FORMAT] [--uppercase]
This script creates the topology data file needed for the Checkmk "network_visualization"
plugin by Andreas Boesl and schnetz. For more information see
@@ -97,19 +90,12 @@ The required inventory data can be created with my inventory plugins:
CDP: https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_cdp_cache
LLDP: https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_lldp_cache
-Version: 0.0.8-202310120 | Written by: thl-cmk
+Version: 0.1.0-202310128 | Written by: thl-cmk
for more information see: https://thl-cmk.hopto.org
options:
-h, --help show this help message and exit
-d, --default Set the created topology data as default
- -m {CDP,LLDP} {CDP,LLDP}, --merge {CDP,LLDP} {CDP,LLDP}
- Merge topologies. This runs the topology creation for CDP and LLDP.
- The topologies are then merged in the specified order.
- I.e. -m CDP LLDP merges the CDP topology into the LLDP topology, overwriting
- the LLDP data in case there are conflicts.
- NOTE: static connection data from the user file will always merged with the
- highest priority
-o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
Directory name where to save the topology data.
I.e.: my_topology. Default is the actual date/time
@@ -118,41 +104,29 @@ options:
-s SEED_DEVICES [SEED_DEVICES ...], --seed-devices SEED_DEVICES [SEED_DEVICES ...]
List of devices to start the topology discovery from.
I.e. Core01 Core02
+ -l {CDP,CUSTOM,LLDP,STATIC} [{CDP,CUSTOM,LLDP,STATIC} ...], --layers {CDP,CUSTOM,LLDP,STATIC} [{CDP,CUSTOM,LLDP,STATIC} ...]
+ Layers with least significant layer first. Listed layers
+ will be merged automatically. Default is "-l CDP STATIC"
-u USER_DATA_FILE, --user-data-file USER_DATA_FILE
Set the name uf the user provided data file
Default is ~local/bin/topology_data/create_topology_data.toml
-v, --version Print version of this script and exit
--check-user-data-only
Only tries to read/parse the user data from create_topology_data.toml and exits.
- --data-source DATA_SOURCE
- The source from which the topology data originates.
- I.e. inv_CDP for CDP data from the inventory.
- NOTE: right now this only an unused label.
--debug Print debug information
--dont-compare Do not compare the actual topology data with the default topology
data. By default, the actual topology is compared with the default
topology. If the data matches, the actual topology is not saved.
So, if you run this tool in a cron job, a new topology will be
created only if there was a change, unless you use "--dont-compare".
- --inventory-columns INVENTORY_COLUMNS
- Columns used from the inventory data.
- I.e. "device_id,local_port,device_port"
- NOTE: the columns must be in the order: neighbour, local_port,
- neighbour_port
--keep-domain Do not remove the domain name from the neighbor name
--keep KEEP Number of topologies to keep. The oldest topologies above keep
max will be deleted. The minimum value for --keep is 1.
NOTE: The default topologies will be always kept.
- --lldp Sets data source to inv_LLDP, inventory path
- to "networking,lldp_cache" and columns
- to "system_name,local_port_num,port_id"
--lowercase Change neighbour names to all lower case
--min-age MIN_AGE The minimum number of days before a topology is deleted
by "--keep".
NOTE: Topologies that are not older than 1 days are always kept.
- --path-in-inventory PATH_IN_INVENTORY
- Checkmk inventory path to the topology data.
- I.e. "networking,cdp_cache"
--time-format TIME_FORMAT
Format string to render the time. (default: %Y-%m-%dT%H:%M:%S.%m)
--uppercase Change neighbour names to all upper case
@@ -160,9 +134,7 @@ options:
Usage:
for CDP (the default):
~/local/bin/network-topology/create_topology_data.py -s Core01 Core02 -d
-for LLDP:
-~/local/bin/network-topology/create_topology_data.py -s Core01 Core02 -d --lldp
-OMD[build]:~$
+OMD[build]:~$
```
</details>
@@ -255,6 +227,10 @@ Yes. You can customize the topology data creation by modifying the `~/local/bin
**Note**: This file uses [Tom's Obvious Minimal Language](https://toml.io/en/)
+```
+~/local/bin/topology_data/create_topology_data.py -u ~/local/bin/topology_data/my.toml
+```
+
</details>
<details><summary>My Neighbor names from the inventory and checkmk host names do not match</summary>
@@ -308,13 +284,18 @@ STATIC_CONNECTIONS = [
<details><summary>Can I use the tool with other inventory data plugins</summary>
\
-Yes. If you don\`t use my plugins you can still use this tool to create your topology data, for this you need the path to your topology data in the inventory. For example for my CDP plugin this is _Networking_ -> _CDP Cache_ internally known as `networking` -> `cdp_cache`. The data must form a table in the inventory that contains at least the three columns for the neighbor name, neighbor port, and local port. For these columns you need the internal names. I.e. for my CDP plugin the columns _Neighbor device_, _Neighbor port_ and _Local port_ are known internally as `device_id`, `local_port` and `device_port`. With this information, you can run the tool like this
-
+Yes. If you don\`t use my plugins you can still use this tool to create your topology data, for this you need the path to your topology data in the inventory. For example for my CDP plugin this is _Networking_ -> _CDP Cache_ internally known as `networking` -> `cdp_cache`. The data must form a table in the inventory that contains at least the three columns for the neighbor name, neighbor port, and local port. For these columns you need the internal names. I.e. for my CDP plugin the columns _Neighbor device_, _Neighbor port_ and _Local port_ are known internally as `device_id`, `local_port` and `device_port`. With this information, you can edit the CUSTOM_LAYERS section in the user data file like this
+```
+# optional custom layers use option -l/--layers CUSTOM to include this layers
+CUSTOM_LAYERS = [
+ { path = "networking,lldp_cache", columns = "system_name,local_port_num,port_id", label = "custom_LLDP" },
+ { path = "networking,cdp_cache", columns = "device_id,local_port,device_port", label = "custom_CDP" },
+]
```
-~/local/bin/network-topology/create_topology_data.py -s Core01 --path-in-inventory "networking,cdp_cache" --inventory-columns "device_id,local_port,device_port"
+then run the tool with the option `-l CUSTOM`
+```
+~/local/bin/network-topology/create_topology_data.py -s Core01 -l CUSTOM
```
-
-Wehre `--path-in-inventory` is the path to your inventory data and `--inventory-columns` are the columns used in the order _neighbor_, _local port_, _neighbor port_.
</details>
--
GitLab