BATCTL(8)

📦
version 2026.3 · 5 versions
, in arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

BATCTL(8) — B.A.T.M.A.N. Advanced Control Tool 💅

okay bestie, sit down, we're doing batctl from the B.A.T.M.A.N. Advanced Control Tool manual, section 8 (that's sysadmin commands, iykyk). this is part 1 of 3 so don't you dare close the tab. ✨

🌸 NAME 🌸

batctl — the B.A.T.M.A.N. advanced control and management tool. she configures, she manages, she's main character energy fr fr.

🎀 SYNOPSIS 🎀

batctl [options] command|debug table|debug JSON [parameters]

🦋 DESCRIPTION 🦋

so like, batctl is your convenient lil bestie for configuring the batman-adv kernel module and for displaying debug info — think originator tables, translation tables, all that tea. 🫖 and here's the cute part: if you team her up with a bat-hosts file, she'll let you use host names instead of those crusty MAC addresses. periodt.

B.A.T.M.A.N. advanced operates on layer 2. that means every host in the virtual switched network is transparently connected to every other host for all protocols above layer 2. which, unfortunately, means the normal diagnosis tools do not work as expected 😭. to fix that little situation, batctl brings along the commands ping, traceroute and tcpdump — they do basically what your regular ping(1), traceroute(1) and tcpdump(1) do, but modified for layer 2 behaviour or using the B.A.T.M.A.N. advanced protocol. iconic behaviour honestly. and for the same reasons she also ships throughputmeter, a command to test network performances. 🏃♀️💨

✨ OPTIONS ✨

  • -m — specify mesh interface (default 'bat0'). yes bestie, bat0 is the default, she lives there. 🏠
  • -h — print general batctl help. the classic "help me" button, no shame in it. 🙈
  • -v — print batctl version and batman-adv version (only if the module is loaded, otherwise girl is just guessing). 🔍

👑 COMMANDS 👑

bisect_iv [-l MAC][-t MAC][-r MAC][-s min [- max]][-o MAC][-n] logfile1 ...

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. 🗂️ then that database can be analysed in a whole bunch of different ways:

  • with -l the database can be used to search for routing loops (spooky).
  • use -t to trace OGMs of a host throughout the network. 👀
  • use -r to display routing tables of the nodes.
  • the option -s limits 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.

event|e [-t|-r]

batctl will monitor for events from the netlink kernel interface of batman-adv. 👁️ the local timestamp of the event gets printed when parameter -t is specified. parameter -r does the same thing but with relative timestamps. cute, right?

[meshif netdev] interface|if

[meshif netdev] interface|if [-M] add|del iface ...

if no parameter is given, or the first parameter is neither "add" nor "del", the current interface settings are displayed. 🖥️

want to add or delete interfaces? specify "add" or "del" as the first argument and append the interface names you wish to add or delete. multiple interfaces can be specified, no cap. 💅

the -M option tells batctl to not automatically create the batman-adv interface on "add". it can also be used to suppress the warning about the manual destruction when "del" removed all interfaces which belonged to it.

[meshif netdev] interface|if create [routing_algo|ra RA_NAME]

a batman-adv interface without attached interfaces can be created using "create". the parameter routing_algo can be used to overwrite the (default) routing algorithm. glow up on your own terms bestie ✨

[meshif netdev] interface|if destroy

remove all attached interfaces and destroy the batman-adv interface. 💀 it's giving demolition day.

