Provided by: batctl_2023.0-1_amd64 bug

NAME

       batctl - B.A.T.M.A.N. advanced control and management tool

SYNOPSIS

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

DESCRIPTION

       batctl offers a convenient way to configure the batman-adv kernel module as well as
       displaying debug information such as originator tables and translation tables. 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

       -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

       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. 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.

       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.

       [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.  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". 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.

       [meshif netdev] interface|if destroy
              Remove all attached interfaces and destroy the batman-adv interface.

       [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.

       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.

       [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.

       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

       [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.

       [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.

       [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.

SETTINGS

       [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] 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.

       [meshif netdev] ap_isolation|ap [0|1]
       [meshif netdev] vid <vid> ap_isolation|ap [0|1]
       vlan vdev 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] 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.

       [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.

       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] 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.

       [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).

       [hardif hardif] hop_penalty|hp [penalty]
              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 originator message's TQ to zero when forwarded over this
              interface).

       [meshif netdev] isolation_mark|mark [value[/mask]]
              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

       [meshif netdev] loglevel|ll [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
              kernels trace buffers. Use trace-cmd stream -e batadv:batadv_dbg to receive the
              system wide log messages.

       [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] 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] 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] 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.

       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").

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.

       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.

       [meshif netdev] backbonetable|bbt [-n] [-H] [-w interval]
              (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]

JSON QUERIES

       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.

       [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

       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
           $ 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

       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 device 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 interface must be
       configured by the user to support transportation of ethernet unicast and broadcast packets
       between its linked peers. The most common reason for a not working batman-adv mesh are
       incorrect configurations 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/originators.

           # 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

       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
           $ batctl meshif bat0 interface destroy

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

       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
       <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>