blob: c1d82047a4b151c35983656e5841e261ff22fd7f [file] [log] [blame]
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +00001BATMAN-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
Antonio Quartulli2dafb492011-05-05 08:42:45 +020020
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000021CONFIGURATION
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
Simon Wunderlich23721382012-01-22 20:00:19 +010068# ls /sys/class/net/bat0/mesh/
Sven Eckelmanna77e8c62012-04-02 19:31:26 +020069# aggregated_ogms gw_bandwidth log_level
70# ap_isolation gw_mode orig_interval
71# bonding gw_sel_class routing_algo
72# bridge_loop_avoidance hop_penalty vis_mode
73# fragmentation
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000074
75
Sylvestre Ledruf65e51d2011-04-04 15:04:46 -070076There is a special folder for debugging information:
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000077
Simon Wunderlich536a23f2012-06-18 18:39:26 +020078# ls /sys/kernel/debug/batman_adv/bat0/
79# bla_backbone_table log transtable_global
80# bla_claim_table originators transtable_local
81# gateways socket vis_data
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000082
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
Antonio Quartulli2dafb492011-05-05 08:42:45 +0200164-> "TT mac" - TT announced by source mac
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000165-> "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.
Antonio Quartulli2dafb492011-05-05 08:42:45 +0200170The TT entries are showing which hosts are connected to the mesh
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000171via 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
Marek Lindner1a984892011-08-30 13:32:33 +02002032 - Enable messages related to route added / changed / deleted
2044 - Enable messages related to translation table operations
Simon Wunderlich23721382012-01-22 20:00:19 +01002058 - Enable messages related to bridge loop avoidance
Antonio Quartulli0e861a32012-10-01 09:57:36 +020020616 - Enable messaged related to DAT, ARP snooping and parsing
20731 - Enable all messages
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000208
209The debug output can be changed at runtime using the file
210/sys/class/net/bat0/mesh/log_level. e.g.
211
Simon Wunderlich23721382012-01-22 20:00:19 +0100212# echo 6 > /sys/class/net/bat0/mesh/log_level
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000213
Marek Lindner1a984892011-08-30 13:32:33 +0200214will enable debug messages for when routes change.
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000215
Martin Hundebøllf8214862012-04-20 17:02:45 +0200216Counters for different types of packets entering and leaving the
217batman-adv module are available through ethtool:
218
219# ethtool --statistics bat0
220
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000221
222BATCTL
223------
224
225As batman advanced operates on layer 2 all hosts participating in
226the virtual switch are completely transparent for all protocols
227above layer 2. Therefore the common diagnosis tools do not work
228as expected. To overcome these problems batctl was created. At
229the moment the batctl contains ping, traceroute, tcpdump and
230interfaces to the kernel module settings.
231
232For more information, please see the manpage (man batctl).
233
234batctl is available on http://www.open-mesh.org/
235
236
237CONTACT
238-------
239
240Please send us comments, experiences, questions, anything :)
241
242IRC: #batman on irc.freenode.org
Sven Eckelmann091b9482011-01-27 10:56:56 +0100243Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription
244 at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000245
246You can also contact the Authors:
247
248Marek Lindner <lindner_marek@yahoo.de>
249Simon Wunderlich <siwu@hrz.tu-chemnitz.de>