mirror of
https://github.com/bmx-routing/bmx7
synced 2025-10-05 15:52:41 +02:00
Added runtime debugging directives, updated the README#FAQ section
This commit is contained in:
Harry Pantazis
committed by
Paul Spooren
Paul Spooren
parent
4e29b2ddc4
commit
91d6651ccb
31
README.md
31
README.md
@@ -1,6 +1,6 @@
|
||||
|
||||
|
||||
|
||||
BMX7 is a mesh routing protocol for Linux based operating systems.
|
||||
BMX7 is a mesh routing protocol for Linux based operating systems.
|
||||
The academic paper with more theoretical details can be found [here](http://dsg.ac.upc.edu/node/843).
|
||||
|
||||
## Content
|
||||
@@ -65,7 +65,7 @@ cd bmx7
|
||||
To only compile the main bmx7 daemon (no bmx7 plugins):
|
||||
```
|
||||
make EXTRA_CFLAGS="-DCRYPTLIB=MBEDTLS_2_4_0"
|
||||
sudo make install
|
||||
sudo make install
|
||||
```
|
||||
|
||||
## Installing in OpenWRT
|
||||
@@ -92,6 +92,25 @@ Available packages exist for the following distributions:
|
||||
|
||||
## FAQ
|
||||
1. How does BMX7 work and on which OSI layer?
|
||||
3. Cool features
|
||||
4. Differences with bmx6
|
||||
5. Similar Software
|
||||
- BMX7 is a routing protocol that operates on layer 3 of the OSI layer; it
|
||||
extends the concept of **receiver-driven routing** and the principles of
|
||||
DSDV routing. The routing update of BMX7 (in contrast to traditional DSDV)
|
||||
contains a single and verifiable heartbeat value which unambiguously
|
||||
identifies a particular node of the network and a specific version of this
|
||||
nodes' self-defined description and routing-update version.
|
||||
|
||||
2. The goal of BMX7/SEMTOR?
|
||||
- The goal of BMX7 is to provide secure mechanisms to ensure that
|
||||
non-trusted nodes in an open network are effectively prevented from
|
||||
disrupting the routing between trusted nodes.
|
||||
- It's achieved by enforcing the exclusion of a given set of identified faulty nodes.
|
||||
|
||||
3. Differences with bmx6
|
||||
- TBD
|
||||
|
||||
4. Similar Software
|
||||
- AODV,
|
||||
- Babel,
|
||||
- BMX6,
|
||||
- OLSR,
|
||||
- batman-adv
|
||||
|
||||
@@ -40,3 +40,76 @@ address usage is the most common reason for such events which happens
|
||||
if two nodes are using (and announcing) the same primary IPs.
|
||||
|
||||
|
||||
## Dynamic Reconfiguration
|
||||
|
||||
Most bmx7 parameters can be applied not only at startup, but also dynamically to an already running main daemon, using the `--connect` command.
|
||||
For example interfaces can be added, removed, or specified with more details:
|
||||
The following example removes interface eth1 and adds eth2 with a max rate of 100 Mbits (overwriting the default assumption of 1000Mbits for ethernet interfaces).
|
||||
|
||||
```
|
||||
bmx7 -c dev=-eth1 dev=eth2 /rateMax=100000
|
||||
bmx7 -cd8
|
||||
```
|
||||
|
||||
Checking new status of interfaces, links, and originator:
|
||||
|
||||
```
|
||||
root@mlc1001:~# bmx7 -cd8
|
||||
```
|
||||
|
||||
It can be seen that:
|
||||
|
||||
* Interface eth1 has been replaced by eth2 with a lower rate.
|
||||
* The old links (via eth1) are removed and a single new link via eth2 to mlc1000 has been detected
|
||||
* All routes are now going via eth2
|
||||
|
||||
|
||||
## Address auto and manual configuration
|
||||
|
||||
By default bmx7 autoconfigures all configred interface by combining a default prefix (fd70::/16) with
|
||||
the SHA224 hash of each nodes' public rsa key.
|
||||
|
||||
|
||||
|
||||
## Unicast Host Network Announcements
|
||||
|
||||
A Host Network Announcements (HNA) describes the advertisement of IP addresses and networks by a node to other nodes in the mesh.
|
||||
Typically (but not with BMX7), several nodes can announce the same or overlapping HNAs at the same time.
|
||||
Announced networks do overlap if they are equal or one being a subset of another (eg. 10.1.1.0/24 is a subset and overlapped by 10.1.0.0/16).
|
||||
Packets with a destination address matching an announced networks will be routed toward any node that originated a corresponding HNA.
|
||||
Therefore these HNA types may also be called anycast HNA.
|
||||
|
||||
In bmx7, HNAs have an unicast nature (UHNAs) because each network can only be announced once and announced networks MUST NOT overlap (See also Wiki).
|
||||
This way it can be ensured that the destination of an UHNA routed packet is exactly known.
|
||||
|
||||
In a sense the origination and propagation (by intermediate nodes) of UHNA announcements can be thought of a promise that guarantees:
|
||||
1. All packets with a destination address matching an announced UHNA network will be routed exactly to the node (with the global ID) that originated the UHNA and
|
||||
2. each node on the forwarding path towards the originator of the UHNA is supporting this promise.
|
||||
|
||||
By default, Bmx7 only announces primary addresses via UHNAs.
|
||||
The cryptographic address configuration ensures that interface addresses are unique.
|
||||
|
||||
Using UHNAs for the announcements of networks requires a strict coordination to ensure that no network is announced twice.
|
||||
|
||||
Technically, multiple UHNAs, each wrapped into a single message, are aggregated into a UHNA frame and attached to the description of a node.
|
||||
Only IPv6 UHNAs can be announced.
|
||||
|
||||
The announcement of UHNAs can be configured with the `--unicastHna` or `-u` parameter followed by a network specification in ip/prefixlen notation.
|
||||
By default all interface addresses are announced via UHNAs. However, this can be disabled by setting the `--dev` subparameter `/announce` or `/a` to 0.
|
||||
|
||||
The following example reconfigures an already running bmx7 daemon to UHNA announce the network fd00:ffff:ffff:ffff::/64 and fd01:ffff:ffff::/48.
|
||||
By omitting the `--connect / -c` parameter, the same could be configured as startup parameter for bmx7.
|
||||
|
||||
```
|
||||
bmx7 -c u=fd00:ffff:ffff:ffff::/64 u=fd01:ffff:ffff::/48
|
||||
```
|
||||
|
||||
An already active announcement can be removed by preceeding the network with the `-` char:
|
||||
```
|
||||
bmx7 -c u=-fd00:ffff:ffff:ffff::/64
|
||||
```
|
||||
|
||||
Before bmx7 accepts a dynamically configured UHNA announcement it checks if this UHNA is not overlapping with an already existing UHNA announcement form another node.
|
||||
If this is the case the configuration will fail.
|
||||
To check if a chain of dynamic commands would be accepted by a bmx7 daemon without actually applying it, the `--test` command may follow the `--connect` command.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Debugging
|
||||
|
||||
**There three channels for debugging with different intended verbosity:**
|
||||
1. system log,which also appears with logread or dmesg. This can be accessed with bmx7 -cd0.
|
||||
1. system log,which also appears with logread or dmesg. This can be accessed with bmx7 -cd0.
|
||||
2. Event logs are more verbose they are used for tracking of events and triggered with code dbgf_track(...). They can be accessed with command bmx7 -cd3.
|
||||
3. Most verbose logs coded with dbgf_all(). Can be accessed with command bmx7 -cd4. (But for embedded devices these logs are often compiled out with a NODEBUGALL Macro or so.
|
||||
|
||||
@@ -9,8 +9,23 @@
|
||||
- Track logs also end up in all logs.
|
||||
|
||||
**There are three different flags for logs:**
|
||||
1. DBGT_INFO,
|
||||
2. DBGT_WARN,
|
||||
3. DBGT_ERR.
|
||||
|
||||
1. DBGT_INFO,
|
||||
2. DBGT_WARN,
|
||||
3. DBGT_ERR.
|
||||
|
||||
These are just used to unify the severity level with which the log appears.
|
||||
|
||||
## Developer directives
|
||||
|
||||
BMX7 uses a handful of assertions and debug level directives within it's source
|
||||
code.
|
||||
|
||||
- A usual scenario would be your changes to pass compilation and then get a
|
||||
SIG* error on runtime. In this case the core is dumped and an error code of
|
||||
the range (-500000, -600000) is displayed which can pinpoint you the exact
|
||||
assert violation that caused it.
|
||||
Inspect the assertion and then load the core that was dumped along with a
|
||||
compiled version of bmx7 (that was compiled with the -g option), likewise:
|
||||
```
|
||||
gdb ./core ./bmx7
|
||||
```
|
||||
|
||||
105
doc/Usage.md
105
doc/Usage.md
@@ -2,9 +2,6 @@
|
||||
* [Intro](#intro)
|
||||
* [Monitoring bmx7](#monitoring-bmx7)
|
||||
* [Simple Ping Test](#simple-ping-test)
|
||||
* [Dynamic Reconfiguration](#dynamic-reconfiguration)
|
||||
* [Address Auto & Manual Configuration](#address-auto-and-manual-configuration)
|
||||
* [UHNAs](#unicast-host-network-announcements)
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -22,7 +19,7 @@ However, to let this simple command work as expected also check the following ba
|
||||
and autoconfigures a [ULA](https://en.wikipedia.org/wiki/Unique_local_address)-based IPv6
|
||||
address for each interface based on the MAC address of the
|
||||
device. The only pre-requisite is that the interfaces must be in the
|
||||
`up` state, E.G.: `ip link set wlan0 up`.
|
||||
`up` state, E.G.: `ip link set wlan0 up`.
|
||||
|
||||
If you are using a wireless interface, the interface settings must
|
||||
have been configured using `iwconfig` or `iw` to communicate with bmx7
|
||||
@@ -128,16 +125,16 @@ shortId name linkKey linkKeys nbLocalIp dev rts
|
||||
AAD9C0F5 mlc1002 DH2048M112 RSA896,DH2048M112 fe80::a2cd:efff:fe10:201 eth1 8 100 100 1000M 1000M -1 0 0 20 0
|
||||
ORIGINATORS:
|
||||
shortId name as S s T t descSqn lastDesc descSize cv revision primaryIp dev nbShortId nbName metric hops ogmSqn lastRef
|
||||
2ECE1A4E mlc1000 nA A A A A 612 212 733+784 21 e2bd709 fd70:2ece:1a4e:fa8e:fb9d:3b70:33e3:da00 eth1 2ECE1A4E mlc1000 999M 1 36 0
|
||||
01662D16 mlc1001 nQ A A A A 612 213 733+784 21 e2bd709 fd70:166:2d16:1ff6:253f:d0bc:1558:d89a --- --- --- 257G 0 36 0
|
||||
AAD9C0F5 mlc1002 nA A A A A 612 212 733+784 21 e2bd709 fd70:aad9:c0f5:8c20:a082:a462:a859:210d eth1 AAD9C0F5 mlc1002 999M 1 36 0
|
||||
DD57B855 mlc1003 pA A A A A 612 203 733+784 21 e2bd709 fd70:dd57:b855:3cdf:b057:10cc:2a93:c19 eth1 AAD9C0F5 mlc1002 706M 2 36 1
|
||||
369C6293 mlc1004 pA A A A A 612 200 733+784 21 e2bd709 fd70:369c:6293:4199:c156:3bb8:2c6a:e3aa eth1 AAD9C0F5 mlc1002 576M 3 36 1
|
||||
0BE5272C mlc1005 pA A A A A 612 200 733+784 21 e2bd709 fd70:be5:272c:703e:822a:e0c5:5d6c:587d eth1 AAD9C0F5 mlc1002 495M 4 36 1
|
||||
DDC8E9EF mlc1006 pA A A A A 612 193 733+784 21 e2bd709 fd70:ddc8:e9ef:4ff0:385e:b034:6fd0:b5f eth1 AAD9C0F5 mlc1002 443M 5 36 0
|
||||
6F59035D mlc1007 pA A A A A 612 188 733+784 21 e2bd709 fd70:6f59:35d:ae9b:1d55:3066:b3f9:74c7 eth1 AAD9C0F5 mlc1002 403M 6 36 0
|
||||
BF335A96 mlc1008 pA A A A A 612 178 733+784 21 e2bd709 fd70:bf33:5a96:889d:eedd:767b:6ca9:42fb eth1 AAD9C0F5 mlc1002 373M 7 36 0
|
||||
1191C909 mlc1009 pA A A A A 612 184 733+784 21 e2bd709 fd70:1191:c909:1e4e:4c9c:4d4a:33eb:b09b eth1 AAD9C0F5 mlc1002 349M 8 35 6
|
||||
2ECE1A4E mlc1000 nA A A A A 612 212 733+784 21 e2bd709 fd70:2ece:1a4e:fa8e:fb9d:3b70:33e3:da00 eth1 2ECE1A4E mlc1000 999M 1 36 0
|
||||
01662D16 mlc1001 nQ A A A A 612 213 733+784 21 e2bd709 fd70:166:2d16:1ff6:253f:d0bc:1558:d89a --- --- --- 257G 0 36 0
|
||||
AAD9C0F5 mlc1002 nA A A A A 612 212 733+784 21 e2bd709 fd70:aad9:c0f5:8c20:a082:a462:a859:210d eth1 AAD9C0F5 mlc1002 999M 1 36 0
|
||||
DD57B855 mlc1003 pA A A A A 612 203 733+784 21 e2bd709 fd70:dd57:b855:3cdf:b057:10cc:2a93:c19 eth1 AAD9C0F5 mlc1002 706M 2 36 1
|
||||
369C6293 mlc1004 pA A A A A 612 200 733+784 21 e2bd709 fd70:369c:6293:4199:c156:3bb8:2c6a:e3aa eth1 AAD9C0F5 mlc1002 576M 3 36 1
|
||||
0BE5272C mlc1005 pA A A A A 612 200 733+784 21 e2bd709 fd70:be5:272c:703e:822a:e0c5:5d6c:587d eth1 AAD9C0F5 mlc1002 495M 4 36 1
|
||||
DDC8E9EF mlc1006 pA A A A A 612 193 733+784 21 e2bd709 fd70:ddc8:e9ef:4ff0:385e:b034:6fd0:b5f eth1 AAD9C0F5 mlc1002 443M 5 36 0
|
||||
6F59035D mlc1007 pA A A A A 612 188 733+784 21 e2bd709 fd70:6f59:35d:ae9b:1d55:3066:b3f9:74c7 eth1 AAD9C0F5 mlc1002 403M 6 36 0
|
||||
BF335A96 mlc1008 pA A A A A 612 178 733+784 21 e2bd709 fd70:bf33:5a96:889d:eedd:767b:6ca9:42fb eth1 AAD9C0F5 mlc1002 373M 7 36 0
|
||||
1191C909 mlc1009 pA A A A A 612 184 733+784 21 e2bd709 fd70:1191:c909:1e4e:4c9c:4d4a:33eb:b09b eth1 AAD9C0F5 mlc1002 349M 8 35 6
|
||||
```
|
||||
|
||||
Only if relevant information exists for a requested type is available
|
||||
@@ -234,82 +231,4 @@ root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:301
|
||||
traceroute to fd66:66:66:0:a2cd:efff:fe10:301 (fd66:66:66:0:a2cd:efff:fe10:301), 30 hops max, 80 byte packets
|
||||
1 fd66:66:66:0:a2cd:efff:fe10:201 0.313 ms
|
||||
2 fd66:66:66:0:a2cd:efff:fe10:301 0.429 ms
|
||||
```
|
||||
|
||||
## Dynamic Reconfiguration
|
||||
|
||||
Most bmx7 parameters can be applied not only at startup, but also dynamically to an already running main daemon, using the `--connect` command.
|
||||
For example interfaces can be added, removed, or specified with more details:
|
||||
The following example removes interface eth1 and adds eth2 with a max rate of 100 Mbits (overwriting the default assumption of 1000Mbits for ethernet interfaces).
|
||||
|
||||
```
|
||||
bmx7 -c dev=-eth1 dev=eth2 /rateMax=100000
|
||||
bmx7 -cd8
|
||||
```
|
||||
|
||||
Checking new status of interfaces, links, and originator:
|
||||
|
||||
```
|
||||
root@mlc1001:~# bmx7 -cd8
|
||||
```
|
||||
|
||||
It can be seen that:
|
||||
|
||||
* Interface eth1 has been replaced by eth2 with a lower rate.
|
||||
* The old links (via eth1) are removed and a single new link via eth2 to mlc1000 has been detected
|
||||
* All routes are now going via eth2
|
||||
|
||||
|
||||
## Address auto and manual configuration
|
||||
|
||||
By default bmx7 autoconfigures all configred interface by combining a default prefix (fd70::/16) with
|
||||
the SHA224 hash of each nodes' public rsa key.
|
||||
|
||||
|
||||
|
||||
## Unicast Host Network Announcements
|
||||
|
||||
A Host Network Announcements (HNA) describes the advertisement of IP addresses and networks by a node to other nodes in the mesh.
|
||||
Typically (but not with BMX7), several nodes can announce the same or overlapping HNAs at the same time.
|
||||
Announced networks do overlap if they are equal or one being a subset of another (eg. 10.1.1.0/24 is a subset and overlapped by 10.1.0.0/16).
|
||||
Packets with a destination address matching an announced networks will be routed toward any node that originated a corresponding HNA.
|
||||
Therefore these HNA types may also be called anycast HNA.
|
||||
|
||||
In bmx7, HNAs have an unicast nature (UHNAs) because each network can only be announced once and announced networks MUST NOT overlap (See also Wiki).
|
||||
This way it can be ensured that the destination of an UHNA routed packet is exactly known.
|
||||
|
||||
In a sense the origination and propagation (by intermediate nodes) of UHNA announcements can be thought of a promise that guarantees:
|
||||
1. All packets with a destination address matching an announced UHNA network will be routed exactly to the node (with the global ID) that originated the UHNA and
|
||||
2. each node on the forwarding path towards the originator of the UHNA is supporting this promise.
|
||||
|
||||
By default, Bmx7 only announces primary addresses via UHNAs.
|
||||
The cryptographic address configuration ensures that interface addresses are unique.
|
||||
|
||||
Using UHNAs for the announcements of networks requires a strict coordination to ensure that no network is announced twice.
|
||||
|
||||
Technically, multiple UHNAs, each wrapped into a single message, are aggregated into a UHNA frame and attached to the description of a node.
|
||||
Only IPv6 UHNAs can be announced.
|
||||
|
||||
The announcement of UHNAs can be configured with the `--unicastHna` or `-u` parameter followed by a network specification in ip/prefixlen notation.
|
||||
By default all interface addresses are announced via UHNAs. However, this can be disabled by setting the `--dev` subparameter `/announce` or `/a` to 0.
|
||||
|
||||
The following example reconfigures an already running bmx7 daemon to UHNA announce the network fd00:ffff:ffff:ffff::/64 and fd01:ffff:ffff::/48.
|
||||
By omitting the `--connect / -c` parameter, the same could be configured as startup parameter for bmx7.
|
||||
|
||||
```
|
||||
bmx7 -c u=fd00:ffff:ffff:ffff::/64 u=fd01:ffff:ffff::/48
|
||||
```
|
||||
|
||||
An already active announcement can be removed by preceeding the network with the `-` char:
|
||||
```
|
||||
bmx7 -c u=-fd00:ffff:ffff:ffff::/64
|
||||
```
|
||||
|
||||
Before bmx7 accepts a dynamically configured UHNA announcement it checks if this UHNA is not overlapping with an already existing UHNA announcement form another node.
|
||||
If this is the case the configuration will fail.
|
||||
To check if a chain of dynamic commands would be accepted by a bmx7 daemon without actually applying it, the `--test` command may follow the `--connect` command.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
``
|
||||
|
||||
Reference in New Issue
Block a user