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 options:
30 -m specify mesh interface (default 'bat0')
31 -h print general batctl help
32 -v print batctl version and batman-adv version (if the mod‐
33 ule is loaded)
34 commands:
36 [meshif <netdev>] interface|if [-M] [add|del iface(s)]
38 If no parameter is given or the first parameter is neither "add"
39 nor "del" the current interface settings are displayed. In or‐
40 der to add or delete interfaces specify "add" or "del" as first
41 argument and append the interface names you wish to add or
42 delete. Multiple interfaces can be specified. The "-M" option
43 tells batctl to not automatically create the batman-adv inter‐
44 face on "add". It can also be used to suppress the warning about
45 the manual destruction when "del" removed all interfaces which
46 belonged to it.
47 [meshif <netdev>] interface|if create [routing_algo|ra RA_NAME]
49 A batman-adv interface without attached interfaces can be cre‐
50 ated using "create". The parameter routing_algo can be used to
51 overwrite the (default) routing algorithm.
52 [meshif <netdev>] interface|if destroy
54 Remove all attached interfaces and destroy the batman-adv inter‐
55 face.
56 [meshif <netdev>] orig_interval|it [interval]
58 If no parameter is given the current originator interval setting
59 is displayed otherwise the parameter is used to set the origina‐
60 tor interval. The interval is in units of milliseconds.
61 [meshif <netdev>] ap_isolation|ap [0|1]
63 If no parameter is given the current ap isolation setting is
64 displayed. Otherwise the parameter is used to enable or disable
65 ap isolation.
66 <vlan <vdev>|[meshif <netdev>] vid <vid>> ap_isolation|ap [0|1]
68 If no parameter is given the current ap isolation setting for
69 the specified VLAN is displayed. Otherwise the parameter is used
70 to enable or disable ap isolation for the specified VLAN.
71 [meshif <netdev>] bridge_loop_avoidance|bl [0|1]
73 If no parameter is given the current bridge loop avoidance set‐
74 ting is displayed. Otherwise the parameter is used to enable or
75 disable the bridge loop avoidance. Bridge loop avoidance support
76 has to be enabled when compiling the module otherwise this op‐
77 tion won't be available.
78 [meshif <netdev>] distributed_arp_table|dat [0|1]
80 If no parameter is given the current distributed arp table set‐
81 ting is displayed. Otherwise the parameter is used to enable or
82 disable the distributed arp table.
83 [meshif <netdev>] aggregation|ag [0|1]
85 If no parameter is given the current aggregation setting is dis‐
86 played. Otherwise the parameter is used to enable or disable OGM
87 packet aggregation.
88 [meshif <netdev>] bonding|b [0|1]
90 If no parameter is given the current bonding mode setting is
91 displayed. Otherwise the parameter is used to enable or disable
92 the bonding mode.
93 event|e [-t|-r]
95 batctl will monitor for events from the netlink kernel interface
96 of batman-adv. The local timestamp of the event will be printed
97 when parameter -t is specified. Parameter -r will do the same
98 but with relative timestamps.
99 hardif <hardif> elp_interval|et [interval]
101 If no parameter is given the current ELP interval setting of the
102 hard interface is displayed otherwise the parameter is used to
103 set the ELP interval. The interval is in units of milliseconds.
104 [meshif <netdev>] fragmentation|f [0|1]
106 If no parameter is given the current fragmentation mode setting
107 is displayed. Otherwise the parameter is used to enable or dis‐
108 able fragmentation.
109 [meshif <netdev>] hop_penalty|hp [penalty]
111 If no parameter is given the current hop penalty setting is dis‐
112 played. Otherwise the parameter is used to set the hop penalty.
113 The penalty is can be 0-255 (255 sets originator message's TQ to
114 zero when forwarded by this hop).
115 [hardif <hardif>] hop_penalty|hp [penalty]
117 If no parameter is given the current hop penalty setting of the
118 hard interface is displayed. Otherwise the parameter is used to
119 set the hop penalty. The penalty can be 0-255 (255 sets origina‐
120 tor message's TQ to zero when forwarded over this interface).
121 [meshif <netdev>] network_coding|nc [0|1]
123 If no parameter is given the current network coding mode setting
124 is displayed. Otherwise the parameter is used to enable or dis‐
125 able network coding.
126 [meshif <netdev>] multicast_forceflood|mff [0|1]
128 If no parameter is given the current multicast forceflood set‐
129 ting is displayed. Otherwise the parameter is used to enable or
130 disable multicast forceflood. This setting defines whether mul‐
131 ticast optimizations should be replaced by simple broadcast-like
132 flooding of multicast packets. If set to non-zero then all nodes
133 in the mesh are going to use classic flooding for any multicast
134 packet with no optimizations.
135 [meshif <netdev>] multicast_fanout|mo [fanout]
137 If no parameter is given the current multicast fanout setting is
138 displayed. Otherwise the parameter is used to set the multicast
139 fanout. The multicast fanout defines the maximum number of
140 packet copies that may be generated for a multicast-to-unicast
141 conversion. Once this limit is exceeded distribution will fall
142 back to broadcast.
143 [meshif <netdev>] loglevel|ll [level[ level[ level]] ...]
145 If no parameter is given the current log level settings are dis‐
146 played otherwise the parameter(s) is/are used to set the log
147 level. Level 'none' disables all verbose logging. Level 'batman'
148 enables messages related to routing / flooding / broadcasting.
149 Level 'routes' enables messages related to routes being added /
150 changed / deleted. Level 'tt' enables messages related to trans‐
151 lation table operations. Level 'bla' enables messages related to
152 the bridge loop avoidance. Level 'dat' enables messages related
153 to ARP snooping and the Distributed Arp Table. Level 'nc' en‐
154 ables messages related to network coding. Level 'mcast' enables
155 messages related to multicast optimizations. Level 'tp' enables
156 messages related to throughput meter. Level 'all' enables all
157 messages. The messages are sent to the kernels trace buffers.
158 Use trace-cmd stream -e batadv:batadv_dbg to receive the system
159 wide log messages.
160 [meshif <netdev>] gw_mode|gw [off|client|server] [sel_class|bandwidth]
162 If no parameter is given the current gateway mode is displayed
163 otherwise the parameter is used to set the gateway mode. The
164 second (optional) argument specifies the selection class (if
165 'client' was the first argument) or the gateway bandwidth (if
166 'server' was the first argument). If the node is a server this
167 parameter is used to inform other nodes in the network about
168 this node's internet connection bandwidth. Just enter any number
169 (optionally followed by "kbit" or "mbit") and the batman-adv
170 module will propagate the entered value in the mesh. Use "/" to
171 separate the down‐ and upload rates. You can omit the upload
172 rate and the module will assume an upload of download / 5.
173 default: 10000 -> 10.0/2.0 MBit
174 examples: 5000 -> 5.0/1.0 MBit
175 5000kbit
176 5mbit
177 5mbit/1024
178 5mbit/1024kbit
179 5mbit/1mbit
180 If the node is a gateway client the parameter will decide which
181 criteria to consider when the batman-adv module has to choose
182 between different internet connections announced by the afore‐
183 mentioned servers.
184 B.A.T.M.A.N. IV:
185 default: 20 -> late switch (TQ 20)
186 examples: 1 -> fast connection
187 consider the gateway's advertised
188 throughput as well as the link quality
189 towards the gateway and stick with the
190 selection until the gateway disappears
191 2 -> stable connection
192 chooses the gateway with the best link
193 quality and sticks with it (ignore the
194 advertised throughput)
195 3 -> fast switch connection
196 chooses the gateway with the best link
197 quality but switches to another gateway
198 as soon as a better one is found
199 XX -> late switch connection
200 chooses the gateway with the best link
201 quality but switches to another gateway
202 as soon as a better one is found which
203 is at least XX TQ better than the cur‐
204 rently selected gateway (XX has to be a
205 number between 3 and 256).
206 B.A.T.M.A.N. V:
207 default: 5000 -> late switch (5000 kbit/s throughput)
208 example: 1500 -> fast switch connection
209 switches to another gateway as soon
210 as a better one is found which is at
211 least 1500 kbit/s faster throughput
212 than the currently selected gateway.
213 Throughput is determined by evaluat‐
214 ing which is lower: the advertised
215 throughput by the gateway or the max‐
216 imum bandwidth across the entire
217 path.
218 routing_algo|ra [algorithm]
220 If no parameter is given the current routing algorithm configu‐
221 ration as well as supported routing algorithms are displayed.
222 Otherwise the parameter is used to select the routing algorithm
223 for the following batX interface to be created.
224 hardif <hardif> throughput_override|to [bandwidth]
226 If no parameter is given the current througput override is dis‐
227 played otherwise the parameter is used to set the throughput
228 override for the specified hard interface. Just enter any num‐
229 ber (optionally followed by "kbit" or "mbit").
230 [meshif <netdev>] isolation_mark|mark
232 If no parameter is given the current isolation mark value is
233 displayed. Otherwise the parameter is used to set or unset the
234 isolation mark used by the Extended Isolation feature.
235 The input is supposed to be of the form $value/$mask, where
236 $value can be any 32bit long integer (expressed in decimal or
237 hex base) and $mask is a generic bitmask (expressed in hex base)
238 that selects the bits to take into consideration from $value. It
239 is also possible to enter the input using only $value and in
240 this case the full bitmask is used by default.
241 Example 1: 0x00000001/0xffffffff
243 Example 2: 0x00040000/0xffff0000
244 Example 3: 16 or 0x0F
245 debug tables:
247 The batman-adv kernel module comes with a variety of debug ta‐
249 bles containing various information about the state of the mesh
250 seen by each individual node.
251 All of the debug tables support the following options:
253 -w refresh the list every second or add a number to let
254 it refresh at a custom interval in seconds (with optional
255 decimal places)
256 -n do not replace the MAC addresses with bat-host names
257 in the output
258 -H do not show the header of the debug table
259 The originator table also supports the "-t" filter option to re‐
261 move all originators from the output that have not been seen for
262 the specified amount of seconds (with optional decimal places).
263 It furthermore supports the "-i" parameter to specify an inter‐
264 face for which the originator table should be printed. If this
265 parameter is not supplied, the default originator table is
266 printed.
267 The local and global translation tables also support the "-u"
269 and "-m" option to only display unicast or multicast translation
270 table announcements respectively.
271 List of debug tables:
273 - neighbors|n
274 - originators|o
275 - gateways|gwl
276 - translocal|tl
277 - transglobal|tg
278 - claimtable|cl (compile time option)
279 - backbonetable|bbt (compile time option)
280 - dat_cache|dc (compile time option)
281 - mcast_flags|mf (compile time option)
282 JSON queries:
284 The generic netlink family provided by the batman-adv kernel
286 module can be queried (read-only) by batctl and automatically
287 translated to JSON. This can be used to monitor the state of the
288 system without the need of parsing the freeform debug tables or
289 the native netlink messages.
290 List of available JSON queries:
293 - bla_backbone_json|bbj
294 - bla_claim_json|clj
295 - dat_cache_json|dcj
296 - gateways_json|gwj
297 - hardif_json|hj
298 - hardifs_json|hj
299 - mcast_flags_json|mfj
300 - mesh_json|mj
301 - neighbors_json|nj
302 - originators_json|oj
303 - transtable_global_json|tgj
304 - transtable_local_json|tlj
305 - vlan_json|vj
306 [meshif <netdev>] translate|t MAC_ad‐
308 dress|bat-host_name|host_name|IP_address
309 Translates a destination (hostname, IP, MAC, bat_host-
311 name) to the originator mac address responsible for
312 it.
313 [meshif <netdev>] statistics|s
315 Retrieve traffic counters from batman-adv kernel mod‐
316 ule. The output may vary depending on which features
317 have been compiled into the kernel module.
318 Each module subsystem has its own counters which are
319 indicated by their prefixes:
320 mgmt - mesh protocol counters
321 tt - translation table counters
322 All counters without a prefix concern payload (pure
323 user data) traffic.
324 [meshif <netdev>] ping|p [-c count][-i interval][-t
326 time][-R][-T] MAC_address|bat-host_name|host_name|IP_address
327 Layer 2 ping of a MAC address or bat-host name.
328 batctl will try to find the bat-host name if the given
329 parameter was not a MAC address. It can also try to
330 guess the MAC address using an IPv4/IPv6 address or a
331 hostname when the IPv4/IPv6 address was configured on
332 top of the batman-adv interface of the destination de‐
333 vice and both source and destination devices are in
334 the same IP subnet. The "-c" option tells batctl how
335 man pings should be sent before the program exits.
336 Without the "-c" option batctl will continue pinging
337 without end. Use CTRL + C to stop it. With "-i" and
338 "-t" you can set the default interval between pings
339 and the timeout time for replies, both in seconds.
340 When run with "-R", the route taken by the ping mes‐
341 sages will be recorded. With "-T" you can disable the
342 automatic translation of a client MAC address to the
343 originator address which is responsible for this
344 client.
345 [meshif <netdev>] traceroute|tr [-n][-T] MAC_ad‐
347 dress|bat-host_name|host_name|IP_address
348 Layer 2 traceroute to a MAC address or bat-host name.
349 batctl will try to find the bat-host name if the given
350 parameter was not a MAC address. It can also try to
351 guess the MAC address using an IPv4/IPv6 address or a
352 hostname when the IPv4/IPv6 address was configured on
353 top of the batman-adv interface of the destination de‐
354 vice and both source and destination devices are in
355 the same IP subnet. batctl will send 3 packets to
356 each host and display the response time. If "-n" is
357 given batctl will not replace the MAC addresses with
358 bat-host names in the output. With "-T" you can dis‐
359 able the automatic translation of a client MAC address
360 to the originator address which is responsible for
361 this client.
362 tcpdump|td [-c][-n][-p filter][-x filter] interface ...
364 batctl will display all packets that are seen on the
365 given interface(s). A variety of options to filter the
366 output are available: To only print packets that match
367 the compatibility number of batctl specify the "-c"
368 (compat filter) option. If "-n" is given batctl will
369 not replace the MAC addresses with bat-host names in
370 the output. To filter the shown packet types you can
371 either use "-p" (dump only specified packet types) or
372 "-x" (dump all packet types except specified). The
373 following packet types are available:
374 1 - batman ogm packets
375 2 - batman icmp packets
376 4 - batman unicast packets
377 8 - batman broadcast packets
378 16 - batman unicast tvlv packets
379 32 - batman fragmented packets
380 64 - batman tt / roaming packets
381 128 - non batman packets
382 Example: batctl td <interface> -p 129 -> only display
383 batman ogm packets and non batman packets
384 bisect_iv [-l MAC][-t MAC][-r MAC][-s min [- max]][-o
386 MAC][-n] logfile1 [logfile2 ... logfileN]
387 Analyses the B.A.T.M.A.N. IV logfiles to build a small
388 internal database of all sent sequence numbers and
389 routing table changes. This database can then be ana‐
390 lyzed in a number of different ways. With "-l" the
391 database can be used to search for routing loops. Use
392 "-t" to trace OGMs of a host throughout the network.
393 Use "-r" to display routing tables of the nodes. The
394 option "-s" can be used to limit the output to a range
395 of sequence numbers, between min and max, or to one
396 specific sequence number, min. Furthermore using "-o"
397 you can filter the output to a specified originator.
398 If "-n" is given batctl will not replace the MAC ad‐
399 dresses with bat-host names in the output.
400 [meshif <netdev>] throughputmeter|tp MAC
402 This command starts a throughput test entirely controlled by
403 batman module in kernel space: the computational resources
404 needed to align memory and copy data between user and kernel
405 space that are required by other user space tools may represent
406 a bottleneck on some low profile device.
407 The test consist of the transfer of 14 MB of data between the
409 two nodes. The protocol used to transfer the data is somehow
410 similar to TCP, but simpler: some TCP features are still miss‐
411 ing, thus protocol performances could be worst. Since a fixed
412 amount of data is transferred the experiment duration depends on
413 the network conditions. The experiment can be interrupted with
414 CTRL + C. At the end of a successful experiment the throughput
415 in KBytes per second is returned, together with the experiment
416 duration in millisecond and the amount of bytes transferred. If
417 too many packets are lost or the specified MAC address is not
418 reachable, a message notifying the error is returned instead of
419 the result.
420
422 bat-hosts
423 This file is similar to the /etc/hosts file. You can write one
424 MAC address and one host name per line. batctl will search for
425 bat-hosts in /etc, your home directory and the current direc‐
426 tory. The found data is used to match MAC address to your pro‐
427 vided host name or replace MAC addresses in debug output and
428 logs. Host names are much easier to remember than MAC addresses.
429
431 ping(1), traceroute(1), tcpdump(1), dmesg(1), dot(1)
432
434 batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lind‐
435 ner <mareklindner@neomailbox.ch>.
436 This manual page was written by Simon Wunderlich <sw@simonwunder‐
438 lich.de>, Marek Lindner <mareklindner@neomailbox.ch> and Andrew Lunn
439 <andrew@lunn.ch>
440Linux July 17, 2015 BATCTL(8)