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 [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 translation tables and the debug log. In combination with a bat-hosts
15 file batctl allows 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
40 order to add or delete interfaces specify "add" or "del" as
41 first 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
77 option 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'
154 enables messages related to network coding. Level 'mcast'
155 enables messages related to multicast optimizations. Level 'tp'
156 enables messages related to throughput meter. Level 'all'
157 enables all messages. The messages are sent to the batman-adv
158 debug log. Use batctl log to retrieve it. Make sure to have
159 debugging output enabled when compiling the module otherwise the
160 output as well as the loglevel options won't be available.
161 [meshif <netdev>] gw_mode|gw [off|client|server] [sel_class|bandwidth]
163 If no parameter is given the current gateway mode is displayed
164 otherwise the parameter is used to set the gateway mode. The
165 second (optional) argument specifies the selection class (if
166 'client' was the first argument) or the gateway bandwidth (if
167 'server' was the first argument). If the node is a server this
168 parameter is used to inform other nodes in the network about
169 this node's internet connection bandwidth. Just enter any number
170 (optionally followed by "kbit" or "mbit") and the batman-adv
171 module will propagate the entered value in the mesh. Use "/" to
172 separate the down‐ and upload rates. You can omit the upload
173 rate and the module will assume an upload of download / 5.
174 default: 10000 -> 10.0/2.0 MBit
175 examples: 5000 -> 5.0/1.0 MBit
176 5000kbit
177 5mbit
178 5mbit/1024
179 5mbit/1024kbit
180 5mbit/1mbit
181 If the node is a gateway client the parameter will decide which
182 criteria to consider when the batman-adv module has to choose
183 between different internet connections announced by the afore‐
184 mentioned servers.
185 B.A.T.M.A.N. IV:
186 default: 20 -> late switch (TQ 20)
187 examples: 1 -> fast connection
188 consider the gateway's advertised
189 throughput as well as the link quality
190 towards the gateway and stick with the
191 selection until the gateway disappears
192 2 -> stable connection
193 chooses the gateway with the best link
194 quality and sticks with it (ignore the
195 advertised throughput)
196 3 -> fast switch connection
197 chooses the gateway with the best link
198 quality but switches to another gateway
199 as soon as a better one is found
200 XX -> late switch connection
201 chooses the gateway with the best link
202 quality but switches to another gateway
203 as soon as a better one is found which
204 is at least XX TQ better than the cur‐
205 rently selected gateway (XX has to be a
206 number between 3 and 256).
207 B.A.T.M.A.N. V:
208 default: 5000 -> late switch (5000 kbit/s throughput)
209 example: 1500 -> fast switch connection
210 switches to another gateway as soon
211 as a better one is found which is at
212 least 1500 kbit/s faster throughput
213 than the currently selected gateway.
214 Throughput is determined by evaluat‐
215 ing which is lower: the advertised
216 throughput by the gateway or the max‐
217 imum bandwidth across the entire
218 path.
219 routing_algo|ra [algorithm]
221 If no parameter is given the current routing algorithm configu‐
222 ration as well as supported routing algorithms are displayed.
223 Otherwise the parameter is used to select the routing algorithm
224 for the following batX interface to be created.
225 hardif <hardif> throughput_override|to [bandwidth]
227 If no parameter is given the current througput override is dis‐
228 played otherwise the parameter is used to set the throughput
229 override for the specified hard interface. Just enter any num‐
230 ber (optionally followed by "kbit" or "mbit").
231 [meshif <netdev>] isolation_mark|mark
233 If no parameter is given the current isolation mark value is
234 displayed. Otherwise the parameter is used to set or unset the
235 isolation mark used by the Extended Isolation feature.
236 The input is supposed to be of the form $value/$mask, where
237 $value can be any 32bit long integer (expressed in decimal or
238 hex base) and $mask is a generic bitmask (expressed in hex base)
239 that selects the bits to take into consideration from $value. It
240 is also possible to enter the input using only $value and in
241 this case the full bitmask is used by default.
242 Example 1: 0x00000001/0xffffffff
244 Example 2: 0x00040000/0xffff0000
245 Example 3: 16 or 0x0F
246 debug tables:
248 The batman-adv kernel module comes with a variety of debug
250 tables containing various information about the state of the
251 mesh seen by each individual node.
252 All of the debug tables support the following options:
254 -w refresh the list every second or add a number to let
255 it refresh at a custom interval in seconds (with optional
256 decimal places)
257 -n do not replace the MAC addresses with bat-host names
258 in the output
259 -H do not show the header of the debug table
260 The originator table also supports the "-t" filter option to
262 remove all originators from the output that have not been seen
263 for the specified amount of seconds (with optional decimal
264 places). It furthermore supports the "-i" parameter to specify
265 an interface for which the originator table should be printed.
266 If this parameter is not supplied, the default originator table
267 is printed.
268 The local and global translation tables also support the "-u"
270 and "-m" option to only display unicast or multicast translation
271 table announcements respectively.
272 List of debug tables:
274 - neighbors|n
275 - originators|o
276 - gateways|gwl
277 - translocal|tl
278 - transglobal|tg
279 - claimtable|cl (compile time option)
280 - backbonetable|bbt (compile time option)
281 - dat_cache|dc (compile time option)
282 - mcast_flags|mf (compile time option)
283 [meshif <netdev>] translate|t
285 MAC_address|bat-host_name|host_name|IP_address
286 Translates a destination (hostname, IP, MAC, bat_host-name) to
288 the originator mac address responsible for it.
289 [meshif <netdev>] statistics|s
291 Retrieve traffic counters from batman-adv kernel module. The
292 output may vary depending on which features have been compiled
293 into the kernel module.
294 Each module subsystem has its own counters which are indicated
295 by their prefixes:
296 mgmt - mesh protocol counters
297 tt - translation table counters
298 All counters without a prefix concern payload (pure user data)
299 traffic.
300 [meshif <netdev>] ping|p [-c count][-i interval][-t time][-R][-T]
302 MAC_address|bat-host_name|host_name|IP_address
303 Layer 2 ping of a MAC address or bat-host name. batctl will try
304 to find the bat-host name if the given parameter was not a MAC
305 address. It can also try to guess the MAC address using an
306 IPv4/IPv6 address or a hostname when the IPv4/IPv6 address was
307 configured on top of the batman-adv interface of the destination
308 device and both source and destination devices are in the same
309 IP subnet. The "-c" option tells batctl how man pings should be
310 sent before the program exits. Without the "-c" option batctl
311 will continue pinging without end. Use CTRL + C to stop it.
312 With "-i" and "-t" you can set the default interval between
313 pings and the timeout time for replies, both in seconds. When
314 run with "-R", the route taken by the ping messages will be
315 recorded. With "-T" you can disable the automatic translation of
316 a client MAC address to the originator address which is respon‐
317 sible for this client.
318 [meshif <netdev>] traceroute|tr [-n][-T]
320 MAC_address|bat-host_name|host_name|IP_address
321 Layer 2 traceroute to a MAC address or bat-host name. batctl
322 will try to find the bat-host name if the given parameter was
323 not a MAC address. It can also try to guess the MAC address
324 using an IPv4/IPv6 address or a hostname when the IPv4/IPv6
325 address was configured on top of the batman-adv interface of the
326 destination device and both source and destination devices are
327 in the same IP subnet. batctl will send 3 packets to each host
328 and display the response time. If "-n" is given batctl will not
329 replace the MAC addresses with bat-host names in the output.
330 With "-T" you can disable the automatic translation of a client
331 MAC address to the originator address which is responsible for
332 this client.
333 tcpdump|td [-c][-n][-p filter][-x filter] interface ...
335 batctl will display all packets that are seen on the given
336 interface(s). A variety of options to filter the output are
337 available: To only print packets that match the compatibility
338 number of batctl specify the "-c" (compat filter) option. If
339 "-n" is given batctl will not replace the MAC addresses with
340 bat-host names in the output. To filter the shown packet types
341 you can either use "-p" (dump only specified packet types) or
342 "-x" (dump all packet types except specified). The following
343 packet types are available:
344 1 - batman ogm packets
345 2 - batman icmp packets
346 4 - batman unicast packets
347 8 - batman broadcast packets
348 16 - batman unicast tvlv packets
349 32 - batman fragmented packets
350 64 - batman tt / roaming packets
351 128 - non batman packets
352 Example: batctl td <interface> -p 129 -> only display batman ogm
353 packets and non batman packets
354 bisect_iv [-l MAC][-t MAC][-r MAC][-s min [- max]][-o MAC][-n] logfile1
356 [logfile2 ... logfileN]
357 Analyses the B.A.T.M.A.N. IV logfiles to build a small internal
358 database of all sent sequence numbers and routing table changes.
359 This database can then be analyzed in a number of different
360 ways. With "-l" the database can be used to search for routing
361 loops. Use "-t" to trace OGMs of a host throughout the network.
362 Use "-r" to display routing tables of the nodes. The option "-s"
363 can be used to limit the output to a range of sequence numbers,
364 between min and max, or to one specific sequence number, min.
365 Furthermore using "-o" you can filter the output to a specified
366 originator. If "-n" is given batctl will not replace the MAC
367 addresses with bat-host names in the output.
368 [meshif <netdev>] throughputmeter|tp MAC
370 This command starts a throughput test entirely controlled by
371 batman module in kernel space: the computational resources
372 needed to align memory and copy data between user and kernel
373 space that are required by other user space tools may represent
374 a bottleneck on some low profile device.
375 The test consist of the transfer of 14 MB of data between the
377 two nodes. The protocol used to transfer the data is somehow
378 similar to TCP, but simpler: some TCP features are still miss‐
379 ing, thus protocol performances could be worst. Since a fixed
380 amount of data is transferred the experiment duration depends on
381 the network conditions. The experiment can be interrupted with
382 CTRL + C. At the end of a successful experiment the throughput
383 in KBytes per second is returned, together with the experiment
384 duration in millisecond and the amount of bytes transferred. If
385 too many packets are lost or the specified MAC address is not
386 reachable, a message notifying the error is returned instead of
387 the result.
388
390 bat-hosts
391 This file is similar to the /etc/hosts file. You can write one
392 MAC address and one host name per line. batctl will search for
393 bat-hosts in /etc, your home directory and the current direc‐
394 tory. The found data is used to match MAC address to your pro‐
395 vided host name or replace MAC addresses in debug output and
396 logs. Host names are much easier to remember than MAC addresses.
397
399 ping(1), traceroute(1), tcpdump(1), dmesg(1), dot(1)
400
402 batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lind‐
403 ner <mareklindner@neomailbox.ch>.
404 This manual page was written by Simon Wunderlich <sw@simonwunder‐
406 lich.de>, Marek Lindner <mareklindner@neomailbox.ch> and Andrew Lunn
407 <andrew@lunn.ch>
408Linux July 17, 2015 BATCTL(8)