Projecte

General

Perfil

Wiki » Historial » Versió 21

Axel Neumann, 27-08-2012 12:16

1 20 Axel Neumann
{{toc}}
2 1 Pau Escrich
3
4 8 Axel Neumann
h1. BMX6
5 6 Axel Neumann
6
Bmx6 is a routing protocol for Linux based operating systems.
7 1 Pau Escrich
The following intro provides kind of tutorial to get started.
8
9 8 Axel Neumann
h2. Installation
10 6 Axel Neumann
11 8 Axel Neumann
h3. Requirements
12 7 Axel Neumann
13 6 Axel Neumann
The following tools are needed to obtain, compile, and install bmx6
14
* git (debian package: git-core)
15
* gcc
16
* make
17
18
19 8 Axel Neumann
h3. Downloading
20 6 Axel Neumann
21
Latest development sources are available from bmx6 git repository
22
<pre>
23
git clone git://qmp.cat/bmx6.git
24
cd bmx6
25
</pre>
26
27 8 Axel Neumann
h3. Compile and Install
28 6 Axel Neumann
29 7 Axel Neumann
To only compile the main bmx6 daemon (no bmx6 plugins)
30 6 Axel Neumann
<pre>
31
make
32
sudo make install
33
</pre>
34
35
36 8 Axel Neumann
h2. Usage (hello mesh)
37 6 Axel Neumann
38 19 Axel Neumann
h3. Starting
39 3 Axel Neumann
40
In its most simple configuration, the only required parameter are the interfaces names that should be used for meshing.
41
The following example starts bmx6 on interface wlan0:
42
<pre>
43 15 Axel Neumann
root@mlc1001:~# bmx6 dev=eth1
44 3 Axel Neumann
</pre>
45
46
However, to let this simple command work as expected also check the following basic requirements:
47
48 15 Axel Neumann
* bmx6 must be executed in root context (with super user permissions). If you are not already root, prepend all commands with sudo (eg: @ sudo bmx6 dev=eth1 @ ).
49 3 Axel Neumann
50 9 Axel Neumann
* NO IP address needs to be configured. By default bmx6 assumes IPv6 and autoconfigures an ULA based IPv6 address for each interface based on the MAC address of the device. Just, the interfaces must be UP. The linux ip command can do this for you (eg: @ ip link set wlan0 up @). Also, if you are using a wireless interface, the wireless interface settings must be set correctly so that link-layer connectivity is given with bmx6 daemons running on other nodes (computers). The good old iwconfig command may help to achieve that. For example @ iwconfig wlan0 mode ad-hoc ap 02:ca:ff:ee:ba:be channel 11 essid my-mesh-network @ is a typical configuration for a wireless mesh setup.
51 3 Axel Neumann
52 15 Axel Neumann
* Bmx6 (by default) works in daemon mode, thus sends itself to background and gives back a prompt. To let it run in foreground specify a debug level with the startup command like: @ bmx6 debug=0 dev=eth1 @ . Of course you may need to kill a previously started bmx6 daemon beforehand (@ killall bmx6 @)
53 1 Pau Escrich
54 19 Axel Neumann
If everything went fine bmx6 is running now, searching for neighboring bmx6 daemons via the configured interface (link), and coordinates with them to learn about existence-of and routes-to all other bmx6 nodes in the network.
55 1 Pau Escrich
56 19 Axel Neumann
57
58
59
60
h3. Accessing Protocol Events, Status, and Network Information
61
62
To access debug and status information of the bmx6 daemon which has just been started, a second bmx6 process can be launched in client mode (with the --connect or -c parameter) to connect to the main bmx6 daemon and retrieve the desired information.
63
64
In the following, a few example will be discussed
65
66
Continuous debug levels with different verbosity and scope are accessible with the --debug or -d parameter.
67
* Debug level 0 only reports critical events
68
* Debug level 3 reports relevant changes and 
69
* Debug level 4 reports everything.
70
* Debug level 12 dump in and outgoing protocol traffic
71
Eg.: @ bmx6 -cd3 @ connects a bmx6 client process to debug-level 3 of the main daemon and logs the output stdout until terminated with ctrl-c
72
73
74
75
Status, network, and statistic information are accessible with dedicated parameters:
76
* status
77
* interfaces
78
* links
79
* originators
80 21 Axel Neumann
* descriptions, plus optional sub-parameters for filtering
81 19 Axel Neumann
* tunnels
82
* traffic=DEV where DEV:= all or eth1, ....
83
84
85 18 Axel Neumann
<pre>
86 1 Pau Escrich
root@mlc1001:~# bmx6 -c status
87
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes 
88
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:101 24100101  0:00:40:37 0.1 4
89
</pre>
90 18 Axel Neumann
91 5 Axel Neumann
So apart from version, compatibility number, and code, the status reveals the daemon's global (see: [[Wiki#Global-ID]] ) and local ID, its primary (self-configured) IPv6 address, the time since when it is running (40 minutes), its current cpu consumption (0.1%) and the total number of 4 learned nodes in the network (including itself).
92 9 Axel Neumann
93 19 Axel Neumann
These desired types can be combined. Also the above given example shows kind of shortcut. The long argument would be
94
@ bmx6 connect show=status @. A more informative case using the long form would be:
95 1 Pau Escrich
<pre>
96 9 Axel Neumann
root@mlc1001:~# bmx6 connect show=status show=interfaces show=links show=originators show=tunnels
97 1 Pau Escrich
status:
98 18 Axel Neumann
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes
99
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:101 06100101  0:00:53:19 0.3 4
100 15 Axel Neumann
interfaces:
101 18 Axel Neumann
devName state type     rateMin rateMax llocalIp                    globalIp                           multicastIp primary
102
eth1    UP    ethernet 1000M   1000M   fe80::a2cd:efff:fe10:101/64 fd66:66:66:0:a2cd:efff:fe10:101/64 ff02::2     1
103 15 Axel Neumann
links:
104 18 Axel Neumann
globalId                     llocalIp                 viaDev rxRate txRate bestTxLink routes wantsOgms nbLocalId
105
mlc1000.0AE58311046412F248CD fe80::a2cd:efff:fe10:1   eth1   100    100    1          1      1         9B100001
106
mlc1002.91DCF042934B5913BB00 fe80::a2cd:efff:fe10:201 eth1   100    100    1          2      1         BB100201
107 15 Axel Neumann
originators:
108 18 Axel Neumann
globalId                     blocked primaryIp                       routes viaIp                    viaDev metric lastDesc lastRef
109
mlc1000.0AE58311046412F248CD 0       fd66:66:66:0:a2cd:efff:fe10:1   1      fe80::a2cd:efff:fe10:1   eth1   999M   3193     3 
110
mlc1001.7A7422752001EC4AC4C8 0       fd66:66:66:0:a2cd:efff:fe10:101 0      ::                       ---    128G   3197     0
111
mlc1002.91DCF042934B5913BB00 0       fd66:66:66:0:a2cd:efff:fe10:201 1      fe80::a2cd:efff:fe10:201 eth1   999M   3196     3 
112
mlc1003.09E796BC491D386248C3 0       fd66:66:66:0:a2cd:efff:fe10:301 1      fe80::a2cd:efff:fe10:201 eth1   576M   22       3 
113 1 Pau Escrich
</pre>
114
115 9 Axel Neumann
Only if relevant information for a requested type is available it will be shown.
116
In this example no tunnels are configured nor offered by other nodes and therefore no tunnel information is shown.
117 1 Pau Escrich
118 9 Axel Neumann
The loop argument can be prepended to the connect argument to continuously show the requested information.
119
Many of the long arguments are usable via a short notation, like l for loop, c for connect, s for show, d for debug.
120
And there is another shortcut summarizing my current favorite information types via debug level 8
121
The following commands do the same as above: @ bmx6 -lc status interfaces links originators tunnels @ or just @ bmx6 -lcd8 @.
122 1 Pau Escrich
123 18 Axel Neumann
Description of the provided info:
124 14 Axel Neumann
* interfaces: Followed by one line per configured interface
125
** dev: Interface name
126
** state and type: Whether the interface is UP or DOWN and its assumed link-layer type.
127
** rateMin and rateMax: Min- and maximum transmit rates assumed for this interface.
128
** llocalIp: IPv6 link-local address (used as source address for all outgoing protocol data).
129
** globalIp: Autoconfigured address used for sending network traffic via this interface and which is propagated to other nodes.
130
** multicastIp: Multicast IP (used as destination address for all bmx6 protocol traffic send via this interface).
131
** primary: Indicates whether the global ip of this interface is used as primary ip for this daemon.
132
* links: Followed by one line per detected neighboring bmx6 node.
133 16 Axel Neumann
** globalId: GlobalId of that neighbor (see: [[Wiki#Global-ID]] ).
134 14 Axel Neumann
** llocalIp: Link-local IP of the neighbor's interface building the other side of the link.
135
** viaDev: Interface of this node for the link.
136
** rxRate: Measured receive rate in percent for the link.
137
** txRate: Measured transmit rate in percent for the link.
138
** bestTxLink: Indicates whether this link is the best link to a neighboring nodes.
139 1 Pau Escrich
** routes: Indicates for how much routes to other nodes this link is used.
140
** wantsOgms: Indicates whether the neighboring node has requested (this node) to propagate originator messsages (OGMs) via this link.
141
** nbLocalId: Neighbors local ID.
142
* originators: Followed by one line per aware originator in the network (including itself).
143
** globalId: Global Id of that node (see: [[Wiki#Global-ID]] ).
144
** blocked: Indicates whether this node is currently blocked (see: [[Wiki#Blocked]] ).
145
** primaryIp: The primary IP of that node. 
146
** routes: Number of potential routes towards this node.
147
** viaIp: Next hops link-local IP of the best route towards this node.
148
** viaDev: Outgoing interface of the best route towards this node.
149
** metric: The end to end path metric to this node
150
** lastDesc: Seconds since the last description update was received (see: [[Widi#Description]] )
151 18 Axel Neumann
** lastRef: Seconds since this node was referenced by any neighboring node (like last sign of life)
152
153
154
Quick summary of provided info:
155
* Node mlc1001 uses one wired interface (eth1) which is up and actively used for meshing.
156
* Node mlc1001 got aware of 2 neighbors and 4 nodes (originators) including itself.
157
* The link qualities (rx and tx rate) to its neighbors are perfect (100%) and actively used (bestTxLink)
158 1 Pau Escrich
* Routes to nodes mlc1000 and mlc1002 are via interface eth1 and directly to the neighbor's link-local address with a metric of 999M (nearly maximum tx/rx rate of the configured interface)
159
* Route to node mlc1003 is setup via interface eth1 and via the link-local address of neighbor mlc1002 (at least two hops to the destination node).
160
161 21 Axel Neumann
The following links of the total network topology can be guessed from this information (further links may exist):
162 1 Pau Escrich
@ mlc1000 --- mlc1001 --- mlc1002 - - - mlc1003 @
163
164 21 Axel Neumann
165
166
167 19 Axel Neumann
h3. Simple Ping Test
168
169 1 Pau Escrich
This could be verified using traceroute6 towards the primary IP of the other nodes.
170 18 Axel Neumann
171 19 Axel Neumann
To mlc1000's primary IP fd66:66:66:0:a2cd:efff:fe10:1 shows one hop:
172 18 Axel Neumann
<pre>
173
root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:1
174
traceroute to fd66:66:66:0:a2cd:efff:fe10:1 (fd66:66:66:0:a2cd:efff:fe10:1), 30 hops max, 80 byte packets
175 1 Pau Escrich
 1  fd66:66:66:0:a2cd:efff:fe10:1  0.324 ms
176 18 Axel Neumann
</pre>
177
178 19 Axel Neumann
To mlc1002's primary IP fd66:66:66:0:a2cd:efff:fe10:201 shows one hop:
179 18 Axel Neumann
<pre>
180
root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:201
181
traceroute to fd66:66:66:0:a2cd:efff:fe10:201 (fd66:66:66:0:a2cd:efff:fe10:201), 30 hops max, 80 byte packets
182
 1  fd66:66:66:0:a2cd:efff:fe10:201  0.302 ms
183 1 Pau Escrich
</pre>
184
185 19 Axel Neumann
To mlc1003's primary IP fd66:66:66:0:a2cd:efff:fe10:301 shows two hops:
186 1 Pau Escrich
<pre>
187
root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:301
188 18 Axel Neumann
traceroute to fd66:66:66:0:a2cd:efff:fe10:301 (fd66:66:66:0:a2cd:efff:fe10:301), 30 hops max, 80 byte packets
189
 1  fd66:66:66:0:a2cd:efff:fe10:201  0.313 ms
190
 2  fd66:66:66:0:a2cd:efff:fe10:301  0.429 ms
191
</pre>
192 19 Axel Neumann
193 1 Pau Escrich
194
h3. Dynamic Reconfiguration
195
196
Most bmx6 parameters can be applied not only at startup, but also dynamically to an already running main daemon, using the --connect command.
197 21 Axel Neumann
For example interfaces can be added, removed, or specified with more details:
198
The following example removes interface eth1 and adds eth2 with a max rate of 100 Mbits (overwriting the default assumption of 1000Mbits for ethernet interfaces).
199
<pre>
200
bmx6 -c dev=-eth1 dev=eth2 /rateMax=100000
201
bmx6 -cd8
202
</pre>
203 1 Pau Escrich
204 21 Axel Neumann
Checking new status of interfaces, links, and originator:
205
<pre>
206
root@mlc1001:~# bmx6 -cd8
207
status:
208
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes 
209
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:102 06100101  0:02:26:00 0.1 4 
210
interfaces:
211
devName state type     rateMin rateMax llocalIp                    globalIp                           multicastIp primary 
212
eth2    UP    ethernet 100M    100M    fe80::a2cd:efff:fe10:102/64 fd66:66:66:0:a2cd:efff:fe10:102/64 ff02::2     1       
213
links:
214
globalId                     llocalIp               viaDev rxRate txRate bestTxLink routes wantsOgms nbLocalId 
215
mlc1000.0AE58311046412F248CD fe80::a2cd:efff:fe10:2 eth2   89     88     1          3      1         9B100001  
216
originators:
217
globalId                     blocked primaryIp                       routes viaIp                  viaDev metric lastDesc lastRef 
218
mlc1000.0AE58311046412F248CD 0       fd66:66:66:0:a2cd:efff:fe10:1   1      fe80::a2cd:efff:fe10:2 eth2   81757K 18       0      
219
mlc1001.7A7422752001EC4AC4C8 0       fd66:66:66:0:a2cd:efff:fe10:102 0      ::                     ---    128G   80       0      
220
mlc1002.91DCF042934B5913BB00 0       fd66:66:66:0:a2cd:efff:fe10:201 1      fe80::a2cd:efff:fe10:2 eth2   83620K 14       4      
221
mlc1003.09E796BC491D386248C3 0       fd66:66:66:0:a2cd:efff:fe10:301 1      fe80::a2cd:efff:fe10:2 eth2   81488K 9        0
222
</pre>
223 1 Pau Escrich
224 21 Axel Neumann
It can be seen that:
225
* Interface eth1 has been replaced by eth2 with a lower rate.
226
* The primary IP of the node has changed (using the autoconfigured IP from eth2.
227
* The old links (via eth1) are removed and a single new link via eth2 to mlc1000 has been detected
228
* All routes are now going via eth2 and mlc1000's link-local IP fe80::a2cd:efff:fe10:2
229 1 Pau Escrich
230 21 Axel Neumann
231
232
233
234 1 Pau Escrich
h2. Concepts
235 17 Axel Neumann
236
h3. Global ID
237
238
Each bmx6 node creates during its initialization (booting) a global ID for itself. 
239
This ID is created as a concatenation of the node's hostname and a random value.
240
In the above given example with node hostname: "mlc1001" the globalID is: mlc1001.7A7422752001EC4AC4C8
241 1 Pau Escrich
When the bmx6 daemon restarts the hostname will remain. But the rand part will change.
242
As a consequence, the restarted node will appear as a new node to other nodes in the mesh while the old Global ID is still present in their node table.
243
Since both node IDs are announcing the same resources (eg the same primary IP), the ID that appears later will be blocked until the state maintained for the first ID expires.
244
245 21 Axel Neumann
h3. Descriptions
246
247
248
249 13 Axel Neumann
h3. Unicast Host Network Announcements (UHNA)
250
251
h3. Tunnel Announcements
252
253 10 Axel Neumann
h3. Blocked
254
255
Nodes may be blocked by other nodes.
256
257
The decision for blocking another node is done locally based on the detection of duplicate claimed unique resources.
258
This happens if two nodes are declaring themselves as the owner of a unique resource. Then one of those two nodes (usually the latter) is blocked to avoid the propagation of conflicting state. Duplicate address usage is the most common reason for such events which happens if two nodes are using (and announcing) the same primary IPs. Another typical reason for such events is the rebooting of a node. Once the bmx6 daemon restarts it appears as a new node to the network but announcing the same address as the previous process. Since the resources allocated by the previous resources are still in the database of other nodes in the mesh they will block the new process until this information expires (by default after 100 seconds).
259
260
261
262
263
264 1 Pau Escrich
265
266
267
268
269
270 8 Axel Neumann
h2. Bmx6 Plugins
271 1 Pau Escrich
272
273 8 Axel Neumann
h3. Config Plugin
274 1 Pau Escrich
275
276 8 Axel Neumann
h4. Requirements
277 1 Pau Escrich
278 8 Axel Neumann
uci libs are needed for the bmx6-config plugin.
279
To install it do:
280
<pre>
281
wget http://downloads.openwrt.org/sources/uci-0.7.5.tar.gz
282
tar xzvf uci-0.7.5.tar.gz
283
cd uci-0.7.5
284
make
285
sudo make install
286
</pre>
287 1 Pau Escrich
288 8 Axel Neumann
Depending on your system there happens to be an error during compilation.
289
Then edit cli.c and change line 465 to: @ char *argv[MAX_ARGS+2]; @
290
291
h4. Compile and Install
292
293
To compile the bmx6 daemon and bmx6 plugins
294
<pre>
295
make build_all
296
sudo make install_all
297
</pre>
298
299
300
h4. Usage
301
302
303
304
h3. Json Plugin
305
306
307
h4. Requirements
308
309
* json-c for bmx6_json plugin (debian package: libjson0 libjson0-dev)
310
311
312
json-c developer libs are needed!
313
For further reading check: http://json.org/ or https://github.com/jehiah/json-c
314
315
Note for debian sid:
316
The debian package libjson0-dev 0.10-1 seems to miss the file /usr/include/json/json_object_iterator.h
317
Manually copying it from the below mentioned json-c_0.10.orig.tar.gz archive helps.
318
319
320
To install manually (only if NOT installed via debian or other package management system):
321
<pre>
322
wget http://ftp.de.debian.org/debian/pool/main/j/json-c/json-c_0.10.orig.tar.gz
323
tar xzvf json-c_0.10.orig.tar.gz
324
cd json-c..
325
./configure ; make ; make install; ldconfig
326
</pre>
327
328
329
h4. Compile and Install
330
331
To compile the bmx6 daemon and bmx6 plugins
332
<pre>
333
make build_all
334
sudo make install_all
335
</pre>
336
337
338
h4. Usage
339
340
341
342
h3. SMS Plugin
343
344
345
346
h3. Quagga Plugin
347
348
349 3 Axel Neumann
350
351
*Misc*
352
353
354 2 Pau Escrich
[[Tunnel]]