Commit | Line | Data |
---|---|---|
5f30a4ab | 1 | [state: 21-08-2011] |
c6c8fea2 SE |
2 | |
3 | BATMAN-ADV | |
4 | ---------- | |
5 | ||
6 | Batman advanced is a new approach to wireless networking which | |
7 | does no longer operate on the IP basis. Unlike the batman daemon, | |
8 | which exchanges information using UDP packets and sets routing | |
9 | tables, batman-advanced operates on ISO/OSI Layer 2 only and uses | |
10 | and routes (or better: bridges) Ethernet Frames. It emulates a | |
11 | virtual network switch of all nodes participating. Therefore all | |
12 | nodes appear to be link local, thus all higher operating proto- | |
13 | cols won't be affected by any changes within the network. You can | |
14 | run almost any protocol above batman advanced, prominent examples | |
15 | are: IPv4, IPv6, DHCP, IPX. | |
16 | ||
17 | Batman advanced was implemented as a Linux kernel driver to re- | |
18 | duce the overhead to a minimum. It does not depend on any (other) | |
19 | network driver, and can be used on wifi as well as ethernet lan, | |
20 | vpn, etc ... (anything with ethernet-style layer 2). | |
21 | ||
2dafb49d | 22 | |
c6c8fea2 SE |
23 | CONFIGURATION |
24 | ------------- | |
25 | ||
26 | Load the batman-adv module into your kernel: | |
27 | ||
28 | # insmod batman-adv.ko | |
29 | ||
30 | The module is now waiting for activation. You must add some in- | |
31 | terfaces on which batman can operate. After loading the module | |
32 | batman advanced will scan your systems interfaces to search for | |
33 | compatible interfaces. Once found, it will create subfolders in | |
34 | the /sys directories of each supported interface, e.g. | |
35 | ||
36 | # ls /sys/class/net/eth0/batman_adv/ | |
37 | # iface_status mesh_iface | |
38 | ||
39 | If an interface does not have the "batman_adv" subfolder it prob- | |
40 | ably is not supported. Not supported interfaces are: loopback, | |
41 | non-ethernet and batman's own interfaces. | |
42 | ||
43 | Note: After the module was loaded it will continuously watch for | |
44 | new interfaces to verify the compatibility. There is no need to | |
45 | reload the module if you plug your USB wifi adapter into your ma- | |
46 | chine after batman advanced was initially loaded. | |
47 | ||
48 | To activate a given interface simply write "bat0" into its | |
49 | "mesh_iface" file inside the batman_adv subfolder: | |
50 | ||
51 | # echo bat0 > /sys/class/net/eth0/batman_adv/mesh_iface | |
52 | ||
53 | Repeat this step for all interfaces you wish to add. Now batman | |
54 | starts 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 write "none" into its | |
62 | "mesh_iface" file: | |
63 | ||
64 | # echo none > /sys/class/net/eth0/batman_adv/mesh_iface | |
65 | ||
66 | ||
67 | All mesh wide settings can be found in batman's own interface | |
68 | folder: | |
69 | ||
70 | # ls /sys/class/net/bat0/mesh/ | |
5f30a4ab SW |
71 | # aggregated_ogms fragmentation gw_sel_class vis_mode |
72 | # ap_isolation gw_bandwidth hop_penalty | |
73 | # bonding gw_mode orig_interval | |
c6c8fea2 SE |
74 | |
75 | ||
f65e51d7 | 76 | There is a special folder for debugging information: |
c6c8fea2 SE |
77 | |
78 | # ls /sys/kernel/debug/batman_adv/bat0/ | |
091b9483 SE |
79 | # gateways socket transtable_global vis_data |
80 | # originators softif_neigh transtable_local | |
c6c8fea2 SE |
81 | |
82 | ||
83 | Some of the files contain all sort of status information regard- | |
84 | ing the mesh network. For example, you can view the table of | |
85 | originators (mesh 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 | |
90 | requirements. For instance, you can check the current originator | |
91 | interval (value in milliseconds which determines how often batman | |
92 | sends its broadcast packets): | |
93 | ||
94 | # cat /sys/class/net/bat0/mesh/orig_interval | |
95 | # 1000 | |
96 | ||
97 | and also change its value: | |
98 | ||
99 | # echo 3000 > /sys/class/net/bat0/mesh/orig_interval | |
100 | ||
101 | In very mobile scenarios, you might want to adjust the originator | |
102 | interval to a lower value. This will make the mesh more respon- | |
103 | sive to topology changes, but will also increase the overhead. | |
104 | ||
105 | ||
106 | USAGE | |
107 | ----- | |
108 | ||
109 | To make use of your newly created mesh, batman advanced provides | |
110 | a new interface "bat0" which you should use from this point on. | |
111 | All interfaces added to batman advanced are not relevant any | |
112 | longer because batman handles them for you. Basically, one "hands | |
113 | over" the data by using the batman interface and batman will make | |
114 | sure it reaches its destination. | |
115 | ||
116 | The "bat0" interface can be used like any other regular inter- | |
117 | face. It needs an IP address which can be either statically con- | |
118 | figured or dynamically (by using DHCP or similar services): | |
119 | ||
120 | # NodeA: ifconfig bat0 192.168.0.1 | |
121 | # NodeB: ifconfig bat0 192.168.0.2 | |
122 | # NodeB: ping 192.168.0.1 | |
123 | ||
124 | Note: In order to avoid problems remove all IP addresses previ- | |
125 | ously assigned to interfaces now used by batman advanced, e.g. | |
126 | ||
127 | # ifconfig eth0 0.0.0.0 | |
128 | ||
129 | ||
130 | VISUALIZATION | |
131 | ------------- | |
132 | ||
133 | If you want topology visualization, at least one mesh node must | |
134 | be configured as VIS-server: | |
135 | ||
136 | # echo "server" > /sys/class/net/bat0/mesh/vis_mode | |
137 | ||
138 | Each node is either configured as "server" or as "client" (de- | |
139 | fault: "client"). Clients send their topology data to the server | |
140 | next to them, and server synchronize with other servers. If there | |
141 | is no server configured (default) within the mesh, no topology | |
142 | information will be transmitted. With these "synchronizing | |
143 | servers", there can be 1 or more vis servers sharing the same (or | |
144 | at least very similar) data. | |
145 | ||
146 | When configured as server, you can get a topology snapshot of | |
147 | your mesh: | |
148 | ||
149 | # cat /sys/kernel/debug/batman_adv/bat0/vis_data | |
150 | ||
151 | This raw output is intended to be easily parsable and convertable | |
152 | with other tools. Have a look at the batctl README if you want a | |
153 | vis output in dot or json format for instance and how those out- | |
154 | puts could then be visualised in an image. | |
155 | ||
156 | The raw format consists of comma separated values per entry where | |
157 | each entry is giving information about a certain source inter- | |
158 | face. Each entry can/has to have the following values: | |
159 | -> "mac" - mac address of an originator's source interface | |
160 | (each line begins with it) | |
161 | -> "TQ mac value" - src mac's link quality towards mac address | |
162 | of a neighbor originator's interface which | |
163 | is being used for routing | |
2dafb49d | 164 | -> "TT mac" - TT announced by source mac |
c6c8fea2 SE |
165 | -> "PRIMARY" - this is a primary interface |
166 | -> "SEC mac" - secondary mac address of source | |
167 | (requires preceding PRIMARY) | |
168 | ||
169 | The TQ value has a range from 4 to 255 with 255 being the best. | |
2dafb49d | 170 | The TT entries are showing which hosts are connected to the mesh |
c6c8fea2 SE |
171 | via bat0 or being bridged into the mesh network. The PRIMARY/SEC |
172 | values are only applied on primary interfaces | |
173 | ||
174 | ||
175 | LOGGING/DEBUGGING | |
176 | ----------------- | |
177 | ||
178 | All error messages, warnings and information messages are sent to | |
179 | the kernel log. Depending on your operating system distribution | |
180 | this can be read in one of a number of ways. Try using the com- | |
181 | mands: dmesg, logread, or looking in the files /var/log/kern.log | |
182 | or /var/log/syslog. All batman-adv messages are prefixed with | |
183 | "batman-adv:" So to see just these messages try | |
184 | ||
185 | # dmesg | grep batman-adv | |
186 | ||
187 | When investigating problems with your mesh network it is some- | |
188 | times necessary to see more detail debug messages. This must be | |
189 | enabled when compiling the batman-adv module. When building bat- | |
190 | man-adv as part of kernel, use "make menuconfig" and enable the | |
191 | option "B.A.T.M.A.N. debugging". | |
192 | ||
193 | Those additional debug messages can be accessed using a special | |
194 | file in debugfs | |
195 | ||
196 | # cat /sys/kernel/debug/batman_adv/bat0/log | |
197 | ||
198 | The additional debug output is by default disabled. It can be en- | |
199 | abled during run time. Following log_levels are defined: | |
200 | ||
201 | 0 - All debug output disabled | |
202 | 1 - Enable messages related to routing / flooding / broadcasting | |
2dafb49d | 203 | 2 - Enable route or tt entry added / changed / deleted |
c6c8fea2 SE |
204 | 3 - Enable all messages |
205 | ||
206 | The debug output can be changed at runtime using the file | |
207 | /sys/class/net/bat0/mesh/log_level. e.g. | |
208 | ||
209 | # echo 2 > /sys/class/net/bat0/mesh/log_level | |
210 | ||
2dafb49d | 211 | will enable debug messages for when routes or TTs change. |
c6c8fea2 SE |
212 | |
213 | ||
214 | BATCTL | |
215 | ------ | |
216 | ||
217 | As batman advanced operates on layer 2 all hosts participating in | |
218 | the virtual switch are completely transparent for all protocols | |
219 | above layer 2. Therefore the common diagnosis tools do not work | |
220 | as expected. To overcome these problems batctl was created. At | |
221 | the moment the batctl contains ping, traceroute, tcpdump and | |
222 | interfaces to the kernel module settings. | |
223 | ||
224 | For more information, please see the manpage (man batctl). | |
225 | ||
226 | batctl is available on http://www.open-mesh.org/ | |
227 | ||
228 | ||
229 | CONTACT | |
230 | ------- | |
231 | ||
232 | Please send us comments, experiences, questions, anything :) | |
233 | ||
234 | IRC: #batman on irc.freenode.org | |
091b9483 SE |
235 | Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription |
236 | at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n) | |
c6c8fea2 SE |
237 | |
238 | You can also contact the Authors: | |
239 | ||
240 | Marek Lindner <lindner_marek@yahoo.de> | |
241 | Simon Wunderlich <siwu@hrz.tu-chemnitz.de> |