1[state: 21-08-2011] 2 3BATMAN-ADV 4---------- 5 6Batman advanced is a new approach to wireless networking which 7does no longer operate on the IP basis. Unlike the batman daemon, 8which exchanges information using UDP packets and sets routing 9tables, batman-advanced operates on ISO/OSI Layer 2 only and uses 10and routes (or better: bridges) Ethernet Frames. It emulates a 11virtual network switch of all nodes participating. Therefore all 12nodes appear to be link local, thus all higher operating proto- 13cols won't be affected by any changes within the network. You can 14run almost any protocol above batman advanced, prominent examples 15are: IPv4, IPv6, DHCP, IPX. 16 17Batman advanced was implemented as a Linux kernel driver to re- 18duce the overhead to a minimum. It does not depend on any (other) 19network driver, and can be used on wifi as well as ethernet lan, 20vpn, etc ... (anything with ethernet-style layer 2). 21 22 23CONFIGURATION 24------------- 25 26Load the batman-adv module into your kernel: 27 28# insmod batman-adv.ko 29 30The module is now waiting for activation. You must add some in- 31terfaces on which batman can operate. After loading the module 32batman advanced will scan your systems interfaces to search for 33compatible interfaces. Once found, it will create subfolders in 34the /sys directories of each supported interface, e.g. 35 36# ls /sys/class/net/eth0/batman_adv/ 37# iface_status mesh_iface 38 39If an interface does not have the "batman_adv" subfolder it prob- 40ably is not supported. Not supported interfaces are: loopback, 41non-ethernet and batman's own interfaces. 42 43Note: After the module was loaded it will continuously watch for 44new interfaces to verify the compatibility. There is no need to 45reload the module if you plug your USB wifi adapter into your ma- 46chine after batman advanced was initially loaded. 47 48To activate a given interface simply write "bat0" into its 49"mesh_iface" file inside the batman_adv subfolder: 50 51# echo bat0 > /sys/class/net/eth0/batman_adv/mesh_iface 52 53Repeat this step for all interfaces you wish to add. Now batman 54starts using/broadcasting on this/these interface(s). 55 56By reading the "iface_status" file you can check its status: 57 58# cat /sys/class/net/eth0/batman_adv/iface_status 59# active 60 61To deactivate an interface you have to write "none" into its 62"mesh_iface" file: 63 64# echo none > /sys/class/net/eth0/batman_adv/mesh_iface 65 66 67All mesh wide settings can be found in batman's own interface 68folder: 69 70# ls /sys/class/net/bat0/mesh/ 71# aggregated_ogms fragmentation gw_sel_class vis_mode 72# ap_isolation gw_bandwidth hop_penalty 73# bonding gw_mode orig_interval 74 75 76There is a special folder for debugging information: 77 78# ls /sys/kernel/debug/batman_adv/bat0/ 79# gateways socket transtable_global vis_data 80# originators softif_neigh transtable_local 81 82 83Some of the files contain all sort of status information regard- 84ing the mesh network. For example, you can view the table of 85originators (mesh participants) with: 86 87# cat /sys/kernel/debug/batman_adv/bat0/originators 88 89Other files allow to change batman's behaviour to better fit your 90requirements. For instance, you can check the current originator 91interval (value in milliseconds which determines how often batman 92sends its broadcast packets): 93 94# cat /sys/class/net/bat0/mesh/orig_interval 95# 1000 96 97and also change its value: 98 99# echo 3000 > /sys/class/net/bat0/mesh/orig_interval 100 101In very mobile scenarios, you might want to adjust the originator 102interval to a lower value. This will make the mesh more respon- 103sive to topology changes, but will also increase the overhead. 104 105 106USAGE 107----- 108 109To make use of your newly created mesh, batman advanced provides 110a new interface "bat0" which you should use from this point on. 111All interfaces added to batman advanced are not relevant any 112longer because batman handles them for you. Basically, one "hands 113over" the data by using the batman interface and batman will make 114sure it reaches its destination. 115 116The "bat0" interface can be used like any other regular inter- 117face. It needs an IP address which can be either statically con- 118figured or dynamically (by using DHCP or similar services): 119 120# NodeA: ifconfig bat0 192.168.0.1 121# NodeB: ifconfig bat0 192.168.0.2 122# NodeB: ping 192.168.0.1 123 124Note: In order to avoid problems remove all IP addresses previ- 125ously assigned to interfaces now used by batman advanced, e.g. 126 127# ifconfig eth0 0.0.0.0 128 129 130VISUALIZATION 131------------- 132 133If you want topology visualization, at least one mesh node must 134be configured as VIS-server: 135 136# echo "server" > /sys/class/net/bat0/mesh/vis_mode 137 138Each node is either configured as "server" or as "client" (de- 139fault: "client"). Clients send their topology data to the server 140next to them, and server synchronize with other servers. If there 141is no server configured (default) within the mesh, no topology 142information will be transmitted. With these "synchronizing 143servers", there can be 1 or more vis servers sharing the same (or 144at least very similar) data. 145 146When configured as server, you can get a topology snapshot of 147your mesh: 148 149# cat /sys/kernel/debug/batman_adv/bat0/vis_data 150 151This raw output is intended to be easily parsable and convertable 152with other tools. Have a look at the batctl README if you want a 153vis output in dot or json format for instance and how those out- 154puts could then be visualised in an image. 155 156The raw format consists of comma separated values per entry where 157each entry is giving information about a certain source inter- 158face. Each entry can/has to have the following values: 159-> "mac" - mac address of an originator's source interface 160 (each line begins with it) 161-> "TQ mac value" - src mac's link quality towards mac address 162 of a neighbor originator's interface which 163 is being used for routing 164-> "TT mac" - TT announced by source mac 165-> "PRIMARY" - this is a primary interface 166-> "SEC mac" - secondary mac address of source 167 (requires preceding PRIMARY) 168 169The TQ value has a range from 4 to 255 with 255 being the best. 170The TT entries are showing which hosts are connected to the mesh 171via bat0 or being bridged into the mesh network. The PRIMARY/SEC 172values are only applied on primary interfaces 173 174 175LOGGING/DEBUGGING 176----------------- 177 178All error messages, warnings and information messages are sent to 179the kernel log. Depending on your operating system distribution 180this can be read in one of a number of ways. Try using the com- 181mands: dmesg, logread, or looking in the files /var/log/kern.log 182or /var/log/syslog. All batman-adv messages are prefixed with 183"batman-adv:" So to see just these messages try 184 185# dmesg | grep batman-adv 186 187When investigating problems with your mesh network it is some- 188times necessary to see more detail debug messages. This must be 189enabled when compiling the batman-adv module. When building bat- 190man-adv as part of kernel, use "make menuconfig" and enable the 191option "B.A.T.M.A.N. debugging". 192 193Those additional debug messages can be accessed using a special 194file in debugfs 195 196# cat /sys/kernel/debug/batman_adv/bat0/log 197 198The additional debug output is by default disabled. It can be en- 199abled during run time. Following log_levels are defined: 200 2010 - All debug output disabled 2021 - Enable messages related to routing / flooding / broadcasting 2032 - Enable route or tt entry added / changed / deleted 2043 - Enable all messages 205 206The debug output can be changed at runtime using the file 207/sys/class/net/bat0/mesh/log_level. e.g. 208 209# echo 2 > /sys/class/net/bat0/mesh/log_level 210 211will enable debug messages for when routes or TTs change. 212 213 214BATCTL 215------ 216 217As batman advanced operates on layer 2 all hosts participating in 218the virtual switch are completely transparent for all protocols 219above layer 2. Therefore the common diagnosis tools do not work 220as expected. To overcome these problems batctl was created. At 221the moment the batctl contains ping, traceroute, tcpdump and 222interfaces to the kernel module settings. 223 224For more information, please see the manpage (man batctl). 225 226batctl is available on http://www.open-mesh.org/ 227 228 229CONTACT 230------- 231 232Please send us comments, experiences, questions, anything :) 233 234IRC: #batman on irc.freenode.org 235Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription 236 at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n) 237 238You can also contact the Authors: 239 240Marek Lindner <lindner_marek@yahoo.de> 241Simon Wunderlich <siwu@hrz.tu-chemnitz.de> 242