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
46To activate a  given  interface  simply  write  "bat0"  into  its
47"mesh_iface" file inside the batman_adv subfolder:
48
49# echo bat0 > /sys/class/net/eth0/batman_adv/mesh_iface
50
51Repeat  this step for all interfaces you wish to add.  Now batman
52starts using/broadcasting on this/these interface(s).
53
54By reading the "iface_status" file you can check its status:
55
56# cat /sys/class/net/eth0/batman_adv/iface_status
57# active
58
59To deactivate an interface you have  to  write  "none"  into  its
60"mesh_iface" file:
61
62# echo none > /sys/class/net/eth0/batman_adv/mesh_iface
63
64
65All  mesh  wide  settings  can be found in batman's own interface
66folder:
67
68# ls /sys/class/net/bat0/mesh/
69#aggregated_ogms        distributed_arp_table  gw_sel_class    orig_interval
70#ap_isolation           fragmentation          hop_penalty     routing_algo
71#bonding                gw_bandwidth           isolation_mark  vlan0
72#bridge_loop_avoidance  gw_mode                log_level
73
74There is a special folder for debugging information:
75
76# ls /sys/kernel/debug/batman_adv/bat0/
77# bla_backbone_table  log                 transtable_global
78# bla_claim_table     originators         transtable_local
79# gateways            socket
80
81Some of the files contain all sort of status information  regard-
82ing  the  mesh  network.  For  example, you can view the table of
83originators (mesh participants) with:
84
85# cat /sys/kernel/debug/batman_adv/bat0/originators
86
87Other files allow to change batman's behaviour to better fit your
88requirements.  For instance, you can check the current originator
89interval (value in milliseconds which determines how often batman
90sends its broadcast packets):
91
92# cat /sys/class/net/bat0/mesh/orig_interval
93# 1000
94
95and also change its value:
96
97# echo 3000 > /sys/class/net/bat0/mesh/orig_interval
98
99In very mobile scenarios, you might want to adjust the originator
100interval to a lower value. This will make the mesh  more  respon-
101sive to topology changes, but will also increase the overhead.
102
103
104USAGE
105-----
106
107To  make use of your newly created mesh, batman advanced provides
108a new interface "bat0" which you should use from this  point  on.
109All  interfaces  added  to  batman  advanced are not relevant any
110longer because batman handles them for you. Basically, one "hands
111over" the data by using the batman interface and batman will make
112sure it reaches its destination.
113
114The "bat0" interface can be used like any  other  regular  inter-
115face.  It needs an IP address which can be either statically con-
116figured or dynamically (by using DHCP or similar services):
117
118# NodeA: ifconfig bat0 192.168.0.1
119# NodeB: ifconfig bat0 192.168.0.2
120# NodeB: ping 192.168.0.1
121
122Note:  In  order to avoid problems remove all IP addresses previ-
123ously assigned to interfaces now used by batman advanced, e.g.
124
125# ifconfig eth0 0.0.0.0
126
127
128LOGGING/DEBUGGING
129-----------------
130
131All error messages, warnings and information messages are sent to
132the kernel log. Depending on your operating  system  distribution
133this  can  be read in one of a number of ways. Try using the com-
134mands: dmesg, logread, or looking in the files  /var/log/kern.log
135or  /var/log/syslog.  All  batman-adv  messages are prefixed with
136"batman-adv:" So to see just these messages try
137
138# dmesg | grep batman-adv
139
140When investigating problems with your mesh network  it  is  some-
141times  necessary  to see more detail debug messages. This must be
142enabled when compiling the batman-adv module. When building  bat-
143man-adv  as  part of kernel, use "make menuconfig" and enable the
144option "B.A.T.M.A.N. debugging".
145
146Those additional  debug messages can be accessed  using a special
147file in debugfs
148
149# cat /sys/kernel/debug/batman_adv/bat0/log
150
151The additional debug output is by default disabled. It can be en-
152abled  during run time. Following log_levels are defined:
153
1540 - All  debug  output  disabled
1551 - Enable messages related to routing / flooding / broadcasting
1562 - Enable messages related to route added / changed / deleted
1574 - Enable messages related to translation table operations
1588 - Enable messages related to bridge loop avoidance
15916 - Enable messaged related to DAT, ARP snooping and parsing
16031 - Enable all messages
161
162The debug output can be changed at runtime  using  the  file
163/sys/class/net/bat0/mesh/log_level. e.g.
164
165# echo 6 > /sys/class/net/bat0/mesh/log_level
166
167will enable debug messages for when routes change.
168
169Counters for different types of packets entering and leaving the
170batman-adv module are available through ethtool:
171
172# ethtool --statistics bat0
173
174
175BATCTL
176------
177
178As batman advanced operates on layer 2 all hosts participating in
179the  virtual switch are completely transparent for all  protocols
180above layer 2. Therefore the common diagnosis tools do  not  work
181as  expected.  To  overcome these problems batctl was created. At
182the  moment the  batctl contains ping,  traceroute,  tcpdump  and
183interfaces to the kernel module settings.
184
185For more information, please see the manpage (man batctl).
186
187batctl is available on http://www.open-mesh.org/
188
189
190CONTACT
191-------
192
193Please send us comments, experiences, questions, anything :)
194
195IRC:            #batman   on   irc.freenode.org
196Mailing-list:   b.a.t.m.a.n@open-mesh.org (optional  subscription
197          at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
198
199You can also contact the Authors:
200
201Marek  Lindner  <mareklindner@neomailbox.ch>
202Simon  Wunderlich  <sw@simonwunderlich.de>
203