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