[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. she can also try to guess the MAC address using an IPv4/IPv6 address or a hostname — but only 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. conditions, conditions.

  • -c tells batctl how many pings should be sent before the program exits. without -c, batctl will keep pinging without end. use CTRL + C to stop it. 🛑
  • -i and -t set the default interval between pings and the timeout time for replies, both in seconds.
  • -R records the route taken by the ping messages. 🗺️
  • -T disables the automatic translation of a client MAC address to the originator address which is responsible for this client.

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. choose your fighter 🥊

[meshif netdev] statistics|s

retrieve traffic counters from the 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. no prefix, no problem. 🍓

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 -c (the compat filter).
  • 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 🧮 (yes bestie, 129 = 1 + 128, math is giving slay)

[meshif netdev] throughputmeter|tp MAC

this command starts a throughput test entirely controlled by the batman module in kernel space: the computational resources needed to align memory and copy data between user and kernel space — which other user space tools require — may represent a bottleneck on some low profile device. basically: built different, runs faster. 🔥

the test consists 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. 😭

[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. she can also try to guess the MAC address using an IPv4/IPv6 address or a hostname — but again only 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.

[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. 🔁 it's giving "who's your originator bestie?"

part 1 done, but we're not finished — more of this manual is coming, so stay tuned bestie 💖

✨ SETTINGS ✨

okay bestie, this is the main character energy of batctl — all the knobs you can twist on your mesh. let's go 💅

  • [meshif netdev] aggregation|ag [0|1] — if you don't drop a parameter, it shows you the current aggregation setting. otherwise, that parameter toggles OGM packet aggregation on or off. ✨
  • [meshif netdev] ap_isolation|ap [0|1] — no parameter? it shows the current ap isolation setting. give it one and it enables or disables ap isolation. 🦋
  • [meshif netdev] ap_isolation|ap [0|1] [meshif netdev] vid <vid> ap_isolation|ap [0|1] vlan vdev ap_isolation|ap [0|1] — if you don't pass a parameter, it shows the current ap isolation setting for the specified VLAN. otherwise, the parameter enables or disables ap isolation for that VLAN. 💜
  • [meshif netdev] bonding|b [0|1] — no parameter means it shows the current bonding mode setting. otherwise, it enables or disables bonding mode. 🔥
  • [meshif netdev] bridge_loop_avoidance|bl [0|1] — no parameter? you get the current bridge loop avoidance setting. otherwise, it enables or disables bridge loop avoidance. heads up: bridge loop avoidance support has to be enabled when compiling the module, otherwise this option won't be available at all. 😭
  • [meshif netdev] distributed_arp_table|dat [0|1] — no parameter shows the current distributed arp table setting. otherwise, it enables or disables the distributed arp table. 🌈
  • hardif hardif elp_interval|et [interval] — no parameter? it displays the current ELP interval setting of the hard interface. otherwise, the parameter sets the ELP interval. the interval is in units of milliseconds. ⏱️
  • [meshif netdev] fragmentation|f [0|1] — no parameter means you see the current fragmentation mode setting. otherwise, it enables or disables fragmentation. 💅
  • [meshif netdev] gw_mode|gw [off|client|server] [sel_class|bandwidth] — if you don't give a parameter, it shows the current gateway mode. otherwise, the parameter sets 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 informs 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 decides 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.
  • [meshif netdev] hop_penalty|hp [penalty] — no parameter? it shows the current hop penalty setting. otherwise, the parameter sets the hop penalty. the penalty can be 0-255 (255 sets originator message's TQ to zero when forwarded by this hop). 👑
  • [hardif hardif] hop_penalty|hp [penalty] — no parameter shows the current hop penalty setting of the hard interface. otherwise, the parameter sets the hop penalty. the penalty can be 0-255 (255 sets originator message's TQ to zero when forwarded over this interface). 💖
  • [meshif netdev] isolation_mark|mark [value[/mask]] — no parameter? it displays the current isolation mark value. otherwise, the parameter sets or unsets 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. you can also 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

  • [meshif netdev] loglevel|ll [level ...] — no parameter? you see the current log level settings. otherwise, the parameter(s) 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 '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 kernels trace buffers. use trace-cmd stream -e batadv:batadv_dbg to receive the system wide log messages. 📝
  • [meshif netdev] multicast_fanout|mo [fanout] — no parameter? it shows the current multicast fanout setting. otherwise, the parameter sets 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] multicast_forceflood|mff [0|1] — no parameter means you get the current multicast forceflood setting. otherwise, it enables or disables 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] orig_interval|it [interval] — no parameter? it shows the current originator interval setting. otherwise, the parameter sets the originator interval. the interval is in units of milliseconds. ⏳
  • hardif hardif throughput_override|to [bandwidth] — no parameter? it displays the current througput override. otherwise, the parameter sets the throughput override for the specified hard interface. just enter any number (optionally followed by "kbit" or "mbit"). 💨

🔍 DEBUG TABLES 🔍

okay bestie so the batman-adv kernel module ships with a whole ✨collection✨ of debug tables, and each one is basically a little window into the state of the mesh as that specific node sees it. every single node got its own view, it's giving very main character of each of them 💅

all of the debug tables support these options, no exceptions:

  • -w — refresh the list every second, or tack a number on there and it'll refresh at your custom interval in seconds (decimal places allowed, fancy 💖)
  • -n — do not swap out the MAC addresses for bat-host names in the output
  • -H — do not show the header of the debug table

the originator table is extra and also supports the -t filter option, which yeets all the originators out of the output that haven't been seen for the number of seconds you specify (again, decimals? allowed 🎀). it furthermore supports the -i parameter so you can name a specific interface whose originator table you want printed. no -i? then you just get the default originator table, easy peasy.

the local and global translation tables also support the -u and -m options, so you can only display unicast or multicast translation table announcements respectively 🌸

[meshif netdev] backbonetable|bbt [-n] [-H] [-winterval]
       (compile time option)

[meshif netdev] claimtable|cl [-n] [-H] [-w[interval]]

[meshif netdev] dat_cache|dc [-n] [-H] [-w[interval]]
       (compile time option)

[meshif netdev] gateways|gwl [-n] [-H] [-w[interval]]

[meshif netdev] mcast_flags|mf [-n] [-H] [-w[interval]]
       (compile time option)

[meshif netdev] neighbors|n [-n] [-H] [-w[interval]]

[meshif netdev] originators|o [-n] [-H] [-w[interval]] [-t
timeout_interval] [-i interface]

[meshif netdev] transglobal|tg [-n] [-H] [-w[interval]] [-u] [-m]
       (compile time option)

[meshif netdev] translocal|tl [-n] [-H] [-w[interval]] [-u] [-m]
ngl, the ones marked (compile time option) only exist if the module was built with them enabled, so if a table is acting shy and refusing to show up, that's probably why 🙈

🦋 JSON QUERIES 🦋

so the generic netlink family that the batman-adv kernel module gives you can be queried — read-only, bestie, don't get any ideas — by batctl, and it gets automatically translated to JSON. no cap, this is the move for monitoring the state of your system without having to parse the freeform debug tables or the raw native netlink messages. it's giving ✨convenience✨

[meshif netdev] bla_backbone_json|bbj

[meshif netdev] bla_claim_json|clj

[meshif netdev] dat_cache_json|dcj

[meshif netdev] gateways_json|gwj

hardif hardif hardif_json|hj

[meshif netdev] hardifs_json|hj

[meshif netdev] mcast_flags_json|mfj

[meshif netdev] mesh_json|mj

[meshif netdev] neighbors_json|nj

[meshif netdev] originators_json|oj

[meshif netdev] transtable_global_json|tgj

[meshif netdev] transtable_local_json|tlj

[meshif netdev] vid <vid> vlan_json|vj
vlan vdev vlan_json|vj

🌈 EXAMPLES 🌈

setting up a batadv interface is lowkey a whole little ritual. usually it goes: create the main interface, attach the (lower) hard-interface, adjust the settings, then bring the interface up 🫶

# create batadv (mesh) interface bat0 with routing algorithm B.A.T.M.A.N. IV
$ batctl meshif bat0 interface create routing_algo BATMAN_IV
# add the (already up and running) mesh0 interface as lower (hard) interface to bat0
$ batctl meshif bat0 interface -M add mesh0
# change some settings to better match the requirements of the user
$ batctl meshif bat0 orig_interval 5000
$ batctl meshif bat0 distributed_arp_table disable
...
# set the batadv (mesh) interface up before it is possible to use it
$ ip link set up dev bat0

important bestie: this only makes sure that the layer 2 functionality of bat0 is started up. that's it. it is the responsibility of the user (that's you 💅) to make sure the bat0 device itself gets attached to a bridge, configured with an IP address (manually / DHCP client / ...) or integrated into other parts of the system before it gets used.

also, the attached (lower) hard-interfaces attached to the batadv interface must be configured by the user so they actually support transportation of ethernet unicast and broadcast packets between its linked peers. and fr fr, the most common reason for a batman-adv mesh that just refuses to work? incorrect configurations of the hard-interfaces, plus hardware, firmware or driver bugs that stop some of the packet types from being correctly exchanged 😭

you can check the current status of the interface using the debug tables. it's often relevant to check which direct neighbors discovery packets were received from. then the next step is checking the (preferred) routes to originators. those only get established once the metric has detected bidirectional connections between neighbors, and they might have forwarded discovery packets from nodes/originators that aren't directly reachable 🌸

# get list of neighbors from which the current node was able to receive discovery packets
$ batctl meshif bat0 neighbors
# get (preferred) routes the routing algorithm found
$ batctl meshif bat0 originators

and if the bat0 interface should no longer be used by the system, you can just destroy it again. slay 💅

# destroy the interface and let the system remove its state
$ batctl meshif bat0 interface destroy

📁 FILES 📁

  • bat-hosts — this file is basically the /etc/hosts file's cousin ✨ you write one MAC address and one host name per line. batctl will go looking for bat-hosts in /etc, your home directory and the current directory. the data it finds gets used to match a MAC address to the host name you provided, or to replace MAC addresses in debug output and logs. host names are so much easier to remember than MAC addresses, iykyk 💖

👀 SEE ALSO 👀

bridge(8), dmesg(1), ip(8), ip-link(8), ping(8), tcpdump(8), traceroute(1), trace-cmd(1)

👑 AUTHOR 👑

batctl was written by Andreas Langer <an.langer@gmx.de> and Marek Lindner <marek.lindner@mailbox.org>.

This manual page was written by Simon Wunderlich <sw@simonwunderlich.de>, Marek Lindner <marek.lindner@mailbox.org> and Andrew Lunn <andrew@lunn.ch>

and that's a wrap on the whole page bestie!! 🎀 this was the Linux version of the page, dated July 17, 2015, living its life as BATCTL(8) — go forth and mesh responsibly, you absolute icon 🦋💜

📦 where this page comes from