Repository : ssh://git@open-mesh.org/doc

On branches: backup-redmine/2019-11-07,master

commit b0a502b27279ade6bf9358127e5a495dfdb5207e Author: Sven Eckelmann sven@narfation.org Date: Sun Oct 27 10:29:26 2019 +0000

doc: batman-adv/Developerinformation: switch to new main page for emulation documentation

b0a502b27279ade6bf9358127e5a495dfdb5207e batman-adv/BATMAN_V_Tests.textile | 2 +- batman-adv/Developerinformation.textile | 2 +- batman-adv/Faq.textile | 2 +- batmand/Developerinformation.textile | 2 +- open-mesh/Emulation_Environment.textile | 39 +++++++++++++++++++++++++++ open-mesh/Kernel_debugging_with_kgdb.textile | 4 +-- open-mesh/Kernel_hacking_Debian_image.textile | 2 +- 7 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/batman-adv/BATMAN_V_Tests.textile b/batman-adv/BATMAN_V_Tests.textile index 35b2477..8305ca6 100644 --- a/batman-adv/BATMAN_V_Tests.textile +++ b/batman-adv/BATMAN_V_Tests.textile @@ -1,6 +1,6 @@ h1. BATMAN V Tests

-The following tests have been performed on [[open-mesh:Emulation|OpenWRT with emulation setup]] to test convergence times. +The following tests have been performed on [[open-mesh:Emulation Environment|OpenWRT with emulation setup]] to test convergence times.

h1. Configuration:

diff --git a/batman-adv/Developerinformation.textile b/batman-adv/Developerinformation.textile index c9019f6..d655850 100644 --- a/batman-adv/Developerinformation.textile +++ b/batman-adv/Developerinformation.textile @@ -3,5 +3,5 @@ h2. Developer Information / Advanced Features * [[tweaking|Tweaking the B.A.T.M.A.N. Advanced behaviour]] - get an overview about the various settings batman-adv offers * [[uevent|B.A.T.M.A.N. user space events]] - batman-adv's uevent documentation * [[open-mesh:UsingBatmanGit|Using the batman git repos]] - this page explains how the git repository is structured and how to use it -* [[open-mesh:Emulation|Emulation HowTo]] - how to create an environment to emulate wireless setups using QEMU and VDE +* [[open-mesh:Emulation_Environment|Emulation HowTo]] - how to create an environment to emulate wireless setups using QEMU * [[TVLV|TVLV]] - details regarding the TVLV (type-version-length-value) API and defined TVLV containers diff --git a/batman-adv/Faq.textile b/batman-adv/Faq.textile index fcd5507..5bc2fa9 100644 --- a/batman-adv/Faq.textile +++ b/batman-adv/Faq.textile @@ -11,7 +11,7 @@ h2. B.A.T.M.A.N. General questions h3. Does B.A.T.M.A.N. have simulator (NS2, Omnet++, etc) support?

*Q:* Does B.A.T.M.A.N. have his own simulator? -*A:* At this point no, but B.A.T.M.A.N. implementation (we know of) supports simulators like the ones mentioned above. However, some people experiment with B.A.T.M.A.N. using emulators (UML/Qemu/etc). If you are looking for step-by-step instructions to install such a system you can [[open-mesh:Emulation|read our emulation document]]. +*A:* At this point no, but B.A.T.M.A.N. implementation (we know of) supports simulators like the ones mentioned above. However, some people experiment with B.A.T.M.A.N. using emulators (UML/Qemu/etc). If you are looking for step-by-step instructions to install such a system you can [[open-mesh:Emulation Environment|read our emulation document]].

h3. How to make my mesh network secure ?

