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