Documentation/networking/batman-adv.rst

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