1BATCTL(8) B.A.T.M.A.N. Advanced Control Tool BATCTL(8)
2
6 batctl - B.A.T.M.A.N. advanced control and management tool
7
9 batctl [options] command|debug table|debug JSON [parameters]
10
12 batctl offers a convenient way to configure the batman-adv kernel mod‐
13 ule as well as displaying debug information such as originator tables
14 and translation tables. In combination with a bat-hosts file batctl al‐
15 lows the use of host names instead of MAC addresses.
16 B.A.T.M.A.N. advanced operates on layer 2. Thus all hosts participating
18 in the virtual switched network are transparently connected together
19 for all protocols above layer 2. Therefore the common diagnosis tools
20 do not work as expected. To overcome these problems batctl contains the
21 commands ping, traceroute, tcpdump which provide similar functionality
22 to the normal ping(1), traceroute(1), tcpdump(1) commands, but modified
23 to layer 2 behaviour or using the B.A.T.M.A.N. advanced protocol. For
24 similar reasons, throughputmeter, a command to test network perfor‐
25 mances, is also included.
26
29 -m specify mesh interface (default 'bat0')
30 -h print general batctl help
32 -v print batctl version and batman-adv version (if the module is
34 loaded)
35
38 bisect_iv [-l MAC][-t MAC][-r MAC][-s min [- max]][-o MAC][-n] logfile1
39 ...
40 Analyses the B.A.T.M.A.N. IV logfiles to build a small internal
41 database of all sent sequence numbers and routing table changes.
42 This database can then be analyzed in a number of different
43 ways. With "-l" the database can be used to search for routing
44 loops. Use "-t" to trace OGMs of a host throughout the network.
45 Use "-r" to display routing tables of the nodes. The option "-s"
46 can be used to limit the output to a range of sequence numbers,
47 between min and max, or to one specific sequence number, min.
48 Furthermore using "-o" you can filter the output to a specified
49 originator. If "-n" is given batctl will not replace the MAC ad‐
50 dresses with bat-host names in the output.
51 event|e [-t|-r]
53 batctl will monitor for events from the netlink kernel interface
54 of batman-adv. The local timestamp of the event will be printed
55 when parameter -t is specified. Parameter -r will do the same
56 but with relative timestamps.
57 [meshif netdev] interface|if
59 [meshif netdev] interface|if [-M] add|del iface ...
60 If no parameter is given or the first parameter is neither "add"
61 nor "del" the current interface settings are displayed. In or‐
62 der to add or delete interfaces specify "add" or "del" as first
63 argument and append the interface names you wish to add or
64 delete. Multiple interfaces can be specified. The "-M" option
65 tells batctl to not automatically create the batman-adv inter‐
66 face on "add". It can also be used to suppress the warning about
67 the manual destruction when "del" removed all interfaces which
68 belonged to it.
69 [meshif netdev] interface|if create [routing_algo|ra RA_NAME]
71 A batman-adv interface without attached interfaces can be cre‐
72 ated using "create". The parameter routing_algo can be used to
73 overwrite the (default) routing algorithm.
74 [meshif netdev] interface|if destroy
76 Remove all attached interfaces and destroy the batman-adv inter‐
77 face.
78 [meshif netdev] ping|p [-c count][-i interval][-t time][-R][-T] MAC_ad‐
80 dress|bat-host_name|host_name|IP_address
81 Layer 2 ping of a MAC address or bat-host name. batctl will try
82 to find the bat-host name if the given parameter was not a MAC
83 address. It can also try to guess the MAC address using an
84 IPv4/IPv6 address or a hostname when the IPv4/IPv6 address was
85 configured on top of the batman-adv interface of the destination
86 device and both source and destination devices are in the same
87 IP subnet. The "-c" option tells batctl how man pings should be
88 sent before the program exits. Without the "-c" option batctl
89 will continue pinging without end. Use CTRL + C to stop it.
90 With "-i" and "-t" you can set the default interval between
91 pings and the timeout time for replies, both in seconds. When
92 run with "-R", the route taken by the ping messages will be
93 recorded. With "-T" you can disable the automatic translation of
94 a client MAC address to the originator address which is respon‐
95 sible for this client.
96 routing_algo|ra [algorithm]
98 If no parameter is given the current routing algorithm configu‐
99 ration as well as supported routing algorithms are displayed.
100 Otherwise the parameter is used to select the routing algorithm
101 for the following batX interface to be created.
102 [meshif netdev] statistics|s
104 Retrieve traffic counters from batman-adv kernel module. The
105 output may vary depending on which features have been compiled
106 into the kernel module.
107 Each module subsystem has its own counters which are indicated
108 by their prefixes:
109 mgmt mesh protocol counters
111 tt translation table counters
112 All counters without a prefix concern payload (pure user data)
113 traffic.
114 tcpdump|td [-c][-n][-p filter][-x filter] interface ...
116 batctl will display all packets that are seen on the given in‐
117 terface(s). A variety of options to filter the output are avail‐
118 able: To only print packets that match the compatibility number
119 of batctl specify the "-c" (compat filter) option. If "-n" is
120 given batctl will not replace the MAC addresses with bat-host
121 names in the output. To filter the shown packet types you can
122 either use "-p" (dump only specified packet types) or "-x" (dump
123 all packet types except specified). The following packet types
124 are available:
125 1 batman ogm packets
128 2 batman icmp packets
129 4 batman unicast packets
130 8 batman broadcast packets
131 16 batman unicast tvlv packets
132 32 batman fragmented packets
134 64 batman tt / roaming packets
135 128 non batman packets
136 Example: batctl td <interface> -p 129 -> only display batman ogm
137 packets and non batman packets
138 [meshif netdev] throughputmeter|tp MAC
140 This command starts a throughput test entirely controlled by
141 batman module in kernel space: the computational resources
142 needed to align memory and copy data between user and kernel
143 space that are required by other user space tools may represent
144 a bottleneck on some low profile device.
145 The test consist of the transfer of 14 MB of data between the
147 two nodes. The protocol used to transfer the data is somehow
148 similar to TCP, but simpler: some TCP features are still miss‐
149 ing, thus protocol performances could be worst. Since a fixed
150 amount of data is transferred the experiment duration depends on
151 the network conditions. The experiment can be interrupted with
152 CTRL + C. At the end of a successful experiment the throughput
153 in KBytes per second is returned, together with the experiment
154 duration in millisecond and the amount of bytes transferred. If
155 too many packets are lost or the specified MAC address is not
156 reachable, a message notifying the error is returned instead of
157 the result.
158 [meshif netdev] traceroute|tr [-n][-T] MAC_ad‐
160 dress|bat-host_name|host_name|IP_address
161 Layer 2 traceroute to a MAC address or bat-host name. batctl
162 will try to find the bat-host name if the given parameter was
163 not a MAC address. It can also try to guess the MAC address us‐
164 ing an IPv4/IPv6 address or a hostname when the IPv4/IPv6 ad‐
165 dress was configured on top of the batman-adv interface of the
166 destination device and both source and destination devices are
167 in the same IP subnet. batctl will send 3 packets to each host
168 and display the response time. If "-n" is given batctl will not
169 replace the MAC addresses with bat-host names in the output.
170 With "-T" you can disable the automatic translation of a client
171 MAC address to the originator address which is responsible for
172 this client.
173 [meshif netdev] translate|t MAC_address|bat-host_name|host_name|IP_ad‐
175 dress
176 Translates a destination (hostname, IP, MAC, bat_host-name) to
177 the originator mac address responsible for it.
178
181 [meshif netdev] aggregation|ag [0|1]
182 If no parameter is given the current aggregation setting is dis‐
183 played. Otherwise the parameter is used to enable or disable OGM
184 packet aggregation.
185 [meshif netdev] ap_isolation|ap [0|1]
187 If no parameter is given the current ap isolation setting is
188 displayed. Otherwise the parameter is used to enable or disable
189 ap isolation.
190 [meshif netdev] ap_isolation|ap [0|1]
192 [meshif netdev] vid <vid> ap_isolation|ap [0|1]
193 vlan vdev ap_isolation|ap [0|1]
194 If no parameter is given the current ap isolation setting for
195 the specified VLAN is displayed. Otherwise the parameter is used
196 to enable or disable ap isolation for the specified VLAN.
197 [meshif netdev] bonding|b [0|1]
199 If no parameter is given the current bonding mode setting is
200 displayed. Otherwise the parameter is used to enable or disable
201 the bonding mode.
202 [meshif netdev] bridge_loop_avoidance|bl [0|1]
204 If no parameter is given the current bridge loop avoidance set‐
205 ting is displayed. Otherwise the parameter is used to enable or
206 disable the bridge loop avoidance. Bridge loop avoidance support
207 has to be enabled when compiling the module otherwise this op‐
208 tion won't be available.
209 [meshif netdev] distributed_arp_table|dat [0|1]
211 If no parameter is given the current distributed arp table set‐
212 ting is displayed. Otherwise the parameter is used to enable or
213 disable the distributed arp table.
214 hardif hardif elp_interval|et [interval]
216 If no parameter is given the current ELP interval setting of the
217 hard interface is displayed otherwise the parameter is used to
218 set the ELP interval. The interval is in units of milliseconds.
219 [meshif netdev] fragmentation|f [0|1]
221 If no parameter is given the current fragmentation mode setting
222 is displayed. Otherwise the parameter is used to enable or dis‐
223 able fragmentation.
224 [meshif netdev] gw_mode|gw [off|client|server] [sel_class|bandwidth]
226 If no parameter is given the current gateway mode is displayed
227 otherwise the parameter is used to set the gateway mode. The
228 second (optional) argument specifies the selection class (if
229 'client' was the first argument) or the gateway bandwidth (if
230 'server' was the first argument). If the node is a server this
231 parameter is used to inform other nodes in the network about
232 this node's internet connection bandwidth. Just enter any number
233 (optionally followed by "kbit" or "mbit") and the batman-adv
234 module will propagate the entered value in the mesh. Use "/" to
235 separate the down‐ and upload rates. You can omit the upload
236 rate and the module will assume an upload of download / 5.
237 default: 10000 -> 10.0/2.0 MBit
238 examples: 5000 -> 5.0/1.0 MBit
239 5000kbit
240 5mbit
241 5mbit/1024
242 5mbit/1024kbit
243 5mbit/1mbit
244 If the node is a gateway client the parameter will decide which
245 criteria to consider when the batman-adv module has to choose
246 between different internet connections announced by the afore‐
247 mentioned servers.
248 B.A.T.M.A.N. IV:
249 default: 20 -> late switch (TQ 20)
250 examples: 1 -> fast connection
251 consider the gateway's advertised
252 throughput as well as the link quality
253 towards the gateway and stick with the
254 selection until the gateway disappears
255 2 -> stable connection
256 chooses the gateway with the best link
257 quality and sticks with it (ignore the
258 advertised throughput)
259 3 -> fast switch connection
260 chooses the gateway with the best link
261 quality but switches to another gateway
262 as soon as a better one is found
263 XX -> late switch connection
264 chooses the gateway with the best link
265 quality but switches to another gateway
266 as soon as a better one is found which
267 is at least XX TQ better than the cur‐
268 rently selected gateway (XX has to be a
269 number between 3 and 256).
270 B.A.T.M.A.N. V:
271 default: 5000 -> late switch (5000 kbit/s throughput)
272 example: 1500 -> fast switch connection
273 switches to another gateway as soon
274 as a better one is found which is at
275 least 1500 kbit/s faster throughput
276 than the currently selected gateway.
277 Throughput is determined by evaluat‐
278 ing which is lower: the advertised
279 throughput by the gateway or the max‐
280 imum bandwidth across the entire
281 path.
282 [meshif netdev] hop_penalty|hp [penalty]
284 If no parameter is given the current hop penalty setting is dis‐
285 played. Otherwise the parameter is used to set the hop penalty.
286 The penalty is can be 0-255 (255 sets originator message's TQ to
287 zero when forwarded by this hop).
288 [hardif hardif] hop_penalty|hp [penalty]
290 If no parameter is given the current hop penalty setting of the
291 hard interface is displayed. Otherwise the parameter is used to
292 set the hop penalty. The penalty can be 0-255 (255 sets origina‐
293 tor message's TQ to zero when forwarded over this interface).
294 [meshif netdev] isolation_mark|mark [value[/mask]]
296 If no parameter is given the current isolation mark value is
297 displayed. Otherwise the parameter is used to set or unset the
298 isolation mark used by the Extended Isolation feature.
299 The input is supposed to be of the form $value/$mask, where
300 $value can be any 32bit long integer (expressed in decimal or
301 hex base) and $mask is a generic bitmask (expressed in hex base)
302 that selects the bits to take into consideration from $value. It
303 is also possible to enter the input using only $value and in
304 this case the full bitmask is used by default.
305 Example 1: 0x00000001/0xffffffff
307 Example 2: 0x00040000/0xffff0000
308 Example 3: 16 or 0x0F
309 [meshif netdev] loglevel|ll [level ...]
311 If no parameter is given the current log level settings are dis‐
312 played otherwise the parameter(s) is/are used to set the log
313 level. Level 'none' disables all verbose logging. Level 'batman'
314 enables messages related to routing / flooding / broadcasting.
315 Level 'routes' enables messages related to routes being added /
316 changed / deleted. Level 'tt' enables messages related to trans‐
317 lation table operations. Level 'bla' enables messages related to
318 the bridge loop avoidance. Level 'dat' enables messages related
319 to ARP snooping and the Distributed Arp Table. Level 'nc' en‐
320 ables messages related to network coding. Level 'mcast' enables
321 messages related to multicast optimizations. Level 'tp' enables
322 messages related to throughput meter. Level 'all' enables all
323 messages. The messages are sent to the kernels trace buffers.
324 Use trace-cmd stream -e batadv:batadv_dbg to receive the system
325 wide log messages.
326 [meshif netdev] multicast_fanout|mo [fanout]
328 If no parameter is given the current multicast fanout setting is
329 displayed. Otherwise the parameter is used to set the multicast
330 fanout. The multicast fanout defines the maximum number of
331 packet copies that may be generated for a multicast-to-unicast
332 conversion. Once this limit is exceeded distribution will fall
333 back to broadcast.
334 [meshif netdev] multicast_forceflood|mff [0|1]
336 If no parameter is given the current multicast forceflood set‐
337 ting is displayed. Otherwise the parameter is used to enable or
338 disable multicast forceflood. This setting defines whether mul‐
339 ticast optimizations should be replaced by simple broadcast-like
340 flooding of multicast packets. If set to non-zero then all nodes
341 in the mesh are going to use classic flooding for any multicast
342 packet with no optimizations.
343 [meshif netdev] network_coding|nc [0|1]
345 If no parameter is given the current network coding mode setting
346 is displayed. Otherwise the parameter is used to enable or dis‐
347 able network coding.
348 [meshif netdev] orig_interval|it [interval]
350 If no parameter is given the current originator interval setting
351 is displayed otherwise the parameter is used to set the origina‐
352 tor interval. The interval is in units of milliseconds.
353 hardif hardif throughput_override|to [bandwidth]
355 If no parameter is given the current througput override is dis‐
356 played otherwise the parameter is used to set the throughput
357 override for the specified hard interface. Just enter any num‐
358 ber (optionally followed by "kbit" or "mbit").
359
362 The batman-adv kernel module comes with a variety of debug tables con‐
363 taining various information about the state of the mesh seen by each
364 individual node.
365 All of the debug tables support the following options:
367 -w refresh the list every second or add a number to let it refresh
369 at a custom interval in seconds (with optional decimal places)
370 -n do not replace the MAC addresses with bat-host names in the out‐
372 put
373 -H do not show the header of the debug table
375 The originator table also supports the "-t" filter option to remove all
378 originators from the output that have not been seen for the specified
379 amount of seconds (with optional decimal places). It furthermore sup‐
380 ports the "-i" parameter to specify an interface for which the origina‐
381 tor table should be printed. If this parameter is not supplied, the de‐
382 fault originator table is printed.
383 The local and global translation tables also support the "-u" and "-m"
385 option to only display unicast or multicast translation table announce‐
386 ments respectively.
387 [meshif netdev] backbonetable|bbt [-n] [-H] [-w interval]
390 (compile time option)
391 [meshif netdev] claimtable|cl [-n] [-H] [-w interval]
393 [meshif netdev] dat_cache|dc [-n] [-H] [-w interval]
395 (compile time option)
396 [meshif netdev] gateways|gwl [-n] [-H] [-w interval]
398 [meshif netdev] mcast_flags|mf [-n] [-H] [-w interval]
400 (compile time option)
401 [meshif netdev] neighbors|n [-n] [-H] [-w interval]
403 [meshif netdev] originators|o [-n] [-H] [-w interval] [-t timeout_in‐
405 terval] [-i interface]
406 [meshif netdev] transglobal|tg [-n] [-H] [-w interval] [-u] [-m]
408 (compile time option)
409 [meshif netdev] translocal|tl [-n] [-H] [-w interval] [-u] [-m]
411
414 The generic netlink family provided by the batman-adv kernel module can
415 be queried (read-only) by batctl and automatically translated to JSON.
416 This can be used to monitor the state of the system without the need of
417 parsing the freeform debug tables or the native netlink messages.
418 [meshif netdev] bla_backbone_json|bbj
421 [meshif netdev] bla_claim_json|clj
423 [meshif netdev] dat_cache_json|dcj
425 [meshif netdev] gateways_json|gwj
427 hardif hardif hardif_json|hj
429 [meshif netdev] hardifs_json|hj
431 [meshif netdev] mcast_flags_json|mfj
433 [meshif netdev] mesh_json|mj
435 [meshif netdev] neighbors_json|nj
437 [meshif netdev] originators_json|oj
439 [meshif netdev] transtable_global_json|tgj
441 [meshif netdev] transtable_local_json|tlj
443 [meshif netdev] vid <vid> vlan_json|vj
445 vlan vdev vlan_json|vj
446
449 The setup of a batadv interface usually consists of creation of the the
450 main interface, attaching of the (lower) hard-interface, adjusting of
451 settings and bringup of the interface:
452 # create batadv (mesh) interface bat0 with routing algorithm B.A.T.M.A.N. IV
454 $ batctl meshif bat0 interface create routing_algo BATMAN_IV
455 # add the (already up and running) mesh0 interface as lower (hard) interface to bat0
456 $ batctl meshif bat0 interface -M add mesh0
457 # change some settings to better match the requirements of the user
458 $ batctl meshif bat0 orig_interval 5000
459 $ batctl meshif bat0 distributed_arp_table disable
460 ...
461 # set the batadv (mesh) interface up before it is possible to use it
462 $ ip link set up dev bat0
463 This only makes sure that the layer 2 functionality of bat0 is started
465 up. It is the responsibility of the user to make sure that the bat0 de‐
466 vice itself gets attached to a bridge, configured with an IP address
467 (manually/DHCP client/...) or integrated in other parts of the system
468 before it gets used.
469 Also the attached (lower) hard-interfaces attached to the batadv inter‐
471 face must be configured by the user to support transportation of ether‐
472 net unicast and broadcast packets between its linked peers. The most
473 common reason for a not working batman-adv mesh are incorrect configu‐
474 rations of the hard-interfaces, hardware, firmware or driver bugs which
475 prevent that some of the packet types are correctly exchanged.
476 The current status of interface can be checked using the debug tables.
478 It is often relevant to check from which direct neighbors discovery
479 packets were received. The next step is to check the (preferred)
480 routes to originators. These will only be established when the metric
481 has detected bidirectional connections between neighbors and might have
482 forwarded discovery packets from not directly reachable nodes/origina‐
483 tors.
484 # get list of neighbors from which the current node was able to receive discovery packets
486 $ batctl meshif bat0 neighbors
487 # get (preferred) routes the routing algorithm found
488 $ batctl meshif bat0 originators
489 If the bat0 interface should no longer used by the system, it can be
491 destroyed again:
492 # destroy the interface and let the system remove its state
494 $ batctl meshif bat0 interface destroy
495
498 bat-hosts
499 This file is similar to the /etc/hosts file. You can write one
500 MAC address and one host name per line. batctl will search for
501 bat-hosts in /etc, your home directory and the current direc‐
502 tory. The found data is used to match MAC address to your pro‐
503 vided host name or replace MAC addresses in debug output and
504 logs. Host names are much easier to remember than MAC addresses.
505
508 bridge(8), dmesg(1), ip(8), ip-link(8), ping(8), tcpdump(8), tracer‐
509 oute(1), trace-cmd(1)
510
512 batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lind‐
513 ner <mareklindner@neomailbox.ch>.
514 This manual page was written by Simon Wunderlich <sw@simonwunder‐
516 lich.de>, Marek Lindner <mareklindner@neomailbox.ch> and Andrew Lunn
517 <andrew@lunn.ch>
518Linux July 17, 2015 BATCTL(8)