bmx7-r2018122901.tar.gz

# BMX7 Bmx7 is a mesh routing protocol for Linux based operating systems. The following intro provides kind of tutorial to get started. ## Content * [Installation](#installation) * [Installing in OpenWRT](#installing-in-openwrt) * [Usage (hello mesh)](#usage-hello-mesh) * [Concepts](#concepts) * [Autoconfiguration](#address-auto-and-manual-configuration) * [Unicast Host Network Announcements (UHNA)](#unicast-host-network-announcements-uhna) * [Tunnel Announcements](#tunnel-announcements) * [Bmx7 Plugins](#bmx7-plugins) * [Config Plugin](#config-plugin) * [Json Plugin](#json-plugin) * [SMS Plugin](#sms-plugin) * [Table plugin](#table-plugin) Note: This document is written using Markdown syntax. Modifications should be synced via README.md file in bmx7 repositories at [github][github]. Nice syntax examples are [here][syntax]. [bmx7]: http://bmx6.net [github]: https://github.com/bmx-routing/bmx7 [syntax]: http://daringfireball.net/projects/markdown/syntax.text ## Installation ## ### Requirements ### The following tools and libraries are needed to obtain, compile, and install bmx7: * git (debian package: git-core) * gcc * make * build-essential * libjson-c-dev zlib1g-dev libiw-dev * libmbedtls-dev ( or mbedtls-2.4.0 from https://tls.mbed.org/download/mbedtls-2.4.0-gpl.tgz) Optional for static configuration: * uci-0.7.5 from http://downloads.openwrt.org/sources/uci-0.7.5.tar.gz The following Linux-kernel modules are needed (depending on used bmx7 features) * ipv6 * tunnel6 * ip6_tunnel The mbed TLS or PolarSSL crypto library is needed for cryptographic operations: Most tested with debian or mbedtls-2.4.0: <pre> wget https://tls.mbed.org/download/mbedtls-2.4.0-gpl.tgz tar xzvf mbedtls-2.4.0-gpl.tgz cd mbedtls-2.4.0 make sudo make install # compile bmx7 with: make EXTRA_CFLAGS="-DCRYPTLIB=MBEDTLS_2_4_0" </pre> ### Downloading Latest development sources are available from bmx7 git repository: <pre> git clone https://github.com/bmx-routing/bmx7.git cd bmx7 </pre> ### Compile and Install To only compile the main bmx7 daemon (no bmx7 plugins): <pre> make EXTRA_CFLAGS="-DCRYPTLIB=MBEDTLS_2_4_0" sudo make install </pre> ## Installing in OpenWRT Bmx7 is currently in the official OpenWRT-routing feed, so to install it from a existing system you can use opkg: <pre> opkg install bmx7 bmx7-uci-config </pre> If you are compiling your own OpenWRT, you can add the routing feed (already enabled by default) which can be found here: https://github.com/openwrt-routing/packages Then run "make menuconfig" and select the bmx7 package in Networking -> Routing and redirection It is recommended to select also, at least, the uci plugin (bmx7-uci-config) You can select "luci-app-bmx7" to have a nice web interface for manage and monitorize the routing daemon. Finally type "make" to build the image. ## Usage (hello mesh) ### Starting In the most simple configuration, the only required parameter are the interfaces names that should be used for meshing. The following example starts bmx7 on interface wlan0: <pre> root@mlc1001:~# bmx7 dev=eth1 </pre> However, to let this simple command work as expected also check the following basic requirements: * `bmx7` must be executed in root context (with super user permissions). If you are not already root, prepend all commands with sudo (eg: `sudo bmx7 dev=eth1` ). * No IP address needs to be configured. By default bmx7 assumes IPv6 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`. If you are using a wireless interface, the interface settings must have been configured using `iwconfig` or `iw` to communicate with bmx7 daemons running on other nodes. This is a typical configuration for a wireless mesh setup: <pre>iwconfig wlan0 mode ad-hoc ap 02:ca:ff:ee:ba:be channel 11 essid my-mesh-network</pre> * Bmx7 (by default) works in daemon mode, thus sends itself to background and gives back a prompt. To let it run in foreground specify a debug level with the startup command like: <pre> bmx7 debug=0 dev=eth1 </pre> Of course, you may need to kill a previously started bmx7 daemon beforehand (`killall bmx7`) If everything went fine bmx7 is running now, searches for neighboring bmx7 daemons via the configured interface (link), and coordinates with them to learn about existence-of and routes-to all other bmx7 nodes in the network. ### Monitoring bmx7 ### To access debug and status information of a running bmx7 daemon, a second bmx7 process can be launched in client mode (with the `--connect` or `-c` parameter) to connect to the main bmx7 daemon and retrieve the desired information. In the following, a few example will be discussed. Continuous debug levels with different verbosity and scope are accessible with the `--debug` or `-d` parameter. * Debug level 0 only reports critical events * Debug level 3 reports relevant changes and * Debug level 4 reports everything. * Debug level 12 dump in and outgoing protocol traffic For example, `bmx7 -cd3` runs a bmx7 client process at debug level 3, connected to the main daemon and logs the output to stdout until terminated with `ctrl-c`. Status, network, and statistic information are also accessible via their own parameters: * `parameters` * `status` * `interfaces` * `links` * `originators` * `descriptions`, plus optional sub-parameters for filtering * `tunnels` (only with bmx7_tun.so plugin) * `traffic=DEV` where DEV:=`all`, `eth1`, etc. <pre> root@mlc1001:~# bmx7 -c show=status STATUS: shortId name nodeKey cv revision primaryIp tun6Address tun4Address uptime cpu txQ nbs rts nodes 01662D16 mlc1001 RSA2048 21 0abee1e fd70:166:2d16:1ff6:253f:d0bc:1558:d89a 2013:0:0:1001::1/64 10.20.1.1/24 0:00:11:43 0.1 4/50 2 9 10/10 </pre> As can be seen, the status reveals: * shortId: the short form of the node's [Global ID](wiki#global-id) * name: the hostname of the node * nodeKey: the key type and strength of its public RSA key * cv: compatibility version * revision: the git revision of the used source code * primaryIP: its primary cryptographically generated IPv6 address * uptime: the time since when it is running * cpu: its current cpu consumption (0.1%) * nbs: the number of neighbors perceived by this node * rts: the number of routes to other nodes * nodes: the total number of known and fully resolved nodes (including itself) These desired types can be combined. Also the above given example shows kind of shortcut. The long argument would be: `bmx7 connect show=status`. A more informative case using the long form would be: <pre> root@mlc1001:~# bmx7 -c parameters show=status show=interfaces show=links show=originators show=tunnels PARAMETERS: plugin bmx7_config.so (0) plugin bmx7_sms.so (0) plugin bmx7_tun.so (0) plugin bmx7_topology.so (0) plugin bmx7_table.so (0) dev eth1 (0) dev eth2 (0) unicastHna 2013:0:0:1001::/64 (0) tunDev default (0) /tun4Address 10.20.1.1/24 (0) /tun6Address 2013:0:0:1001::1/64 (0) tunOut ip6 (0) /network 2013::/16 (0) tunOut ip4 (0) /network 10.20.0.0/16 (0) STATUS: shortId name nodeKey cv revision primaryIp tun6Address tun4Address uptime cpu txQ nbs rts nodes 01662D16 mlc1001 RSA2048 21 e2bd709 fd70:166:2d16:1ff6:253f:d0bc:1558:d89a 2013:0:0:1001::1/64 10.20.1.1/24 0:00:03:34 0.2 0/50 2 9