Provided by: batctl_2016.0-2_i386 bug

NAME

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

SYNOPSIS

       batctl [options] command|debug table [parameters]

DESCRIPTION

       batctl offers a convenient way to configure the batman-adv kernel
       module as well as displaying debug information such as originator
       tables, translation tables and the debug log. In combination with a
       bat-hosts file batctl allows the use of host names instead of MAC
       addresses.

       B.A.T.M.A.N. advanced operates on layer 2. Thus all hosts participating
       in the virtual switched network are transparently connected together
       for all protocols above layer 2. Therefore the common diagnosis tools
       do not work as expected. To overcome these problems batctl contains the
       commands ping, traceroute, tcpdump which provide similar functionality
       to the normal ping(1), traceroute(1), tcpdump(1) commands, but modified
       to layer 2 behaviour or using the B.A.T.M.A.N. advanced protocol.

OPTIONS

       options:
              -m     specify mesh interface or VLAN created on top of a mesh
              interface (default 'bat0')
              -h     print general batctl help
              -v     print batctl version and batman-adv version (if the
              module is loaded)

       commands:

       interface|if [add|del iface(s)]
              If no parameter is given or the first parameter is neither "add"
              nor "del" the current interface settings are displayed.  In
              order to add or delete interfaces specify "add" or "del" as
              first argument and append the interface names you wish to add or
              delete. Multiple interfaces can be specified.

       orig_interval|it [interval]
              If no parameter is given the current originator interval setting
              is displayed otherwise the parameter is used to set the
              originator interval. The interval is in units of milliseconds.

       ap_isolation|ap [0|1]
              If no parameter is given the current ap isolation setting is
              displayed. Otherwise the parameter is used to enable or disable
              ap isolation. This command can be used in conjunction with "-m"
              option to target per VLAN configurations.

       bridge_loop_avoidance|bl [0|1]
              If no parameter is given the current bridge loop avoidance
              setting is displayed. Otherwise the parameter is used to enable
              or disable the bridge loop avoidance. Bridge loop avoidance
              support has to be enabled when compiling the module otherwise
              this option won't be available.

       distributed_arp_table|dat [0|1]
              If no parameter is given the current distributed arp table
              setting is displayed. Otherwise the parameter is used to enable
              or disable the distributed arp table.

       aggregation|ag [0|1]
              If no parameter is given the current aggregation setting is
              displayed. Otherwise the parameter is used to enable or disable
              OGM packet aggregation.

       bonding|b [0|1]
              If no parameter is given the current bonding mode setting is
              displayed. Otherwise the parameter is used to enable or disable
              the bonding mode.

       fragmentation|f [0|1]
              If no parameter is given the current fragmentation mode setting
              is displayed. Otherwise the parameter is used to enable or
              disable fragmentation.

       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.

       multicast_mode|mm [0|1]
              If no parameter is given the current multicast mode setting is
              displayed. Otherwise the parameter is used to enable or disable
              multicast optimizations (i.e. disabling means always sending own
              multicast frames via classic flooding).

       loglevel|ll [level[ level[ level]] ...]
              If no parameter is given the current log level settings are
              displayed otherwise the parameter(s) is/are used to set the log
              level. Level 'none' disables all verbose logging. Level 'batman'
              enables messages related to routing / flooding / broadcasting.
              Level 'routes' enables messages related to routes being added /
              changed / deleted. Level 'tt' enables messages related to
              translation table operations. Level 'bla' enables messages
              related to the bridge loop avoidance. Level 'dat' enables
              messages related to ARP snooping and the Distributed Arp Table.
              Level 'nc' enables messages related to network coding.  Level
              'all' enables all messages. The messages are sent to the batman-
              adv debug log. Use batctl log to retrieve it.  Make sure to have
              debugging output enabled when compiling the module otherwise the
              output as well as the loglevel options won't be available.

       log|l [-n]
              batctl will read the batman-adv debug log which has to be
              compiled into the kernel module. If "-n" is given batctl will
              not replace the MAC addresses with bat-host names in the output.

       gw_mode|gw [off|client|server] [sel_class|bandwidth]
              If no parameter is given the current gateway mode is displayed
              otherwise the parameter is used to set the gateway mode. The
              second (optional) argument specifies the selection class (if
              'client' was the first argument) or the gateway bandwidth (if
              'server' was the first argument). If the node is a server this
              parameter is used to inform other nodes in the network about
              this node's internet connection bandwidth. Just enter any number
              (optionally followed by "kbit" or "mbit") and the batman-adv
              module will propagate the entered value in the mesh. Use "/" to
              separate the down‐ and upload rates. You can omit the upload
              rate and the module will assume an upload of download / 5.
                        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
              criterias to consider when the batman-adv module has to choose
              between different internet connections announced by the
              aforementioned servers.
                        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).

       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.

       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
              tables containing various information about the state of the
              mesh seen by each individual node. These tables are exported via
              debugfs and easily accessible via batctl. You will need debugfs
              support compiled into your kernel and preferably have mounted
              the debugfs to a well-known mountpoint. If debugfs is not
              mounted batctl will attempt to do this step for you.

              All of the debug tables support the following options:
                 -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.

              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)
                        - nc_nodes|nn (compile time option)

       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.

       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.

       ping|p [-c count][-i interval][-t time][-R][-T]
       MAC_address|bat-host_name|host_name|IP_address
              Layer 2 ping of a MAC address or bat-host name.  batctl will try
              to find the bat-host name if the given parameter was not a MAC
              address. It can also try to guess the MAC address using an
              IPv4/IPv6 address or a hostname when the IPv4/IPv6 address was
              configured on top of the batman-adv interface of the destination
              device and both source and destination devices are in the same
              IP subnet.  The "-c" option tells batctl how man pings should be
              sent before the program exits. Without the "-c" option batctl
              will continue pinging without end. Use CTRL + C to stop it.
              With "-i" and "-t" you can set the default interval between
              pings and the timeout time for replies, both in seconds. When
              run with "-R", the route taken by the ping messages will be
              recorded. With "-T" you can disable the automatic translation of
              a client MAC address to the originator address which is
              responsible for this client.

       traceroute|tr [-n][-T] MAC_address|bat-host_name|host_name|IP_address
              Layer 2 traceroute to a MAC address or bat-host name. batctl
              will try to find the bat-host name if the given parameter was
              not a MAC address. It can also try to guess the MAC address
              using an IPv4/IPv6 address or a hostname when the IPv4/IPv6
              address was configured on top of the batman-adv interface of the
              destination device and both source and destination devices are
              in the same IP subnet.  batctl will send 3 packets to each host
              and display the response time. If "-n" is given batctl will not
              replace the MAC addresses with bat-host names in the output.
              With "-T" you can disable the automatic translation of a client
              MAC address to the originator address which is responsible for
              this 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 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.

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

       ping(1), traceroute(1), tcpdump(1), dmesg(1), dot(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>