Provided by: batctl_2019.5-1_amd64 
NAME
batctl - B.A.T.M.A.N. advanced control and management tool
SYNOPSIS
batctl [options] command|debug table [parameters]
DESCRIPTION
batctl offers a convenient way to configure the batman-adv kernel module as well as displaying debug
information such as originator tables, translation tables and the debug log. In combination with a
bat-hosts file batctl allows the use of host names instead of MAC addresses.
B.A.T.M.A.N. advanced operates on layer 2. Thus all hosts participating in the virtual switched network
are transparently connected together for all protocols above layer 2. Therefore the common diagnosis
tools do not work as expected. To overcome these problems batctl contains the commands ping, traceroute,
tcpdump which provide similar functionality to the normal ping(1), traceroute(1), tcpdump(1) commands,
but modified to layer 2 behaviour or using the B.A.T.M.A.N. advanced protocol. For similar reasons,
throughputmeter, a command to test network performances, is also included.
OPTIONS
options:
-m specify mesh interface (default 'bat0')
-h print general batctl help
-v print batctl version and batman-adv version (if the module is loaded)
commands:
[meshif <netdev>] interface|if [-M] [add|del iface(s)]
If no parameter is given or the first parameter is neither "add" nor "del" the current interface
settings are displayed. In order to add or delete interfaces specify "add" or "del" as first
argument and append the interface names you wish to add or delete. Multiple interfaces can be
specified. The "-M" option tells batctl to not automatically create the batman-adv interface on
"add" or to destroy it when "del" removed all interfaces which belonged to it.
[meshif <netdev>] interface|if [create|destroy]
A batman-adv interface without attached interfaces can be created using "create". The parameter
"destroy" can be used to free all attached interfaces and remove batman-adv interface.
[meshif <netdev>] orig_interval|it [interval]
If no parameter is given the current originator interval setting is displayed otherwise the
parameter is used to set the originator interval. The interval is in units of milliseconds.
[meshif <netdev>] ap_isolation|ap [0|1]
If no parameter is given the current ap isolation setting is displayed. Otherwise the parameter is
used to enable or disable ap isolation.
<vlan <vdev>|[meshif <netdev>] vid <vid>> ap_isolation|ap [0|1]
If no parameter is given the current ap isolation setting for the specified VLAN is displayed.
Otherwise the parameter is used to enable or disable ap isolation for the specified VLAN.
[meshif <netdev>] bridge_loop_avoidance|bl [0|1]
If no parameter is given the current bridge loop avoidance setting is displayed. Otherwise the
parameter is used to enable or disable the bridge loop avoidance. Bridge loop avoidance support
has to be enabled when compiling the module otherwise this option won't be available.
[meshif <netdev>] distributed_arp_table|dat [0|1]
If no parameter is given the current distributed arp table setting is displayed. Otherwise the
parameter is used to enable or disable the distributed arp table.
[meshif <netdev>] aggregation|ag [0|1]
If no parameter is given the current aggregation setting is displayed. Otherwise the parameter is
used to enable or disable OGM packet aggregation.
[meshif <netdev>] bonding|b [0|1]
If no parameter is given the current bonding mode setting is displayed. Otherwise the parameter is
used to enable or disable the bonding mode.
event|e [-t|-r]
batctl will monitor for events from the netlink kernel interface of batman-adv. The local
timestamp of the event will be printed when parameter -t is specified. Parameter -r will do the
same but with relative timestamps.
hardif <hardif> elp_interval|et [interval]
If no parameter is given the current ELP interval setting of the hard interface is displayed
otherwise the parameter is used to set the ELP interval. The interval is in units of milliseconds.
[meshif <netdev>] fragmentation|f [0|1]
If no parameter is given the current fragmentation mode setting is displayed. Otherwise the
parameter is used to enable or disable fragmentation.
[meshif <netdev>] hop_penalty|hp [penalty]
If no parameter is given the current hop penalty setting is displayed. Otherwise the parameter is
used to set the hop penalty. The penalty is can be 0-255 (255 sets originator message's TQ to zero
when forwarded by this hop).
[meshif <netdev>] network_coding|nc [0|1]
If no parameter is given the current network coding mode setting is displayed. Otherwise the
parameter is used to enable or disable network coding.
[meshif <netdev>] multicast_forceflood|mff [0|1]
If no parameter is given the current multicast forceflood setting is displayed. Otherwise the
parameter is used to enable or disable multicast forceflood. This setting defines whether
multicast optimizations should be replaced by simple broadcast-like flooding of multicast packets.
If set to non-zero then all nodes in the mesh are going to use classic flooding for any multicast
packet with no optimizations.
[meshif <netdev>] multicast_fanout|mo [fanout]
If no parameter is given the current multicast fanout setting is displayed. Otherwise the
parameter is used to set the multicast fanout. The multicast fanout defines the maximum number of
packet copies that may be generated for a multicast-to-unicast conversion. Once this limit is
exceeded distribution will fall back to broadcast.
[meshif <netdev>] loglevel|ll [level[ level[ level]] ...]
If no parameter is given the current log level settings are displayed otherwise the parameter(s)
is/are used to set the log level. Level 'none' disables all verbose logging. Level 'batman'
enables messages related to routing / flooding / broadcasting. Level 'routes' enables messages
related to routes being added / changed / deleted. Level 'tt' enables messages related to
translation table operations. Level 'bla' enables messages related to the bridge loop avoidance.
Level 'dat' enables messages related to ARP snooping and the Distributed Arp Table. Level 'nc'
enables messages related to network coding. Level 'mcast' enables messages related to multicast
optimizations. Level 'tp' enables messages related to throughput meter. Level 'all' enables all
messages. The messages are sent to the batman-adv debug log. Use batctl log to retrieve it. Make
sure to have debugging output enabled when compiling the module otherwise the output as well as
the loglevel options won't be available.
[meshif <netdev>] gw_mode|gw [off|client|server] [sel_class|bandwidth]
If no parameter is given the current gateway mode is displayed otherwise the parameter is used to
set the gateway mode. The second (optional) argument specifies the selection class (if 'client'
was the first argument) or the gateway bandwidth (if 'server' was the first argument). If the node
is a server this parameter is used to inform other nodes in the network about this node's internet
connection bandwidth. Just enter any number (optionally followed by "kbit" or "mbit") and the
batman-adv module will propagate the entered value in the mesh. Use "/" to separate the down‐ and
upload rates. You can omit the upload rate and the module will assume an upload of download / 5.
default: 10000 -> 10.0/2.0 MBit
examples: 5000 -> 5.0/1.0 MBit
5000kbit
5mbit
5mbit/1024
5mbit/1024kbit
5mbit/1mbit
If the node is a gateway client the parameter will decide which criteria to consider when the
batman-adv module has to choose between different internet connections announced by the
aforementioned servers.
B.A.T.M.A.N. IV:
default: 20 -> late switch (TQ 20)
examples: 1 -> fast connection
consider the gateway's advertised throughput as well as the link quality
towards the gateway and stick with the selection until the gateway
disappears
2 -> stable connection
chooses the gateway with the best link quality and sticks with it (ignore
the advertised throughput)
3 -> fast switch connection
chooses the gateway with the best link quality but switches to another
gateway as soon as a better one is found
XX -> late switch connection
chooses the gateway with the best link quality but switches to another
gateway as soon as a better one is found which is at least XX TQ better
than the currently selected gateway (XX has to be a number between 3 and
256).
B.A.T.M.A.N. V:
default: 5000 -> late switch (5000 kbit/s throughput)
example: 1500 -> fast switch connection
switches to another gateway as soon as a better one is found which is
at least 1500 kbit/s faster throughput than the currently selected
gateway. Throughput is determined by evaluating which is lower: the
advertised throughput by the gateway or the maximum bandwidth across
the entire path.
routing_algo|ra [algorithm]
If no parameter is given the current routing algorithm configuration as well as supported routing
algorithms are displayed. Otherwise the parameter is used to select the routing algorithm for the
following batX interface to be created.
hardif <hardif> throughput_override|to [bandwidth]
If no parameter is given the current througput override is displayed otherwise the parameter is
used to set the throughput override for the specified hard interface. Just enter any number
(optionally followed by "kbit" or "mbit").
[meshif <netdev>] isolation_mark|mark
If no parameter is given the current isolation mark value is displayed. Otherwise the parameter
is used to set or unset the isolation mark used by the Extended Isolation feature.
The input is supposed to be of the form $value/$mask, where $value can be any 32bit long integer
(expressed in decimal or hex base) and $mask is a generic bitmask (expressed in hex base) that
selects the bits to take into consideration from $value. It is also possible to enter the input
using only $value and in this case the full bitmask is used by default.
Example 1: 0x00000001/0xffffffff
Example 2: 0x00040000/0xffff0000
Example 3: 16 or 0x0F
debug tables:
The batman-adv kernel module comes with a variety of debug tables containing various information
about the state of the mesh seen by each individual node. These tables are exported via debugfs
and easily accessible via batctl. You will need debugfs support compiled into your kernel and
preferably have mounted the debugfs to a well-known mountpoint. If debugfs is not mounted batctl
will attempt to do this step for you.
All of the debug tables support the following options:
-w refresh the list every second or add a number to let it refresh at a custom interval in
seconds (with optional decimal places)
-n do not replace the MAC addresses with bat-host names in the output
-H do not show the header of the debug table
The originator table also supports the "-t" filter option to remove all originators from the
output that have not been seen for the specified amount of seconds (with optional decimal places).
It furthermore supports the "-i" parameter to specify an interface for which the originator table
should be printed. If this parameter is not supplied, the default originator table is printed.
The local and global translation tables also support the "-u" and "-m" option to only display
unicast or multicast translation table announcements respectively.
List of debug tables:
- neighbors|n
- originators|o
- gateways|gwl
- translocal|tl
- transglobal|tg
- claimtable|cl (compile time option)
- backbonetable|bbt (compile time option)
- dat_cache|dc (compile time option)
- nc_nodes|nn (compile time option)
- mcast_flags|mf (compile time option)
[meshif <netdev>] translate|t MAC_address|bat-host_name|host_name|IP_address
Translates a destination (hostname, IP, MAC, bat_host-name) to the originator mac address
responsible for it.
[meshif <netdev>] statistics|s
Retrieve traffic counters from batman-adv kernel module. The output may vary depending on which
features have been compiled into the kernel module.
Each module subsystem has its own counters which are indicated by their prefixes:
mgmt - mesh protocol counters
tt - translation table counters
All counters without a prefix concern payload (pure user data) traffic.
[meshif <netdev>] ping|p [-c count][-i interval][-t time][-R][-T]
MAC_address|bat-host_name|host_name|IP_address
Layer 2 ping of a MAC address or bat-host name. batctl will try to find the bat-host name if the
given parameter was not a MAC address. It can also try to guess the MAC address using an IPv4/IPv6
address or a hostname when the IPv4/IPv6 address was configured on top of the batman-adv interface
of the destination device and both source and destination devices are in the same IP subnet. The
"-c" option tells batctl how man pings should be sent before the program exits. Without the "-c"
option batctl will continue pinging without end. Use CTRL + C to stop it. With "-i" and "-t" you
can set the default interval between pings and the timeout time for replies, both in seconds. When
run with "-R", the route taken by the ping messages will be recorded. With "-T" you can disable
the automatic translation of a client MAC address to the originator address which is responsible
for this client.
[meshif <netdev>] traceroute|tr [-n][-T] MAC_address|bat-host_name|host_name|IP_address
Layer 2 traceroute to a MAC address or bat-host name. batctl will try to find the bat-host name if
the given parameter was not a MAC address. It can also try to guess the MAC address using an
IPv4/IPv6 address or a hostname when the IPv4/IPv6 address was configured on top of the batman-adv
interface of the destination device and both source and destination devices are in the same IP
subnet. batctl will send 3 packets to each host and display the response time. If "-n" is given
batctl will not replace the MAC addresses with bat-host names in the output. With "-T" you can
disable the automatic translation of a client MAC address to the originator address which is
responsible for this client.
tcpdump|td [-c][-n][-p filter][-x filter] interface ...
batctl will display all packets that are seen on the given interface(s). A variety of options to
filter the output are available: To only print packets that match the compatibility number of
batctl specify the "-c" (compat filter) option. If "-n" is given batctl will not replace the MAC
addresses with bat-host names in the output. To filter the shown packet types you can either use
"-p" (dump only specified packet types) or "-x" (dump all packet types except specified). The
following packet types are available:
1 - batman ogm packets
2 - batman icmp packets
4 - batman unicast packets
8 - batman broadcast packets
16 - batman unicast tvlv packets
32 - batman fragmented packets
64 - batman tt / roaming packets
128 - non batman packets
Example: batctl td <interface> -p 129 -> only display batman ogm packets and non batman packets
bisect_iv [-l MAC][-t MAC][-r MAC][-s min [- max]][-o MAC][-n] logfile1 [logfile2 ... logfileN]
Analyses the B.A.T.M.A.N. IV logfiles to build a small internal database of all sent sequence
numbers and routing table changes. This database can then be analyzed in a number of different
ways. With "-l" the database can be used to search for routing loops. Use "-t" to trace OGMs of a
host throughout the network. Use "-r" to display routing tables of the nodes. The option "-s" can
be used to limit the output to a range of sequence numbers, between min and max, or to one
specific sequence number, min. Furthermore using "-o" you can filter the output to a specified
originator. If "-n" is given batctl will not replace the MAC addresses with bat-host names in the
output.
[meshif <netdev>] throughputmeter|tp MAC
This command starts a throughput test entirely controlled by batman module in kernel space: the
computational resources needed to align memory and copy data between user and kernel space that
are required by other user space tools may represent a bottleneck on some low profile device.
The test consist of the transfer of 14 MB of data between the two nodes. The protocol used to
transfer the data is somehow similar to TCP, but simpler: some TCP features are still missing,
thus protocol performances could be worst. Since a fixed amount of data is transferred the
experiment duration depends on the network conditions. The experiment can be interrupted with CTRL
+ C. At the end of a successful experiment the throughput in KBytes per second is returned,
together with the experiment duration in millisecond and the amount of bytes transferred. If too
many packets are lost or the specified MAC address is not reachable, a message notifying the error
is returned instead of the result.
FILES
bat-hosts
This file is similar to the /etc/hosts file. You can write one MAC address and one host name per
line. batctl will search for bat-hosts in /etc, your home directory and the current directory. The
found data is used to match MAC address to your provided host name or replace MAC addresses in
debug output and logs. Host names are much easier to remember than MAC addresses.
SEE ALSO
ping(1), traceroute(1), tcpdump(1), dmesg(1), dot(1)
AUTHOR
batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lindner <mareklindner@neomailbox.ch>.
This manual page was written by Simon Wunderlich <sw@simonwunderlich.de>, Marek Lindner
<mareklindner@neomailbox.ch> and Andrew Lunn <andrew@lunn.ch>
Linux July 17, 2015 BATCTL(8)