From b33bdb1815527fcb6e8f287e57e17b3220f5eb25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20K=C3=BCthe?= <m.k@mk16.de>
Date: Wed, 17 Jul 2024 19:31:24 +0000
Subject: [PATCH] Add documentation for babeld-cli.sh

---
 docs/routing/babeld/babeld-cli-sh.md | 54 ++++++++++++++++++++++++++++
 mkdocs.yml                           |  1 +
 2 files changed, 55 insertions(+)
 create mode 100644 docs/routing/babeld/babeld-cli-sh.md

diff --git a/docs/routing/babeld/babeld-cli-sh.md b/docs/routing/babeld/babeld-cli-sh.md
new file mode 100644
index 0000000..0bba292
--- /dev/null
+++ b/docs/routing/babeld/babeld-cli-sh.md
@@ -0,0 +1,54 @@
+# babeld-cli.sh
+
+babeld has an interface for dumping information, which by default listens on TCP port 33123. This is also used by babelweb, for example, to create the graph.
+Unfortunately, babeld does not provide a tool to use this interface. However, simple tools such as bash, netcat, grep and awk are sufficient to receive and interpret the results.
+
+A ready-made script for this is available on Codeberg [available](https://codeberg.org/mark22k/babeld_helper/).
+
+## Installation
+
+The installation can be done by cloning the repository with git:
+```
+$ git clone https://codeberg.org/mark22k/babeld_helper.git
+```
+
+Alternatively, you can just download the script and make it executable:
+```
+$ wget https://codeberg.org/mark22k/babeld_helper/raw/branch/main/babeld-cli.sh
+$ chmod +x ./babeld-cli.sh
+```
+or
+```
+$ curl --output babeld-cli.sh https://codeberg.org/mark22k/babeld_helper/raw/branch/main/babeld-cli.sh
+$ chmod +x ./babeld-cli.sh
+```
+
+## Usage
+
+Once the script is executable, it can be called with `./babeld-cli.sh [options]`. `[options]` can take the following values `interfaces`, `neighbors`, `routes`, `xroutes` or `version`. Interfaces returns the configured interfaces, Neighbors returns the actually active neighbors, Routes returns all (not only installed) routes, xroutes returns the own routes that are propagated and version returns the version number of the running babeld.
+
+### Interfaces
+
+Interfaces returns three columns `Interface`, `State` and `Next hop`.
+
+### Neighbors
+
+Neighbors returns nine columns `Neighbor ID`, `IP address`, `Interface`, `Reach`, `RX cost`, `TX cost`, `RTT`, `RTT cost` and `Cost`. 'Neighbor ID' indicates the ID of the neighbor, 'IP address' the IP address of the neighbor, 'Interface' indicates the interface on which the neighbor is located, 'RX cost' the configured RX costs, 'TX cost' the RX cost configured by the peer, 'RTT' the current round trip time in MS, 'RTT cost' the additional RX costs based on the RTT and 'Cost' the addition of the configured RX costs and the RTT RX costs - i.e. the real actual costs. RX costs are the costs that the neighbor needs to reach us.
+
+### Routes
+
+**Note**: The output can be very long.
+
+Routes returns eight columns `Route ID`, `Prefix`, `Installed`, `ID`, `Metric`, `Refmetric`, `Next hop` and `Interface`. `Prefix` specifies the actual prefix, `Installed` specifies whether the route is installed in the kernel or the forwarding plane and thus effectively whether it is the preferred route, `Metric` specifies the cost of this route to the destination, `Refmetric` specifies the cost of this route to the destination, but without this node or the cost of the neighbor to the destination, `Next hop` specifies the next hop and `Interface` specifies the interface on which the next hop is located.
+
+### XRoutes
+
+XRoutes returns two columns. `Prefix` indicates the prefix which is to be propagated and `Metric` the costs for this prefix (normally 0).
+
+### Version
+
+Version returns three values. Firstly, the current babeld version that is currently running, the name of the host on which it is running and the configured router ID.
+
+## babeld-cli.sh on OpenWrt
+
+OpenWrt does not have bash installed by default and therefore cannot execute the script. To execute it anyway, the first line where bash is specified can be replaced by `#!/bin/ash`.
diff --git a/mkdocs.yml b/mkdocs.yml
index be990b8..79bbb4c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -29,6 +29,7 @@ nav:
         - Setting up Babeld: routing/babeld/babeld
         - Compile and install babeld: routing/babeld/compile-install
         - max-len filter in babeld: routing/babeld/maxlen-filter
+        - babeld-cli.sh: routing/babeld/babeld-cli-sh
         - babelweb2: routing/babeld/babelweb2