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 (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
35       commands:
36
37       [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
47       [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
52       [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
57       [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
62       <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
67       [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
74       [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
79       [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
84       [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
89       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
95       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
100       [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
105       [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
111       [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
116       [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
125       [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
133       [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
151       [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
209       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
215       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
221       [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
232              Example 1: 0x00000001/0xffffffff
233              Example 2: 0x00040000/0xffff0000
234              Example 3: 16 or 0x0F
235
236       debug tables:
237
238              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
246              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
254              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
262              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
266              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
278       [meshif <netdev>] translate|t
279       MAC_address|bat-host_name|host_name|IP_address
280
281              Translates a destination (hostname, IP, MAC, bat_host-name) to
282              the originator mac address responsible for it.
283
284       [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
295       [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
313       [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
328       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
349       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
363       [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
370              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

FILES

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

SEE ALSO

393       ping(1), traceroute(1), tcpdump(1), dmesg(1), dot(1)
394

AUTHOR

396       batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lind‐
397       ner <mareklindner@neomailbox.ch>.
398
399       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>
402
403
404
405Linux                            July 17, 2015                       BATCTL(8)
Impressum