Collection of CheckMK checks (see https://checkmk.com/). All checks and plugins are provided as is. Absolutely no warranty. Send any comments to thl-cmk[at]outlook[dot]com

Skip to content
Snippets Groups Projects
Commit ac0bf45c authored by thl-cmk's avatar thl-cmk :flag_na:
Browse files

Update README.md

parent 1c08ce67
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 63 additions and 44 deletions
README.md
+ 63
− 44
View file @ ac0bf45c
......@@ -5,18 +5,19 @@ This script creates the topology data file needed for the [Checkmk Exchange Netw
For more information see [Checkmk forum Network Visualization](https://forum.checkmk.com/t/network-visualization/41680).
Features:
- Reading layer 2 connection data from the checkmk HW/SW inventory.
- Works in distributed monitoring environments
- Handling differences between inventory neighbor names and checkmk host names.
- Map layer 2 port names to interface service items
- Add custom connections for connections that are not in the inventory
- Optimized for my [CDP](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_cdp_cache/) (default) and [LLDP](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_lldp_cache/) cache plugins
- Read and merge CDP and LLDP topologies
- Create Layer 2 (CDP/LLDP) topology data
- Create Layer 3 (IPv4) topology data -> CMK2.3.0 only
- Reading connection data from the checkmk HW/SW inventory.
- Works in standalone and distributed monitoring environments
- Add custom connections (STATIC) for connections that are not in the inventory
- Optimized for my [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/) and [IPv4](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_ipv4_addresses) inventory plugins
- Merge CDP, LLDP, STATIC topologies (CMK 2.2.0 only)
- Can also be used with custom inventory plugins
The necessary HW/SW inventory data can be created with my CDP/LLDP inventory plugins.
- [CDP inventory plugin](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_cdp_cache/)
- [LLDP inventory plugin](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_lldp_cache/)
- [IPv4 inventory plugin](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_ipv4_addresses)
- [Interface name inventory plugin (optional but recommended)](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_ifname)
---
......@@ -32,7 +33,7 @@ detlev[dot]gerke[at]siegfried[dot]ch, who was my beta tester ;-)
* [Download latest mkp file][PACKAGE]
**Note**: before updating to a newer version check the [CHANGELOG](/CHANGELOG "CHANGELOG"). There could always be an incompatible change.
**Note**: before updating to a newer version check the [CHANGELOG](/CHANGELOG "CHANGELOG"). There could be always incompatible changes.
---
### Installation
......@@ -57,11 +58,12 @@ To use this tool:
- the HW/SW inventory must be enabled
- you need to install/enable an inventory plugin to collect the connection data I.e. my [CDP cache](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_cdp_cache/) or [LLDP cache](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_lldp_cache/) plugins
- check if the Checkmk HW/SW inventory finds the required data (CDP/LLDP neighbors)
- the [Network visualization plugin](https://exchange.checkmk.com/p/network-visualization) must be installed
- the [Network visualization plugin](https://exchange.checkmk.com/p/network-visualization) must be installed (CMK 2.2.0 only, for CMK2.3.0 this is bildin)
**Note**: if you are using my CDP/LLDP plugins update at least to version
- 0.7.1-20231221 for CDP
- 0.9.2-2023122 for LLDP
**Note**: if you are using my CDP/LLDP/IPv4 plugins update at least to version
- 0.7.6-20240414 for CDP
- 0.9.7-20240414 for LLDP
- 0.0.4-20240407 for IPv4
and let Checkmk run the HW/SW inventory for each device at least once
......@@ -83,11 +85,12 @@ Usage with LLDP and STATIC:
OMD[build]:~$ ~/local/bin/nvdct/nvdct.py -h
usage: nvdct.py [-h] [-b {FILESYSTEM,LIVESTATUS,MULTISITE,RESTAPI}] [-d] [-o OUTPUT_DIRECTORY]
[-s SEED_DEVICES [SEED_DEVICES ...]] [-p PREFIX]
[-l {CDP,CUSTOM,LLDP,STATIC,L3v4} [{CDP,CUSTOM,LLDP,STATIC,L3v4} ...]] [-u USER_DATA_FILE]
[-v] [--check-user-data-only] [--log-file LOG_FILE]
[--log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [--log-to-stdout] [--dont-compare]
[--keep-domain] [--keep KEEP] [--lowercase] [--min-age MIN_AGE] [--new-format] [--quiet]
[--time-format TIME_FORMAT] [--uppercase]
[-l {CDP,CUSTOM,LLDP,STATIC,L3v4} [{CDP,CUSTOM,LLDP,STATIC,L3v4} ...]]
[-u USER_DATA_FILE] [-v] [--api-port API_PORT] [--check-user-data-only]
[--log-file LOG_FILE] [--log-level {CRITICAL,FATAL,ERROR,WARNING,INFO,DEBUG,OFF}]
[--log-to-stdout] [--dont-compare] [--keep-domain] [--keep KEEP] [--lowercase]
[--min-age MIN_AGE] [--new-format] [--pre-fetch] [--quiet] [--skip-l3-if]
[--skip-l3-ip] [--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,24 +100,27 @@ and the plugin on the Exchange: https://exchange.checkmk.com/p/network-visualiza
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
L3v4: https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_ipv4_addresses
Version: 0.6.2-20240104 | Written by: thl-cmk
Version: 0.8.7-20240430 | Written by: thl-cmk
for more information see: https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/nvdct
options:
-h, --help show this help message and exit
-b {FILESYSTEM,LIVESTATUS,MULTISITE,RESTAPI}, --backend {FILESYSTEM,LIVESTATUS,MULTISITE,RESTAPI}
Backend used to retrieve the topology data
FILESYSTEM fetches the data directly form the inventory files -> use in distributed environments
LIVESTATUS fetches data via local Livestatus -> only local site
MULTISITE like LIVESTATUS but for distributed environments -> this is the default
RESTAPI uses the CMK REST API.
-d, --default Set the created topology data as default
- FILESYSTEM : fetches the data directly form the inventory files (deprecatred)
- LIVESTATUS : fetches data via local Livestatus (local site only)
- MULTISITE : like LIVESTATUS but for distributed environments (default)
- RESTAPI : uses the CMK REST API.
-d, --default Set the created topology data as default. Will be created automatically
if it doesn't exists.
-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
in "--time-format" format.
NOTE: the directory is a sub directory under "~/var/topology_data/"
NOTE: the directory is a sub directory under "~/var/topology_data/" (CMK2.2.0)
For CMK 2.3.0 the path is under "~/var/check_mk/topology/data/".
-s SEED_DEVICES [SEED_DEVICES ...], --seed-devices SEED_DEVICES [SEED_DEVICES ...]
List of devices to start the topology discovery from.
I.e. Core01 Core02
......@@ -122,20 +128,22 @@ options:
Prepends each host with the prefix. (Needs testing)
-l {CDP,CUSTOM,LLDP,STATIC,L3v4} [{CDP,CUSTOM,LLDP,STATIC,L3v4} ...], --layers {CDP,CUSTOM,LLDP,STATIC,L3v4} [{CDP,CUSTOM,LLDP,STATIC,L3v4} ...]
Layers with least significant layer first. Listed layers
will be merged automatically. Default is "-l CDP STATIC"
CDP - needs inv_cdp_cache package at least in version 0.7.1-20231221
LLDP - needs inv_lldp_cache package at least in version 0.9.2-20231221
L3v4 - adds, layer 3 topology fpr IPv4
needs inv_ipv4_addresses package at least in version 0.9.2-20231221
will be merged automatically (CMK2.2 only).
- CDP : needs inv_cdp_cache package at least in version 0.7.1-20240320
- LLDP : needs inv_lldp_cache package at least in version 0.9.3-20240320
- L3v4 : needs inv_ipv4_addresses package at least in version 0.0.3-20240320
adds, layer 3 topology fpr IPv4 (CMK 2.3.0 only)
-u USER_DATA_FILE, --user-data-file USER_DATA_FILE
Set the name uf the user provided data file
Default is ~/local/bin/nvdct/nvdct.toml
-v, --version Print version of this script and exit
--api-port API_PORT TCP Port to access the REST API. Default is 80. NVDCT will try to automatically
detect the site apache port.
--check-user-data-only
Only tries to read/parse the user data from nvdct.toml and exits.
--log-file LOG_FILE Set the log file. Default is ~/var/log/nvdct.log
--log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}
Sets the loglevel. The default is "WARN"
--log-level {CRITICAL,FATAL,ERROR,WARNING,INFO,DEBUG,OFF}
Sets the log level. The default is "WARNING"
--log-to-stdout Send log to stdout.
--dont-compare Do not compare the actual topology data with the default topology
data. By default, the actual topology is compared with the default
......@@ -148,8 +156,13 @@ options:
NOTE: The default topologies will be always kept.
--lowercase Change neighbour names to all lower case
--min-age MIN_AGE The minimum number of days before a topology is deleted by "--keep".
--new-format Save data in new format
--new-format Save data in new format. Use for CMK 2.3.x
NVDCT will try to automatically detect the correct format. (deprecated)
--pre-fetch Try to fetch host data, with less API calls. Can improve RESTAPI backend
performance
--quiet Suppress output to stdtout
--skip-l3-if Skip interface in layer 3 topology
--skip-l3-ip Skip ip-address in layer 3 topology
--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
......@@ -163,6 +176,7 @@ Exit codes:
Usage:
~/local/bin/nvdct/nvdct.py -s Core01 Core02 -d
OMD[build]:~$
```
......@@ -171,9 +185,8 @@ OMD[build]:~$
---
### Known limitations
- ~~local/neighbour interface names have to match the service names in Checkmk~~
- ~~works by default only for the local site, use `--backend FILESYSTEM` in distributed environments.~~
- the backend `FILESYSTEM` can only acces the local autochheck files, this might lead in ditributed environments to incomplete data, use `MUTLISITE` or `RESTAPI` instead
---
### FAQ
......@@ -350,23 +363,29 @@ First check your HW/SW inventory if it not contains the data needed to create th
Sample output
```
OMD[build]:~$ ~/local/bin/nvdct/nvdct.py -l LLDP CDP STATIC
OMD[build]:~$ ~/local/bin/nvdct/nvdct.py -u ~/local/bin/nvdct/nvdct.toml
Network Visualisation Data Creation Tool (NVDCT)
by thl-cmk[at]outlook[dot]com, version 0.6.2-20240103
by thl-cmk[at]outlook[dot]com, version 0.8.7-20240430
see https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/nvdct
Start time...: 2024-01-03T13:02:45.01
Devices added: 17, source lldp
Devices added: 72, source cdp
Devices added: 29, source static
Time taken...: 0.450685963/s
End time.....: 2024-01-03T13:02:46.01
Start time....: 2024-04-30T14:17:02.04
Devices added.: 16, source lldp
Devices added.: 72, source cdp
Devices added.: 29, source STATIC
Devices added.: 59, source L3v4
Time taken....: 3.225333135/s
End time......: 2024-04-30T14:17:05.04
OMD[build]:~$
```
Sample network topology
Sample network topology CDP/LLDP CMK 2.2.0
![CDP/LLDP CMK 2.2.0](/img/sample-cmk2-2.png?raw=true "Sample network topology CDP/LLDP CMK 2.2.0")
![sample output details](/img/sample-details.png?raw=true "sample output details")
Sample network topology CDP/LLDP CMK 2.2.0
![CDP/LLDP CMK 2.2.0](/img/sample-cmk2-3.png?raw=true "Sample network topology CDP/LLDP CMK 2.2.0")
Sample network topology IPv4 CMK 2.3.0
![CDP/LLDP CMK 2.2.0](/img/sample-cmk2-3-ipv4.png?raw=true "Sample network topology IPv4 CMK 2.3.0")
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Collection of CheckMK checks (see https://checkmk.com/). All checks and plugins are provided as is. Absolutely no warranty. Send any comments to thl-cmk[at]outlook[dot]com