Provided by: batctl_2013.4.0-2_amd64 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 (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.

       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.

       vis_mode|vm [client|server]
              If no parameter is given the current vis mode is displayed otherwise the parameter
              is used to set the vis mode.

       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.

       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 guess your appropriate gateway class. 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: 2000 -> gateway class 20
                       examples: 5000 -> gateway class 49
                                 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).

       vis_data|vd dot [-n|--numbers][-T|--no-TT][-2|--no-2nd]
              Display the visualisation data in graphviz dot(1) format. If "--numbers" or "-n" is
              given batctl will not replace the MAC addresses with bat-host names in the output.
              With "--no-TT" or "-T" the TT entries are not displayed, so the pure mesh topology
              can be seen. With "--no-2nd" or "-2" a dot cluster is not formed around primary and
              secondary addresses from the same device.

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

              List of debug tables:
                        - 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 vis 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>