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 Some files allow to change batman-adv's behaviour to better fit your
  78 requirements. For instance, you can check the current originator interval (value
  79 in milliseconds which determines how often batman sends its broadcast packets)::
  80
  81   $ cat /sys/class/net/bat0/mesh/orig_interval
  82   1000
  83
  84 and also change its value::
  85
  86   $ echo 3000 > /sys/class/net/bat0/mesh/orig_interval
  87
  88 In very mobile scenarios, you might want to adjust the originator interval to a
  89 lower value. This will make the mesh more responsive to topology changes, but
  90 will also increase the overhead.
  91
  92 Information about the current state can be accessed via the batadv generic
  93 netlink family. batctl provides human readable version via its debug tables
  94 subcommands.
  95
  96
  97 Usage
  98 =====
  99
 100 To make use of your newly created mesh, batman advanced provides a new
 101 interface "bat0" which you should use from this point on. All interfaces added
 102 to batman advanced are not relevant any longer because batman handles them for
 103 you. Basically, one "hands over" the data by using the batman interface and
 104 batman will make sure it reaches its destination.
 105
 106 The "bat0" interface can be used like any other regular interface. It needs an
 107 IP address which can be either statically configured or dynamically (by using
 108 DHCP or similar services)::
 109
 110   NodeA: ip link set up dev bat0
 111   NodeA: ip addr add 192.168.0.1/24 dev bat0
 112
 113   NodeB: ip link set up dev bat0
 114   NodeB: ip addr add 192.168.0.2/24 dev bat0
 115   NodeB: ping 192.168.0.1
 116
 117 Note: In order to avoid problems remove all IP addresses previously assigned to
 118 interfaces now used by batman advanced, e.g.::
 119
 120   $ ip addr flush dev eth0
 121
 122
 123 Logging/Debugging
 124 =================
 125
 126 All error messages, warnings and information messages are sent to the kernel
 127 log. Depending on your operating system distribution this can be read in one of
 128 a number of ways. Try using the commands: ``dmesg``, ``logread``, or looking in
 129 the files ``/var/log/kern.log`` or ``/var/log/syslog``. All batman-adv messages
 130 are prefixed with "batman-adv:" So to see just these messages try::
 131
 132   $ dmesg | grep batman-adv
 133
 134 When investigating problems with your mesh network, it is sometimes necessary to
 135 see more detail debug messages. This must be enabled when compiling the
 136 batman-adv module. When building batman-adv as part of kernel, use "make
 137 menuconfig" and enable the option ``B.A.T.M.A.N. debugging``
 138 (``CONFIG_BATMAN_ADV_DEBUG=y``).
 139
 140 Those additional debug messages can be accessed using the perf infrastructure::
 141
 142   $ trace-cmd stream -e batadv:batadv_dbg
 143
 144 The additional debug output is by default disabled. It can be enabled during
 145 run time. Following log_levels are defined:
 146
 147 .. flat-table::
 148
 149    * - 0
 150      - All debug output disabled
 151    * - 1
 152      - Enable messages related to routing / flooding / broadcasting
 153    * - 2
 154      - Enable messages related to route added / changed / deleted
 155    * - 4
 156      - Enable messages related to translation table operations
 157    * - 8
 158      - Enable messages related to bridge loop avoidance
 159    * - 16
 160      - Enable messages related to DAT, ARP snooping and parsing
 161    * - 32
 162      - Enable messages related to network coding
 163    * - 64
 164      - Enable messages related to multicast
 165    * - 128
 166      - Enable messages related to throughput meter
 167    * - 255
 168      - Enable all messages
 169
 170 The debug output can be changed at runtime using the file
 171 ``/sys/class/net/bat0/mesh/log_level``. e.g.::
 172
 173   $ echo 6 > /sys/class/net/bat0/mesh/log_level
 174
 175 will enable debug messages for when routes change.
 176
 177 Counters for different types of packets entering and leaving the batman-adv
 178 module are available through ethtool::
 179
 180   $ ethtool --statistics bat0
 181
 182
 183 batctl
 184 ======
 185
 186 As batman advanced operates on layer 2, all hosts participating in the virtual
 187 switch are completely transparent for all protocols above layer 2. Therefore
 188 the common diagnosis tools do not work as expected. To overcome these problems,
 189 batctl was created. At the moment the batctl contains ping, traceroute, tcpdump
 190 and interfaces to the kernel module settings.
 191
 192 For more information, please see the manpage (``man batctl``).
 193
 194 batctl is available on https://www.open-mesh.org/
 195
 196
 197 Contact
 198 =======
 199
 200 Please send us comments, experiences, questions, anything :)
 201
 202 IRC:
 203   #batman on irc.freenode.org
 204 Mailing-list:
 205   b.a.t.m.a.n@open-mesh.org (optional subscription at
 206   https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
 207
 208 You can also contact the Authors:
 209
 210 * Marek Lindner <mareklindner@neomailbox.ch>
 211 * Simon Wunderlich <sw@simonwunderlich.de>