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