From 394353c705c8185f9a0479a1374440092d2b6442 Mon Sep 17 00:00:00 2001
From: thl-cmk <thl-cmk@outlook.com>
Date: Tue, 6 Aug 2024 18:02:36 +0000
Subject: [PATCH] Add new file
---
TROUBLESHOOTING.md | 195 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 195 insertions(+)
create mode 100644 TROUBLESHOOTING.md
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 0000000..801874b
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,195 @@
+# Troubleshooting guide
+
+## Basics
+
+<details><summary>Setup and basic configuration</summary>
+
+If you have issues with the basic setup and configuration follow the [HowTo](HOWTO.md)
+
+</details>
+
+<details><summary>Isssues with installing the required plugins</summary>
+
+See [Checkmk extension packages (MKPs)](https://docs.checkmk.com/latest/en/mkps.html?lquery=install%20plug) in the offical Checkmk documentation
+
+</details>
+
+<details><summary>HW/SW-Inventory issues</summary>
+
+For issues with the HW/SW inventory, such as no or incomplete CDP/LLDP/IP address inventory, follow the contribution guidelines of the respective plugins
+
+- [CDP cache](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_cdp_cache/-/blob/master/CONTRIBUTING.md)
+- [LLDP cache](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_lldp_cache/-/blob/master/CONTRIBUTING.md)
+- [Inventory IPv4 addresses](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_ipv4_addresses/-/blob/master/CONTRIBUTING.md)
+- [Interface name](https://thl-cmk.hopto.org/gitlab/checkmk/vendor-independent/inventory/inv_ifname/-/blob/master/CONTRIBUTING.md)
+
+If you have no inventory at all, check your HW/SW-Inventory rule(s) (see the [HowTo](HOWTO.md) ) or the offical Checkmk documentation [The HW/SW Inventory](https://docs.checkmk.com/latest/en/inventory.html?lquery=hw/sw)
+</details>
+
+<details><summary>The desired topology layer was not created</summary>
+
+By default NVDCT will onyl create the CDP topology layer. To create any other layer use the option `-l`/`--layers` or configure the layers you want in the config file.
+
+```
+[SETTINGS]
+layers = ["LLDP", "CDP", "L3v4"]
+```
+
+</details>
+
+
+<details><summary>NVDCT runs fine, but there is no Network topology icon in the GUI</summary>
+
+There are two possible reasons for this
+
+1. there is no symbolic link "default" pointing to the default topology
+
+ The Network viszualisation backend picks up the topology behind the symlink `~/var/check_mk/topology/data/default`. If there is no such symlink there will be no Network Topology icon.
+
+ NVDCT creates the sysmlink "default" to the default topology automatically if no symlink exists. If, for whatever reason, no "default" symlink exists, you can create one manually. I.e.
+
+ ```
+ OMD[build]:~$ ln -s /omd/sites/build/var/check_mk/topology/data/fortinet ~/var/check_mk/topology/data/default
+ ```
+ Where `build` is the site name and `fortinet` the name of the topology that sould be the default topology.
+
+ Or run NVDCT with the option `-d`/`--default` or set `default = true` under `[SETTINGS]` in the config file.
+
+ ```
+ [SETTINGS]
+ default = true
+ ```
+
+ This will make the created topology the default topology at the next run of NVDCT.
+
+1. the topology was created on a different Checkmk instance than the one it should be displayed on
+
+ This can occur in distributed environments, e.g. if the topology was created on a remote site and sould be used on the central instance.
+
+ **Solution**: Always create the topology on the central instance. NVDCT can also read the data from the remote sites.
+
+ **Workaround**: If the topology cannot be created on the instance on which it is used, the generated topology (data_XXXX.jscon) must be copied to the instance on which it is used. If you sync the topology data between sites, dont forget to create the symlink "default" (see above)
+
+</details>
+
+<details><summary>Network visualization in a distributed environment</summary>
+
+In a distributed environment there are two known issues
+1. where to run NVDCT -> see above _NVDCT runs fine, but there is no Network topology icon in the GUI_
+2. where to place the configuration file
+As stated in the HowTo, always work with a copy of the default configuration file `nvdct.toml`. By default, this file is located under `~/local/bin/nvdct/conf`. In distributed environments, everything under `~/local` is overwritten by the central instance during the configuration sync, including any existing configuration files for **NCDCT**. To avoid this, the config files can either be created on the central instance and synchronized to the remote system or they must be stored on the remote system outside of `~/local`. E.g. under `~/nvdct_conf`.
+
+</details>
+
+<details><summary>Topologies from different sources</summary>
+
+If you use different sources to create topology layers, it is possible that not all layers will be adopted by the backend.
+
+The backend only picks up the layers that are available in the default topology directory.
+
+A workaround for this problem is to create an empty dummy topology file in the default directory for each layer that you cerated but that is not in the default directory. The dummy file must have the same name as the file from the other source and the layer name must also match. For example, if the other source creates the file `data_vsphere.json` with the layer name `vSphere`, the dummy file would have the following content
+
+```
+{"version": 1, "name": "vSphere", "objects": {}, "connections": []}
+```
+</details>
+
+## Layer2 Topologies (CDP/LLDP)
+<details><summary>There are not all expected devices in the Topology</summary>
+
+This can happen if you have multiple Layer2 domains (CDP/LLDP). E.g. locations that are connected via a WAN connection such as MPLS or the Internet. Normally there is no CDP/LLDP adjacency between these sites.
+
+To solve this problem, add at least one seed device from each site to the configuration file (see [HowTo](HOWTO.md)). This way NVDCT will create a topology file for all Layer2 domains together. To view a specific location, you need to start the topology view from a device of that location. Currently there is no good way to connect these Layer2 domains within Checkmk.
+
+</details>
+
+<details><summary>There are devices with a white question mark on blue background as emblem</summary>
+
+This can happen if NVDCT cannot map the neighbor names from CDP/LLDP to host names in Checkmk.
+
+The best way to solve such issues use the same name on the device and in Checkmk. If this not possible there are several options how NVDCT converts neighbor names to Checkmk names
+
+1. NVDCT removes the domain name and only uses the host name
+
+ If the FQDN is used in Checkmk, this kan be disabled with the option `--keep-domain` or in the configuratin file with
+
+ ```
+ [SETTINGS]
+ keep_domain = true
+ ```
+
+1. NVDCT can convert all neighbor names to upper or lower case
+
+ NVDCT has the options '--lowercase' and '--uppercase' for this purpose.
+
+ ```
+ [SETTINGS]
+ lowercase = false
+ uppercase = true
+ ```
+ Note: set only `lowercase` or `lowercase` to `true`. If both options set to `true`, NVDCT will prefer `uppercase`
+
+3. NVDCT can add a prefix to all neighbor names
+
+ Use the pption '-p'/'--prefix' to add an prefix to all neighbor names. The prefix will be set after the upper-/lowercase option.
+
+ ```
+ [SETTINGS]
+ prefix = "yor-prefix-"
+ ```
+
+4. NVDCT can map neighbor names to Checkmk names via the [HOST_MAP] section.
+
+ If all this options dont solve your nameig issues, there is as last option the [HOST_MAP] serction in the settings file. Here you can map neighbor names to Checkmk names.
+
+ ```
+ [HOST_MAP]
+ inventory_neighbour1 = "cmk_host1"
+ inventory_neighbour2 = "cmk_host2"
+ inventory_neighbour3 = "cmk_host3"
+ ```
+
+ You can use the NVDCT log file to check for such issues
+
+ ```
+ OMD[build]:~$ grep "not found in CMK" ~/var/log/nvdct.log
+ 2024-06-18 20:41:38,337 :: WARNING :: backends :: host_exists() :: 297 :: [MULTISITE] Host AP-01 not found in CMK
+ 2024-06-18 20:41:38,415 :: WARNING :: backends :: host_exists() :: 297 :: [MULTISITE] Host AP-02 not found in CMK
+ 2024-06-18 20:41:38,486 :: WARNING :: backends :: host_exists() :: 297 :: [MULTISITE] Host AP-03 not found in CMK
+
+ ```
+
+</details>
+
+<details><summary>There are devices that I do not want to have in the topology</summary>
+
+In most environments you will find some devices in the CDP/LLDP topology that are not in Checkmk, e.g. IP phones or client devices.
+
+There are two options in the configuration file to remove such devices from the topology.
+
+Under `DROP_HOST` you can simply add neighbor names to be excluded from the topology creation.
+```
+DROP_HOSTS = [
+ "not advertised",
+ "a nother invalid name",
+]
+```
+
+If `DROP_HOST` is not sufficient, you can use `DROP_HOSTS_REGEX`. It has the same purpose as DROP_HOSTS, but the names are interpreted here as Python regex. You can use this, for example, to remove neighbors with a MAC address as a neighbor name from the topology.
+
+```
+DROP_HOSTS_REGEX = [
+ "^(([0-9a-fA-F]){2}[:.-]?){5}([0-9a-fA-F]){2}$",
+]
+```
+
+</details>
+
+## Layer3 IPv4 Address Topologies
+<details><summary>The Layer3 topology was not created</summary>
+
+1. check whether the L3v4 layer is activated in the configuration file or whether the -l L3v4 option is used (see above _The desired topology layer was not created_)
+
+1. The creation of the Layer3 topology is based on the host label `nvdct/routing_capable:yes`. This label is added by the `inv_ip_address` plugin to all hosts with more than one IP address. After the inventory has been run, you must rediscover the host labels in Checkmk. See the [HowTo](HOWTO.md) or the Checkmk documentation about [Labels](https://docs.checkmk.com/latest/en/labels.html?lquery=host%20label)
+
+</details>
--
GitLab