|BATCTL(8)||B.A.T.M.A.N. Advanced Control Tool||BATCTL(8)|
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.
- -m specify mesh interface or VLAN created on top of a mesh interface
-h print general batctl help
-v print batctl version and batman-adv version (if the module is loaded)
- 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.
- 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.
- 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.
- 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. This
command can be used in conjunction with "-m" option to target
per VLAN configurations.
- 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.
- 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.
- 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
- 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.
- 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
- 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
- multicast_mode|mm [0|1]
- If no parameter is given the current multicast mode setting is displayed.
Otherwise the parameter is used to enable or disable multicast
optimizations (i.e. disabling means always sending own multicast frames
via classic flooding).
- 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 '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.
- log|l [-n]
- batctl will read the batman-adv debug log which has to be compiled into
the kernel module. If "-n" is given batctl will not replace the
MAC addresses with bat-host names in the output.
- 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.
- 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.
- 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
- 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:
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:
- 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.
- Retrieve traffic counters from batman-adv kernel module. The output may
vary depending on which features have been compiled into the kernel
Each module subsystem has its own counters which are indicated by their prefixes:
- 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.
- 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
- 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:
- 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.
- 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 bootleneck 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, togheter 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 notifing the error is returned instead of the result.
- 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 <firstname.lastname@example.org> and Marek Lindner <email@example.com>.
This manual page was written by Simon Wunderlich <firstname.lastname@example.org>, Marek Lindner <email@example.com> and Andrew Lunn <firstname.lastname@example.org>
|July 17, 2015||Linux|