diff --git a/batmand/Developerinformation.textile b/batmand/Developerinformation.textile index fcd1b25..da8c10a 100644 --- a/batmand/Developerinformation.textile +++ b/batmand/Developerinformation.textile @@ -4,4 +4,4 @@ h2. Developer Information / Advanced Features * [[DebugOutput|Understanding the debug output]] - documentation that helps you to understand the debug output * [[VisOutput|Vis output]] - working with the vis server output * [[Coredump|How to get a coredump]] - documentation about coredump configuration & retrieval -* [[open-mesh:Emulation|Emulation HowTo]] - how to create an environment to emulate wireless setups using QEMU and VDE +* [[open-mesh:Emulation Environment|Emulation HowTo]] - how to create an environment to emulate wireless setups using QEMU diff --git a/open-mesh/Emulation_Environment.textile b/open-mesh/Emulation_Environment.textile new file mode 100644 index 0000000..c4accda --- /dev/null +++ b/open-mesh/Emulation_Environment.textile @@ -0,0 +1,39 @@ +h1. Emulation Environment + +To give an answer to the often asked question "How to test/evaluate/debug mesh network protocols?", this document explains a virtual machine setup which can be used to test batman-adv in a controlled environment. The idea is to use "QEMU":https://www.qemu.org/ (instead of pure simulation systems like "NS-2":https://www.isi.edu/nsnam/ns/) to run an unmodified Linux system with the unmodified source code as it is used in real world setups. Besides B.A.T.M.A.N., you could evaluate any routing protocol. + +A simple setup is shown first and various extension and debugging helpers are explained later. + + +h2. Architecture + +The test stack consists of the following components: + +* Host running the virtual instances +* virtual instances (cloned) from a single image +* interconnect to connect the virtual instances +* various debugging tools +* optional external devices and services + +!emulation_overview.png! + +h2. Virtual Instances + +The main components of the testing setup are the virtual instances. Various images can be used to create them. There is not a single image for all tasks but the right one has to be chosen. + +* [[OpenWrt in QEMU]] +* [[Kernel hacking Debian image]] + +h2. Advanced interconnects + +The default interconnect is only creating a single broadcasting domain using a bridge. This cannot be used to simulate interesting topologies. I more advanced techniques can be used to extend or replace the bridge to still achieve a reasonable setup + +* [[bridge interconnect]] +* [[vde_switch interconnect]] +* [[mixing VM with gluon hardware]] + +h2. Debugging helpers + +* [[Analyzing interconnect packets]] +* [[Kernel debugging with qemu's GDB server]] +* [[Kernel debugging with kgdb]] \ No newline at end of file diff --git a/open-mesh/Kernel_debugging_with_kgdb.textile b/open-mesh/Kernel_debugging_with_kgdb.textile index b1353f9..4ab25bd 100644 --- a/open-mesh/Kernel_debugging_with_kgdb.textile +++ b/open-mesh/Kernel_debugging_with_kgdb.textile @@ -1,6 +1,6 @@ h1. OpenWrt KGDB

-The [[Emulation Debug]] documentation explains how to start multiple virtual Linux kernels+userspace, connect them and connect various helpers to test/debug a whole linux system. But some problems might only be reproducible on actual hardware. It is therefore sometimes necessary to debug a whole system. +The [[Emulation Environment]] documentation explains how to start multiple virtual Linux kernels+userspace, connect them and connect various helpers to test/debug a whole linux system. But some problems might only be reproducible on actual hardware ([[Mixing_VM_with_gluon_hardware|connected to the emulation setup]]). It is therefore sometimes necessary to debug a whole system.

In best case, the system can be "debugged using JTAG":https://openwrt.org/docs/techref/hardware/port.jtag. But this is often not possible and an in-kernel gdb remote stub like "KGDB":https://www.kernel.org/doc/html/latest/dev-tools/kgdb.html has to be used. The only requirement it has on the actual board is a simple serial console with <code>poll_{get,put}_char()</code> support.

@@ -297,7 +297,7 @@ lx-symbols ../batman-adv-2019.2/.pkgdir/ ../backports-4.19.66-1/.pkgdir/ ../butt

The rest of the usage now works similar to debugging using gdbserver. Just set some additional breakpoints and let the kernel run again. kgdb will then inform gdb whenever a breakpoints was hit. Just keep in mind that it is not possible to interrupt the kernel from gdb (without a Oops or an already existing breakpoint) - use sysrq from linux for that.

-Some other ideas are documented in [[Emulation_Debug#Using-GDB]]. This document also contains important hints about [[Emulation_Debug#Building-the-batman-adv-module|increasing the chance of getting debugable modules]] which didn't had all information optimized away. The relevant flags could be set directly in the routing feed like this: +Some other ideas are documented in [[Kernel_debugging_with_qemu's_GDB_server]]. This document also contains important hints about [[Kernel_hacking_Debian_image#Building-the-batman-adv-module|increasing the chance of getting debugable modules]] which didn't had all information optimized away. The relevant flags could be set directly in the routing feed like this:

<pre><code class="diff"> diff --git a/batman-adv/Makefile b/batman-adv/Makefile diff --git a/open-mesh/Kernel_hacking_Debian_image.textile b/open-mesh/Kernel_hacking_Debian_image.textile index 93ec52a..7c0887b 100644 --- a/open-mesh/Kernel_hacking_Debian_image.textile +++ b/open-mesh/Kernel_hacking_Debian_image.textile @@ -270,7 +270,7 @@ make all -j$(nproc || echo 1)

h2. Start of the simple environment

-The two node environment must be started inside a screen session. The hub (bridge with 5 tap devices) has to be started first to have a simple network. A more complex network setup can be on the page [[Emulation]] +The two node environment must be started inside a screen session. The hub (bridge with 5 tap devices) has to be started first to have a simple network. A more complex network setup can be on the page [[vde switch interconnect]] and [[bridge interconnect]]

The @ETH@ in hub.sh has to be changed to the real interface which provides internet-connectivity