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