batctl - html man page (v2021.0-38-g35d8327)




SYNOPSIS

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


DESCRIPTION

       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 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 perfor-
       mances, 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 mod-
              ule 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 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.

       [meshif <netdev>] interface|if create [routing_algo|ra RA_NAME]
              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.

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

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

       [meshif <netdev>] distributed_arp_table|dat [0|1]
              If no parameter is given the current distributed arp table set-
              ting 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 dis-
              played. 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 dis-
              able fragmentation.

       [meshif <netdev>] hop_penalty|hp [penalty]
              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).

       [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 origina-
              tor message's TQ to zero when forwarded over this interface).

       [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 dis-
              able network coding.

       [meshif <netdev>] multicast_forceflood|mff [0|1]
              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.

       [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 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 'nc' en-
              ables 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>] 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 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

                        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.

       routing_algo|ra [algorithm]
              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.

       hardif <hardif> throughput_override|to [bandwidth]
              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").

       [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 ta-
              bles 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 re-
              move 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 inter-
              face 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)
                        - mcast_flags|mf (compile time option)

       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.


              List of available JSON queries:
                        - bla_backbone_json|bbj
                        - bla_claim_json|clj
                        - dat_cache_json|dcj
                        - gateways_json|gwj
                        - hardif_json|hj
                        - hardifs_json|hj
                        - mcast_flags_json|mfj
                        - mesh_json|mj
                        - neighbors_json|nj
                        - originators_json|oj
                        - transtable_global_json|tgj
       - transtable_local_json|tlj
       - vlan_json|vj

                 [meshif <netdev>] translate|t MAC_ad-
                 dress|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 mod-
                        ule. 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 de-
                        vice 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 mes-
                        sages 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_ad-
                 dress|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 de-
                        vice 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 dis-
                        able 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 ana-
                        lyzed 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

              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.


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


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 Lind-
       ner <mareklindner@neomailbox.ch>.

       This manual page was written by Simon Wunderlich <sw@simonwunder-
       lich.de>, Marek Lindner <mareklindner@neomailbox.ch> and Andrew Lunn
       <andrew@lunn.ch>



Linux                            July 17, 2015                       BATCTL(8)

Man(1) output converted with man2html