Documentation/networking/batman-adv.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==========
   4 batman-adv
   5 ==========
   6
   7 Batman advanced is a new approach to wireless networking which does no longer
   8 operate on the IP basis. Unlike the batman daemon, which exchanges information
   9 using UDP packets and sets routing tables, batman-advanced operates on ISO/OSI
  10 Layer 2 only and uses and routes (or better: bridges) Ethernet Frames. It
  11 emulates a virtual network switch of all nodes participating. Therefore all
  12 nodes appear to be link local, thus all higher operating protocols won't be
  13 affected by any changes within the network. You can run almost any protocol
  14 above batman advanced, prominent examples are: IPv4, IPv6, DHCP, IPX.
  15
  16 Batman advanced was implemented as a Linux kernel driver to reduce the overhead
  17 to a minimum. It does not depend on any (other) network driver, and can be used
  18 on wifi as well as ethernet lan, vpn, etc ... (anything with ethernet-style
  19 layer 2).
  20
  21
  22 Configuration
  23 =============
  24
  25 Load the batman-adv module into your kernel::
  26
  27   $ insmod batman-adv.ko
  28
  29 The module is now waiting for activation. You must add some interfaces on which
  30 batman can operate. After loading the module batman advanced will scan your
  31 systems interfaces to search for compatible interfaces. Once found, it will
  32 create subfolders in the ``/sys`` directories of each supported interface,
  33 e.g.::
  34
  35   $ ls /sys/class/net/eth0/batman_adv/
  36   elp_interval iface_status mesh_iface throughput_override
  37
  38 If an interface does not have the ``batman_adv`` subfolder, it probably is not
  39 supported. Not supported interfaces are: loopback, non-ethernet and batman's
  40 own interfaces.
  41
  42 Note: After the module was loaded it will continuously watch for new
  43 interfaces to verify the compatibility. There is no need to reload the module
  44 if you plug your USB wifi adapter into your machine after batman advanced was
  45 initially loaded.
  46
  47 The batman-adv soft-interface can be created using the iproute2 tool ``ip``::
  48
  49   $ ip link add name bat0 type batadv
  50
  51 To activate a given interface simply attach it to the ``bat0`` interface::
  52
  53   $ ip link set dev eth0 master bat0
  54
  55 Repeat this step for all interfaces you wish to add. Now batman starts
  56 using/broadcasting on this/these interface(s).
  57
  58 By reading the "iface_status" file you can check its status::
  59
  60   $ cat /sys/class/net/eth0/batman_adv/iface_status
  61   active
  62
  63 To deactivate an interface you have to detach it from the "bat0" interface::
  64
  65   $ ip link set dev eth0 nomaster
  66
  67
  68 All mesh wide settings can be found in batman's own interface folder::
  69
  70   $ ls /sys/class/net/bat0/mesh/
  71   aggregated_ogms       fragmentation isolation_mark routing_algo
  72   ap_isolation          gw_bandwidth  log_level      vlan0
  73   bonding               gw_mode       multicast_mode
  74   bridge_loop_avoidance gw_sel_class  network_coding
  75   distributed_arp_table hop_penalty   orig_interval
  76
  77 There is a special folder for debugging information::
  78
  79   $ ls /sys/kernel/debug/batman_adv/bat0/
  80   bla_backbone_table log         neighbors         transtable_local
  81   bla_claim_table    mcast_flags originators
  82   dat_cache          nc          socket
  83   gateways           nc_nodes    transtable_global
  84
  85 Some of the files contain all sort of status information regarding the mesh
  86 network. For example, you can view the table of originators (mesh
  87 participants) with::
  88
  89   $ cat /sys/kernel/debug/batman_adv/bat0/originators
  90
  91 Other files allow to change batman's behaviour to better fit your requirements.
  92 For instance, you can check the current originator interval (value in
  93 milliseconds which determines how often batman sends its broadcast packets)::
  94
  95   $ cat /sys/class/net/bat0/mesh/orig_interval
  96   1000
  97
  98 and also change its value::
  99
 100   $ echo 3000 > /sys/class/net/bat0/mesh/orig_interval
 101
 102 In very mobile scenarios, you might want to adjust the originator interval to a
 103 lower value. This will make the mesh more responsive to topology changes, but
 104 will also increase the overhead.
 105
 106
 107 Usage
 108 =====
 109
 110 To make use of your newly created mesh, batman advanced provides a new
 111 interface "bat0" which you should use from this point on. All interfaces added
 112 to batman advanced are not relevant any longer because batman handles them for
 113 you. Basically, one "hands over" the data by using the batman interface and
 114 batman will make sure it reaches its destination.
 115
 116 The "bat0" interface can be used like any other regular interface. It needs an
 117 IP address which can be either statically configured or dynamically (by using
 118 DHCP or similar services)::
 119
 120   NodeA: ip link set up dev bat0
 121   NodeA: ip addr add 192.168.0.1/24 dev bat0
 122
 123   NodeB: ip link set up dev bat0
 124   NodeB: ip addr add 192.168.0.2/24 dev bat0
 125   NodeB: ping 192.168.0.1
 126
 127 Note: In order to avoid problems remove all IP addresses previously assigned to
 128 interfaces now used by batman advanced, e.g.::
 129
 130   $ ip addr flush dev eth0
 131
 132
 133 Logging/Debugging
 134 =================
 135
 136 All error messages, warnings and information messages are sent to the kernel
 137 log. Depending on your operating system distribution this can be read in one of
 138 a number of ways. Try using the commands: ``dmesg``, ``logread``, or looking in
 139 the files ``/var/log/kern.log`` or ``/var/log/syslog``. All batman-adv messages
 140 are prefixed with "batman-adv:" So to see just these messages try::
 141
 142   $ dmesg | grep batman-adv
 143
 144 When investigating problems with your mesh network, it is sometimes necessary to
 145 see more detail debug messages. This must be enabled when compiling the
 146 batman-adv module. When building batman-adv as part of kernel, use "make
 147 menuconfig" and enable the option ``B.A.T.M.A.N. debugging``
 148 (``CONFIG_BATMAN_ADV_DEBUG=y``).
 149
 150 Those additional debug messages can be accessed using a special file in
 151 debugfs::
 152
 153   $ cat /sys/kernel/debug/batman_adv/bat0/log
 154
 155 The additional debug output is by default disabled. It can be enabled during
 156 run time. Following log_levels are defined:
 157
 158 .. flat-table::
 159
 160    * - 0
 161      - All debug output disabled
 162    * - 1
 163      - Enable messages related to routing / flooding / broadcasting
 164    * - 2
 165      - Enable messages related to route added / changed / deleted
 166    * - 4
 167      - Enable messages related to translation table operations
 168    * - 8
 169      - Enable messages related to bridge loop avoidance
 170    * - 16
 171      - Enable messages related to DAT, ARP snooping and parsing
 172    * - 32
 173      - Enable messages related to network coding
 174    * - 64
 175      - Enable messages related to multicast
 176    * - 128
 177      - Enable messages related to throughput meter
 178    * - 255
 179      - Enable all messages
 180
 181 The debug output can be changed at runtime using the file
 182 ``/sys/class/net/bat0/mesh/log_level``. e.g.::
 183
 184   $ echo 6 > /sys/class/net/bat0/mesh/log_level
 185
 186 will enable debug messages for when routes change.
 187
 188 Counters for different types of packets entering and leaving the batman-adv
 189 module are available through ethtool::
 190
 191   $ ethtool --statistics bat0
 192
 193
 194 batctl
 195 ======
 196
 197 As batman advanced operates on layer 2, all hosts participating in the virtual
 198 switch are completely transparent for all protocols above layer 2. Therefore
 199 the common diagnosis tools do not work as expected. To overcome these problems,
 200 batctl was created. At the moment the batctl contains ping, traceroute, tcpdump
 201 and interfaces to the kernel module settings.
 202
 203 For more information, please see the manpage (``man batctl``).
 204
 205 batctl is available on https://www.open-mesh.org/
 206
 207
 208 Contact
 209 =======
 210
 211 Please send us comments, experiences, questions, anything :)
 212
 213 IRC:
 214   #batman on irc.freenode.org
 215 Mailing-list:
 216   b.a.t.m.a.n@open-mesh.org (optional subscription at
 217   https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
 218
 219 You can also contact the Authors:
 220
 221 * Marek Lindner <mareklindner@neomailbox.ch>
 222 * Simon Wunderlich <sw@simonwunderlich.de>