1BATMAN-ADV 2---------- 3 4Batman advanced is a new approach to wireless networking which 5does no longer operate on the IP basis. Unlike the batman daemon, 6which exchanges information using UDP packets and sets routing 7tables, batman-advanced operates on ISO/OSI Layer 2 only and uses 8and routes (or better: bridges) Ethernet Frames. It emulates a 9virtual network switch of all nodes participating. Therefore all 10nodes appear to be link local, thus all higher operating proto- 11cols won't be affected by any changes within the network. You can 12run almost any protocol above batman advanced, prominent examples 13are: IPv4, IPv6, DHCP, IPX. 14 15Batman advanced was implemented as a Linux kernel driver to re- 16duce the overhead to a minimum. It does not depend on any (other) 17network driver, and can be used on wifi as well as ethernet lan, 18vpn, etc ... (anything with ethernet-style layer 2). 19 20 21CONFIGURATION 22------------- 23 24Load the batman-adv module into your kernel: 25 26# insmod batman-adv.ko 27 28The module is now waiting for activation. You must add some in- 29terfaces on which batman can operate. After loading the module 30batman advanced will scan your systems interfaces to search for 31compatible interfaces. Once found, it will create subfolders in 32the /sys directories of each supported interface, e.g. 33 34# ls /sys/class/net/eth0/batman_adv/ 35# iface_status mesh_iface 36 37If an interface does not have the "batman_adv" subfolder it prob- 38ably is not supported. Not supported interfaces are: loopback, 39non-ethernet and batman's own interfaces. 40 41Note: After the module was loaded it will continuously watch for 42new interfaces to verify the compatibility. There is no need to 43reload the module if you plug your USB wifi adapter into your ma- 44chine after batman advanced was initially loaded. 45 46The batman-adv soft-interface can be created using the iproute2 47tool "ip" 48 49# ip link add name bat0 type batadv 50 51To activate a given interface simply attach it to the "bat0" 52interface 53 54# ip link set dev eth0 master bat0 55 56Repeat this step for all interfaces you wish to add. Now batman 57starts using/broadcasting on this/these interface(s). 58 59By reading the "iface_status" file you can check its status: 60 61# cat /sys/class/net/eth0/batman_adv/iface_status 62# active 63 64To deactivate an interface you have to detach it from the 65"bat0" interface: 66 67# ip link set dev eth0 nomaster 68 69 70All mesh wide settings can be found in batman's own interface 71folder: 72 73# ls /sys/class/net/bat0/mesh/ 74#aggregated_ogms distributed_arp_table gw_sel_class orig_interval 75#ap_isolation fragmentation hop_penalty routing_algo 76#bonding gw_bandwidth isolation_mark vlan0 77#bridge_loop_avoidance gw_mode log_level 78 79There is a special folder for debugging information: 80 81# ls /sys/kernel/debug/batman_adv/bat0/ 82# bla_backbone_table log transtable_global 83# bla_claim_table originators transtable_local 84# gateways socket 85 86Some of the files contain all sort of status information regard- 87ing the mesh network. For example, you can view the table of 88originators (mesh participants) with: 89 90# cat /sys/kernel/debug/batman_adv/bat0/originators 91 92Other files allow to change batman's behaviour to better fit your 93requirements. For instance, you can check the current originator 94interval (value in milliseconds which determines how often batman 95sends its broadcast packets): 96 97# cat /sys/class/net/bat0/mesh/orig_interval 98# 1000 99 100and also change its value: 101 102# echo 3000 > /sys/class/net/bat0/mesh/orig_interval 103 104In very mobile scenarios, you might want to adjust the originator 105interval to a lower value. This will make the mesh more respon- 106sive to topology changes, but will also increase the overhead. 107 108 109USAGE 110----- 111 112To make use of your newly created mesh, batman advanced provides 113a new interface "bat0" which you should use from this point on. 114All interfaces added to batman advanced are not relevant any 115longer because batman handles them for you. Basically, one "hands 116over" the data by using the batman interface and batman will make 117sure it reaches its destination. 118 119The "bat0" interface can be used like any other regular inter- 120face. It needs an IP address which can be either statically con- 121figured or dynamically (by using DHCP or similar services): 122 123# NodeA: ip link set up dev bat0 124# NodeA: ip addr add 192.168.0.1/24 dev bat0 125 126# NodeB: ip link set up dev bat0 127# NodeB: ip addr add 192.168.0.2/24 dev bat0 128# NodeB: ping 192.168.0.1 129 130Note: In order to avoid problems remove all IP addresses previ- 131ously assigned to interfaces now used by batman advanced, e.g. 132 133# ip addr flush dev eth0 134 135 136LOGGING/DEBUGGING 137----------------- 138 139All error messages, warnings and information messages are sent to 140the kernel log. Depending on your operating system distribution 141this can be read in one of a number of ways. Try using the com- 142mands: dmesg, logread, or looking in the files /var/log/kern.log 143or /var/log/syslog. All batman-adv messages are prefixed with 144"batman-adv:" So to see just these messages try 145 146# dmesg | grep batman-adv 147 148When investigating problems with your mesh network it is some- 149times necessary to see more detail debug messages. This must be 150enabled when compiling the batman-adv module. When building bat- 151man-adv as part of kernel, use "make menuconfig" and enable the 152option "B.A.T.M.A.N. debugging". 153 154Those additional debug messages can be accessed using a special 155file in debugfs 156 157# cat /sys/kernel/debug/batman_adv/bat0/log 158 159The additional debug output is by default disabled. It can be en- 160abled during run time. Following log_levels are defined: 161 1620 - All debug output disabled 1631 - Enable messages related to routing / flooding / broadcasting 1642 - Enable messages related to route added / changed / deleted 1654 - Enable messages related to translation table operations 1668 - Enable messages related to bridge loop avoidance 16716 - Enable messaged related to DAT, ARP snooping and parsing 16831 - Enable all messages 169 170The debug output can be changed at runtime using the file 171/sys/class/net/bat0/mesh/log_level. e.g. 172 173# echo 6 > /sys/class/net/bat0/mesh/log_level 174 175will enable debug messages for when routes change. 176 177Counters for different types of packets entering and leaving the 178batman-adv module are available through ethtool: 179 180# ethtool --statistics bat0 181 182 183BATCTL 184------ 185 186As batman advanced operates on layer 2 all hosts participating in 187the virtual switch are completely transparent for all protocols 188above layer 2. Therefore the common diagnosis tools do not work 189as expected. To overcome these problems batctl was created. At 190the moment the batctl contains ping, traceroute, tcpdump and 191interfaces to the kernel module settings. 192 193For more information, please see the manpage (man batctl). 194 195batctl is available on https://www.open-mesh.org/ 196 197 198CONTACT 199------- 200 201Please send us comments, experiences, questions, anything :) 202 203IRC: #batman on irc.freenode.org 204Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription 205 at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n) 206 207You can also contact the Authors: 208 209Marek Lindner <mareklindner@neomailbox.ch> 210Simon Wunderlich <sw@simonwunderlich.de> 211