batctl - html man page (v2026.3-2-ge01cdd8)
[1mDESCRIPTION[0m
batctl offers a convenient way to configure the batman-adv kernel mod-
ule as well as displaying debug information such as originator tables
and translation tables. In combination with a bat-hosts file batctl al-
lows 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 [1mping[22m, [1mtraceroute[22m, [1mtcpdump [22mwhich provide similar functionality
to the normal [1mping[22m(1), [1mtraceroute[22m(1), [1mtcpdump[22m(1) commands, but modified
to layer 2 behaviour or using the B.A.T.M.A.N. advanced protocol. For
similar reasons, [1mthroughputmeter[22m, a command to test network perfor-
mances, is also included.
[1mOPTIONS[0m
[1m-m [22mspecify mesh interface (default 'bat0')
[1m-h [22mprint general batctl help
[1m-v [22mprint batctl version and batman-adv version (if the module is
loaded)
[1mCOMMANDS[0m
[1mevent[22m|[1me [22m[[1m-t[22m|[1m-r[22m]
batctl will monitor for events from the netlink kernel interface
of batman-adv. The local timestamp of the event will be printed
when parameter [1m-t [22mis specified. Parameter [1m-r [22mwill do the same
but with relative timestamps.
[[1mmeshif [4m[22mnetdev[24m] [1minterface[22m|[1mif[0m
[[1mmeshif [4m[22mnetdev[24m] [1minterface[22m|[1mif [22m[[1m-M[22m] [1madd[22m|[1mdel [4m[22miface[24m ...
If no parameter is given or the first parameter is neither "add"
nor "del" the current interface settings are displayed. In or-
der 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 inter-
face on "add". It can also be used to suppress the warning about
the manual destruction when "del" removed all interfaces which
belonged to it.
[[1mmeshif [4m[22mnetdev[24m] [1minterface[22m|[1mif create [22m[[1mrouting_algo[22m|[1mra [4m[22mRA_NAME[24m]
A batman-adv interface without attached interfaces can be cre-
ated using "create". The parameter routing_algo can be used to
overwrite the (default) routing algorithm.
[[1mmeshif [4m[22mnetdev[24m] [1minterface[22m|[1mif destroy[0m
Remove all attached interfaces and destroy the batman-adv inter-
face.
[[1mmeshif [4m[22mnetdev[24m] [1mping[22m|[1mp [22m[[1m-c [4m[22mcount[24m][[1m-i [4m[22minterval[24m][[1m-t [4m[22mtime[24m][[1m-R[22m][[1m-T[22m] [4mMAC_ad-[0m
[4mdress[24m|[4mbat-host_name[24m|[4mhost_name[24m|[4mIP_address[0m
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 respon-
sible for this client.
[1mrouting_algo[22m|[1mra [22m[[4malgorithm[24m]
If no parameter is given the current routing algorithm configu-
ration 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.
[[1mmeshif [4m[22mnetdev[24m] [1mstatistics[22m|[1ms[0m
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.
[1mtcpdump[22m|[1mtd [22m[[1m-c[22m][[1m-n[22m][[1m-p [4m[22mfilter[24m][[1m-x [4m[22mfilter[24m] [1minterface ...[0m
batctl will display all packets that are seen on the given in-
terface(s). A variety of options to filter the output are avail-
able: 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
[[1mmeshif [4m[22mnetdev[24m] [1mthroughputmeter[22m|[1mtp [4m[22mMAC[0m
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 miss-
ing, 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.
[[1mmeshif [4m[22mnetdev[24m] [1mtraceroute[22m|[1mtr [22m[[1m-n[22m][[1m-T[22m] [4mMAC_ad-[0m
[4mdress[24m|[4mbat-host_name[24m|[4mhost_name[24m|[4mIP_address[0m
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 us-
ing an IPv4/IPv6 address or a hostname when the IPv4/IPv6 ad-
dress 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.
[[1mmeshif [4m[22mnetdev[24m] [1mtranslate[22m|[1mt [4m[22mMAC_address[24m|[4mbat-host_name[24m|[4mhost_name[24m|[4mIP_ad-[0m
[4mdress[0m
Translates a destination (hostname, IP, MAC, bat_host-name) to
the originator mac address responsible for it.
[1mSETTINGS[0m
[[1mmeshif [4m[22mnetdev[24m] [1maggregation[22m|[1mag [22m[[4m0[24m|[4m1[24m]
If no parameter is given the current aggregation setting is dis-
played. Otherwise the parameter is used to enable or disable OGM
packet aggregation.
[[1mmeshif [4m[22mnetdev[24m] [1map_isolation[22m|[1map [22m[[4m0[24m|[4m1[24m]
If no parameter is given the current ap isolation setting is
displayed. Otherwise the parameter is used to enable or disable
ap isolation.
[[1mmeshif [4m[22mnetdev[24m] [1map_isolation[22m|[1map [22m[[4m0[24m|[4m1[24m]
[[1mmeshif [4m[22mnetdev[24m] [1mvid <vid> ap_isolation[22m|[1map [22m[[4m0[24m|[4m1[24m]
[1mvlan [4m[22mvdev[24m [1map_isolation[22m|[1map [22m[[4m0[24m|[4m1[24m]
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.
[[1mmeshif [4m[22mnetdev[24m] [1mbonding[22m|[1mb [22m[[4m0[24m|[4m1[24m]
If no parameter is given the current bonding mode setting is
displayed. Otherwise the parameter is used to enable or disable
the bonding mode.
[[1mmeshif [4m[22mnetdev[24m] [1mbridge_loop_avoidance[22m|[1mbl [22m[[4m0[24m|[4m1[24m]
If no parameter is given the current bridge loop avoidance set-
ting 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 op-
tion won't be available.
[[1mmeshif [4m[22mnetdev[24m] [1mdistributed_arp_table[22m|[1mdat [22m[[4m0[24m|[4m1[24m]
If no parameter is given the current distributed arp table set-
ting is displayed. Otherwise the parameter is used to enable or
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 afore-
mentioned 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 cur-
rently 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 evaluat-
ing which is lower: the advertised
throughput by the gateway or the max-
imum bandwidth across the entire
path.
[[1mmeshif [4m[22mnetdev[24m] [1mhop_penalty[22m|[1mhp [22m[[4mpenalty[24m]
If no parameter is given the current hop penalty setting is dis-
played. 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).
[[1mhardif [4m[22mhardif[24m] [1mhop_penalty[22m|[1mhp [22m[[4mpenalty[24m]
If no parameter is given the current hop penalty setting of the
hard interface is displayed. Otherwise the parameter is used to
set the hop penalty. The penalty can be 0-255 (255 sets origina-
tor message's TQ to zero when forwarded over this interface).
[[1mmeshif [4m[22mnetdev[24m] [1misolation_mark[22m|[1mmark [22m[[4mvalue[24m[/[4mmask[24m]]
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
[[1mmeshif [4m[22mnetdev[24m] [1mloglevel[22m|[1mll [22m[[4mlevel[24m ...]
If no parameter is given the current log level settings are dis-
played 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 trans-
lation 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 'mcast'
enables messages related to multicast optimizations. Level 'tp'
enables messages related to throughput meter. Level 'all' en-
ables all messages. The messages are sent to the kernels trace
buffers. Use [1mtrace-cmd stream -e batadv:batadv_dbg [22mto receive
the system wide log messages.
[[1mmeshif [4m[22mnetdev[24m] [1mmulticast_fanout[22m|[1mmo [22m[[4mfanout[24m]
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.
[[1mmeshif [4m[22mnetdev[24m] [1mmulticast_forceflood[22m|[1mmff [22m[[4m0[24m|[4m1[24m]
If no parameter is given the current multicast forceflood set-
ting is displayed. Otherwise the parameter is used to enable or
disable multicast forceflood. This setting defines whether mul-
ticast 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.
[[1mmeshif [4m[22mnetdev[24m] [1morig_interval[22m|[1mit [22m[[4minterval[24m]
If no parameter is given the current originator interval setting
is displayed otherwise the parameter is used to set the origina-
tor interval. The interval is in units of milliseconds.
[1mhardif [4m[22mhardif[24m [1mthroughput_override|to [22m[[4mbandwidth[24m]
If no parameter is given the current througput override is dis-
played otherwise the parameter is used to set the throughput
override for the specified hard interface. Just enter any num-
ber (optionally followed by "kbit" or "mbit").
[1mDEBUG TABLES[0m
The batman-adv kernel module comes with a variety of debug tables con-
taining various information about the state of the mesh seen by each
individual node.
All of the debug tables support the following options:
[1m-w [22mrefresh the list every second or add a number to let it refresh
at a custom interval in seconds (with optional decimal places)
[1m-n [22mdo not replace the MAC addresses with bat-host names in the out-
put
[1m-H [22mdo 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 sup-
ports the "-i" parameter to specify an interface for which the origina-
tor table should be printed. If this parameter is not supplied, the de-
fault 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 announce-
ments respectively.
[[1mmeshif [4m[22mnetdev[24m] [1mbackbonetable[22m|[1mbbt [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[4m[22minterval[24m]
(compile time option)
[[1mmeshif [4m[22mnetdev[24m] [1mclaimtable[22m|[1mcl [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]]
[[1mmeshif [4m[22mnetdev[24m] [1mdat_cache[22m|[1mdc [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]]
(compile time option)
[[1mmeshif [4m[22mnetdev[24m] [1mgateways[22m|[1mgwl [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]]
[[1mmeshif [4m[22mnetdev[24m] [1mmcast_flags[22m|[1mmf [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]]
(compile time option)
[[1mmeshif [4m[22mnetdev[24m] [1mneighbors[22m|[1mn [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]]
[[1mmeshif [4m[22mnetdev[24m] [1moriginators[22m|[1mo [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]] [[1m-t [4m[22mtimeout_in-[0m
[4mterval[24m] [[1m-i [4m[22minterface[24m]
[[1mmeshif [4m[22mnetdev[24m] [1mtransglobal[22m|[1mtg [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]] [[1m-u[22m] [[1m-m[22m]
(compile time option)
[[1mmeshif [4m[22mnetdev[24m] [1mtranslocal[22m|[1mtl [22m[[1m-n[22m] [[1m-H[22m] [[1m-w[22m[[4minterval[24m]] [[1m-u[22m] [[1m-m[22m]
[1mJSON QUERIES[0m
The generic netlink family provided by the batman-adv kernel module can
be queried (read-only) by batctl and automatically translated to JSON.
This can be used to monitor the state of the system without the need of
parsing the freeform debug tables or the native netlink messages.
[[1mmeshif [4m[22mnetdev[24m] [1mmesh_json[22m|[1mmj[0m
[[1mmeshif [4m[22mnetdev[24m] [1mneighbors_json[22m|[1mnj[0m
[[1mmeshif [4m[22mnetdev[24m] [1moriginators_json[22m|[1moj[0m
[[1mmeshif [4m[22mnetdev[24m] [1mtranstable_global_json[22m|[1mtgj[0m
[[1mmeshif [4m[22mnetdev[24m] [1mtranstable_local_json[22m|[1mtlj[0m
[[1mmeshif [4m[22mnetdev[24m] [1mvid <vid> vlan_json[22m|[1mvj[0m
[1mvlan [4m[22mvdev[24m [1mvlan_json[22m|[1mvj[0m
[1mEXAMPLES[0m
The setup of a batadv interface usually consists of creation of the the
main interface, attaching of the (lower) hard-interface, adjusting of
settings and bringup of the interface:
# create batadv (mesh) interface bat0 with routing algorithm B.A.T.M.A.N. IV
$ [1mbatctl meshif bat0 interface create routing_algo BATMAN_IV[0m
# add the (already up and running) mesh0 interface as lower (hard) interface to bat0
$ [1mbatctl meshif bat0 interface -M add mesh0[0m
# change some settings to better match the requirements of the user
$ [1mbatctl meshif bat0 orig_interval 5000[0m
$ [1mbatctl meshif bat0 distributed_arp_table disable[0m
...
# set the batadv (mesh) interface up before it is possible to use it
$ [1mip link set up dev bat0[0m
This only makes sure that the layer 2 functionality of bat0 is started
up. It is the responsibility of the user to make sure that the bat0 de-
vice itself gets attached to a bridge, configured with an IP address
(manually/DHCP client/...) or integrated in other parts of the system
before it gets used.
Also the attached (lower) hard-interfaces attached to the batadv inter-
face must be configured by the user to support transportation of ether-
net unicast and broadcast packets between its linked peers. The most
common reason for a not working batman-adv mesh are incorrect configu-
rations of the hard-interfaces, hardware, firmware or driver bugs which
prevent that some of the packet types are correctly exchanged.
The current status of interface can be checked using the debug tables.
It is often relevant to check from which direct neighbors discovery
packets were received. The next step is to check the (preferred)
routes to originators. These will only be established when the metric
has detected bidirectional connections between neighbors and might have
forwarded discovery packets from not directly reachable nodes/origina-
tors.
# get list of neighbors from which the current node was able to receive discovery packets
$ [1mbatctl meshif bat0 neighbors[0m
# get (preferred) routes the routing algorithm found
$ [1mbatctl meshif bat0 originators[0m
If the bat0 interface should no longer used by the system, it can be
destroyed again:
# destroy the interface and let the system remove its state
$ [1mbatctl meshif bat0 interface destroy[0m
[1mFILES[0m
[1mbat-hosts[0m
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 direc-
tory. The found data is used to match MAC address to your pro-
vided host name or replace MAC addresses in debug output and
logs. Host names are much easier to remember than MAC addresses.
[1mSEE ALSO[0m
[1mbridge[22m(8), [1mdmesg[22m(1), [1mip[22m(8), [1mip-link[22m(8), [1mping[22m(8), [1mtcpdump[22m(8), [1mtracer-[0m
[1moute[22m(1), [1mtrace-cmd[22m(1)
[1mAUTHOR[0m
batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lind-
ner <marek.lindner@mailbox.org>.
This manual page was written by Simon Wunderlich <sw@simonwunder-
lich.de>, Marek Lindner <marek.lindner@mailbox.org> and Andrew Lunn
<andrew@lunn.ch>
Linux July 17, 2015 [4mBATCTL[24m(8)
Man(1) output converted with
man2html