drivers/staging/batman-adv/README

   1 [state: 22-03-2010]
   2
   3 BATMAN-ADV
   4 ----------
   5
   6 Batman-advanced is a new approach to wireless networking which does no longer
   7 operate on the IP basis. Unlike B.A.T.M.A.N, which exchanges information
   8 using UDP packets and sets routing tables, batman-advanced operates on ISO/OSI
   9 Layer 2 only and uses and routes (or better: bridges) Ethernet Frames. It
  10 emulates a virtual network switch of all nodes participating. Therefore all
  11 nodes appear to be link local, thus all higher operating protocols won't be
  12 affected by any changes within the network. You can run almost any protocol
  13 above B.A.T.M.A.N. Advanced, prominent examples are: IPv4, IPv6, DHCP, IPX.
  14
  15 This is batman-advanced implemented as Linux kernel driver. It does not depend
  16 on any network (other) driver, and can be used on wifi as well as ethernet,
  17 vpn, etc ... (anything with ethernet-style layer 2).
  18
  19 USAGE
  20 -----
  21
  22 insmod the batman-adv.ko in your kernel:
  23
  24 # insmod batman-adv.ko
  25
  26 the module is now waiting for activation. You must add some interfaces
  27 on which batman can operate. Each interface must be added separately:
  28
  29 # echo wlan0 > /proc/net/batman-adv/interfaces
  30
  31 ( # echo wlan1 > /proc/net/batman-adv/interfaces )
  32 ( # echo eth0 > /proc/net/batman-adv/interfaces )
  33 ( ... )
  34
  35 Now batman starts broadcasting on this interface.
  36 You can now view the table of originators (mesh participants) with:
  37
  38 # cat /proc/net/batman-adv/originators
  39
  40 The module will create a new interface "bat0", which can be used as a
  41 regular interface:
  42
  43 # ifconfig bat0 inet 192.168.0.1 up
  44 # ping 192.168.0.2
  45 ...
  46
  47 ---
  48 If you want topology visualization, your meshnode must be configured
  49 as VIS-server:
  50
  51 # echo "server" > /proc/net/batman-adv/vis_server
  52
  53 Each node is either configured as "server" or as "client" (default:
  54 "client"). Clients send their topology data to the server next to them,
  55 and server synchronize with other servers. If there is no server
  56 configured (default) within the mesh, no topology information will be
  57 transmitted. With these "synchronizing servers", there can be 1 or
  58 more vis servers sharing the same (or at least very similar) data.
  59
  60 When configured as server, you can get a topology snapshot of your mesh:
  61
  62 # cat /proc/net/batman-adv/vis_data
  63
  64 This raw output is intended to be easily parsable and convertable with
  65 other tools. Have a look at the batctl README if you want a vis output
  66 in dot or json format for instance and how those outputs could then be
  67 visualised in an image.
  68
  69 The raw format consists of comma seperated values per entry where each
  70 entry is giving information about a certain source interface. Each entry
  71 can/has to have the following values:
  72 -> "mac" -> mac address of an originator's source interface
  73            (each line begins with it)
  74 -> "TQ mac value" -> src mac's link quality towards mac address of a neighbor
  75                      originator's interface which is being used for routing
  76 -> "HNA mac" -> HNA announced by source mac
  77 -> "PRIMARY" -> this is a primary interface
  78 -> "SEC mac" -> secondary mac address of source (requires preceeding
  79 -> PRIMARY)
  80
  81 The TQ value has a range from 4 to 255 with 255 being the best.
  82 The HNA entries are showing which hosts are connected to the mesh via bat0
  83 or being bridged into the mesh network.
  84 The PRIMARY/SEC values are only applied on primary interfaces
  85
  86 ---
  87 In very mobile scenarios, you might want to adjust the originator
  88 interval to a lower value. This will make the mesh more responsive to
  89 topology changes, but will also increase the overhead. Please make sure
  90 that all nodes in your mesh use the same interval. The default value
  91 is 1000 ms (1 second).
  92
  93 # echo 1000 > /proc/net/batman-adv/orig_interval
  94
  95 To deactivate batman, do:
  96
  97 # echo "" > /proc/net/batman-adv/interfaces
  98
  99 LOGGING/DEBUGGING
 100 -----------------
 101
 102 All error messages, warnings and information messages are sent to the
 103 kernel log. Depending on your operating system distribution this can be
 104 read in one of a number of ways. Try using the commands: dmesg,
 105 logread, or looking in the files /var/log/kern.log or
 106 /var/log/syslog. All batman-adv messages are prefixed with
 107 "batman-adv:" So to see just these messages try
 108
 109 dmesg | grep batman-adv
 110
 111 When investigating problems with your mesh network it is sometimes
 112 necessary to see more detail debug messages. This must be enabled when
 113 compiling the batman-adv module. Use "make menuconfig" and enable the
 114 option "B.A.T.M.A.N. debugging".
 115
 116 The additional debug output is by default disabled. It can be enabled
 117 either at kernel module load time or during run time. To enable debug
 118 output at module load time, add the module parameter debug=<value>.
 119 <value> can take one of four values.
 120
 121 0 - All debug output disabled
 122 1 - Enable messages related to routing / flooding / broadcasting
 123 2 - Enable route or hna added / changed / deleted
 124 3 - Enable all messages
 125
 126 e.g.
 127
 128 modprobe batman-adv debug=2
 129
 130 will load the module and enable debug messages for when routes or HNAs
 131 change.
 132
 133 The debug output can also be changed at runtime using the file
 134 /sys/module/batman-adv/parameters/debug. e.g.
 135
 136 echo 2 > /sys/module/batman-adv/parameters/debug
 137
 138 enables debug messages for when routes or HNAs
 139
 140 The debug output is sent to the kernel logs. So try dmesg, logread etc
 141 to see the debug messages.
 142
 143 BATCTL
 144 ------
 145
 146 B.A.T.M.A.N.  advanced operates on layer 2 and thus all hosts
 147 participating in the virtual switch are completely transparent for all
 148 protocols above layer 2. Therefore the common diagnosis tools do not
 149 work as expected. To overcome these problems batctl was created. At
 150 the moment the batctl contains ping, traceroute, tcpdump and
 151 interfaces to the kernel module settings.
 152
 153 For more information, please see the manpage (man batctl).
 154
 155 batctl is available on http://www.open-mesh.net/
 156
 157 CONTACT
 158 -------
 159
 160 Please send us comments, experiences, questions, anything :)
 161
 162 IRC:             #batman on irc.freenode.org
 163 Mailing-list:    b.a.t.m.a.n@open-mesh.net
 164 (subscription at https://list.open-mesh.net/mm/listinfo/b.a.t.m.a.n )
 165
 166 You can also contact the Authors:
 167
 168 Marek Lindner <lindner_marek@yahoo.de>
 169 Simon Wunderlich <siwu@hrz.tu-chemnitz.de>