1BATCTL(8)             B.A.T.M.A.N. Advanced Control Tool             BATCTL(8)
2
3
4

NAME

6       batctl - B.A.T.M.A.N. advanced control and management tool
7

SYNOPSIS

9       batctl [options] command|debug table [parameters]
10

DESCRIPTION

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
17       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
27

OPTIONS

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
36       commands:
37
38       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
48       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
53       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
58       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
64       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
71       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
76       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
81       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
86       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
92       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
97       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
103       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
108       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
117       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
125       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
143       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
201       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
207       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
218              Example 1: 0x00000001/0xffffffff
219              Example 2: 0x00040000/0xffff0000
220              Example 3: 16 or 0x0F
221
222       debug tables:
223
224              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
232              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
240              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
248              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
252              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
264       translate|t MAC_address|bat-host_name|host_name|IP_address
265
266              Translates a destination (hostname, IP, MAC, bat_host-name) to
267              the originator mac address responsible for it.
268
269       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
280       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
298       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
312       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
333       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
347       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
354              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

FILES

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

SEE ALSO

377       ping(1), traceroute(1), tcpdump(1), dmesg(1), dot(1)
378

AUTHOR

380       batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lind‐
381       ner <mareklindner@neomailbox.ch>.
382
383       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>
386
387
388
389Linux                            July 17, 2015                       BATCTL(8)
Impressum