Projecte

General

Perfil

Wiki » Historial » Versió 15

Axel Neumann, 27-08-2012 08:34

1 6 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 3 Axel Neumann
39
In its most simple configuration, the only required parameter are the interfaces names that should be used for meshing.
40
The following example starts bmx6 on interface wlan0:
41
<pre>
42 15 Axel Neumann
root@mlc1001:~# bmx6 dev=eth1
43 3 Axel Neumann
</pre>
44
45
However, to let this simple command work as expected also check the following basic requirements:
46
47 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 @ ).
48 3 Axel Neumann
49 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.
50 3 Axel Neumann
51 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 @)
52 3 Axel Neumann
53 9 Axel Neumann
If everything went fine bmx6 is running now, searching for neighboring bmx6 daemons via the configured link, and coordinates with them to learn about existence-of and routes-to all other bmx6 nodes in the network.
54
 
55 4 Axel Neumann
To access 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.
56 9 Axel Neumann
57 4 Axel Neumann
In the following, a few example will be discussed:
58
<pre>
59 1 Pau Escrich
root@mlc1001:~# bmx6 -c status
60
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes 
61
BMX6-0.1-alpha 16            9           mlc1001.E0F9E33CD42EF2980443 fd66:66:66:0:a2cd:efff:fe10:101 24100101  0:00:56:37 0.3 3
62
</pre>
63
64
So apart from version, compatibility number, and code, the status reveals the daemon's global and local ID, its primary (self-configured) IPv6 address, the time since when it is running (56 minutes), its current cpu consumption (0.3%) and the total number of learned nodes in the network (including itself).
65 5 Axel Neumann
66 9 Axel Neumann
Typical types of accessible information are: status, interfaces, links, originators, descriptions, tunnels
67
These required types can be combined. Also the above given example shows kind of shortcut. The long argument would be
68
@ bmx6 connect show=status @. So a more informative case using the long form would be:
69 1 Pau Escrich
<pre>
70 9 Axel Neumann
root@mlc1001:~# bmx6 connect show=status show=interfaces show=links show=originators show=tunnels
71 1 Pau Escrich
status:
72
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes 
73 15 Axel Neumann
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:101 06100101  0:00:06:52 0.1 3    
74 1 Pau Escrich
interfaces:
75
devName state type     rateMin rateMax llocalIp                    globalIp                           multicastIp primary 
76 15 Axel Neumann
eth1    UP    ethernet 1000M   1000M   fe80::a2cd:efff:fe10:101/64 fd66:66:66:0:a2cd:efff:fe10:101/64 ff02::2     1       
77 1 Pau Escrich
links:
78 15 Axel Neumann
globalId                     llocalIp                 viaDev rxRate txRate bestTxLink routes wantsOgms nbLocalId 
79
mlc1000.0AE58311046412F248CD fe80::a2cd:efff:fe10:1   eth1   100    100    1          1      1         9B100001  
80
mlc1002.91DCF042934B5913BB00 fe80::a2cd:efff:fe10:201 eth1   100    100    1          1      1         BB100201  
81 1 Pau Escrich
originators:
82 15 Axel Neumann
globalId                     blocked primaryIp                       routes viaIp                    viaDev metric lastDesc lastRef 
83
mlc1000.0AE58311046412F248CD 0       fd66:66:66:0:a2cd:efff:fe10:1   1      fe80::a2cd:efff:fe10:1   eth1   999M   407      1      
84
mlc1001.7A7422752001EC4AC4C8 0       fd66:66:66:0:a2cd:efff:fe10:101 0      ::                       ---    128G   410      0      
85
mlc1002.91DCF042934B5913BB00 0       fd66:66:66:0:a2cd:efff:fe10:201 1      fe80::a2cd:efff:fe10:201 eth1   999M   410      1
86 1 Pau Escrich
</pre>
87
88 9 Axel Neumann
Only if relevant information for a requested type is available it will be shown.
89
In this example no tunnels are configured nor offered by other nodes and therefore no tunnel information is shown.
90 1 Pau Escrich
91 9 Axel Neumann
The loop argument can be prepended to the connect argument to continuously show the requested information.
92
Many of the long arguments are usable via a short notation, like l for loop, c for connect, s for show, d for debug.
93
And there is another shortcut summarizing my current favorite information types via debug level 8
94
The following commands do the same as above: @ bmx6 -lc status interfaces links originators tunnels @ or just @ bmx6 -lcd8 @.
95 1 Pau Escrich
96 9 Axel Neumann
Reviewing the provided info:
97 14 Axel Neumann
* interfaces: Followed by one line per configured interface
98
** dev: Interface name
99
** state and type: Whether the interface is UP or DOWN and its assumed link-layer type.
100
** rateMin and rateMax: Min- and maximum transmit rates assumed for this interface.
101
** llocalIp: IPv6 link-local address (used as source address for all outgoing protocol data).
102
** globalIp: Autoconfigured address used for sending network traffic via this interface and which is propagated to other nodes.
103
** multicastIp: Multicast IP (used as destination address for all bmx6 protocol traffic send via this interface).
104
** primary: Indicates whether the global ip of this interface is used as primary ip for this daemon.
105
* links: Followed by one line per detected neighboring bmx6 node.
106
** globalId: GlobalId of that neighbor (see: [[Wiki#Global ID]] ).
107
** llocalIp: Link-local IP of the neighbor's interface building the other side of the link.
108
** viaDev: Interface of this node for the link.
109
** rxRate: Measured receive rate in percent for the link.
110
** txRate: Measured transmit rate in percent for the link.
111
** bestTxLink: Indicates whether this link is the best link to a neighboring nodes.
112
** routes: Indicates for how much routes to other nodes this link is used.
113
** wantsOgms: Indicates whether the neighboring node has requested (this node) to propagate originator messsages (OGMs) via this link.
114
** nbLocalId: Neighbors local ID.
115
* originators: Followed by one line per aware originator in the network (including itself).
116
** globalId: Global Id of that node (see: [[Wiki#Global ID]] ).
117
** blocked: Indicates whether this node is currently blocked (see: [[Wiki#Blocked]] ).
118
** primaryIp: The primary IP of that node. 
119
** routes: Number of potential routes towards this node.
120
** viaIp: Next hops link-local IP of the best route towards this node.
121
** viaDev: Outgoing interface of the best route towards this node.
122
** metric: The end to end path metric to this node
123
** lastDesc: Seconds since the last description update was received (see: [[Widi#Description]] )
124 15 Axel Neumann
** lastRef: Seconds since this node was referenced by any neighboring node (like last sign of life)
125 14 Axel Neumann
126
127 10 Axel Neumann
128
129
130
131
h2. Concepts
132
133
h3. Global ID
134 1 Pau Escrich
135 13 Axel Neumann
h3. Unicast Host Network Announcements (UHNA)
136
137
h3. Tunnel Announcements
138
139
h3. Descriptions
140
141 10 Axel Neumann
h3. Blocked
142
143
Nodes may be blocked by other nodes.
144
145
The decision for blocking another node is done locally based on the detection of duplicate claimed unique resources.
146
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).
147
148
149
150
151
152 1 Pau Escrich
153
154
155
156
157
158 8 Axel Neumann
h2. Bmx6 Plugins
159 1 Pau Escrich
160
161 8 Axel Neumann
h3. Config Plugin
162 1 Pau Escrich
163
164 8 Axel Neumann
h4. Requirements
165 1 Pau Escrich
166 8 Axel Neumann
uci libs are needed for the bmx6-config plugin.
167
To install it do:
168
<pre>
169
wget http://downloads.openwrt.org/sources/uci-0.7.5.tar.gz
170
tar xzvf uci-0.7.5.tar.gz
171
cd uci-0.7.5
172
make
173
sudo make install
174
</pre>
175 1 Pau Escrich
176 8 Axel Neumann
Depending on your system there happens to be an error during compilation.
177
Then edit cli.c and change line 465 to: @ char *argv[MAX_ARGS+2]; @
178
179
h4. Compile and Install
180
181
To compile the bmx6 daemon and bmx6 plugins
182
<pre>
183
make build_all
184
sudo make install_all
185
</pre>
186
187
188
h4. Usage
189
190
191
192
h3. Json Plugin
193
194
195
h4. Requirements
196
197
* json-c for bmx6_json plugin (debian package: libjson0 libjson0-dev)
198
199
200
json-c developer libs are needed!
201
For further reading check: http://json.org/ or https://github.com/jehiah/json-c
202
203
Note for debian sid:
204
The debian package libjson0-dev 0.10-1 seems to miss the file /usr/include/json/json_object_iterator.h
205
Manually copying it from the below mentioned json-c_0.10.orig.tar.gz archive helps.
206
207
208
To install manually (only if NOT installed via debian or other package management system):
209
<pre>
210
wget http://ftp.de.debian.org/debian/pool/main/j/json-c/json-c_0.10.orig.tar.gz
211
tar xzvf json-c_0.10.orig.tar.gz
212
cd json-c..
213
./configure ; make ; make install; ldconfig
214
</pre>
215
216
217
h4. Compile and Install
218
219
To compile the bmx6 daemon and bmx6 plugins
220
<pre>
221
make build_all
222
sudo make install_all
223
</pre>
224
225
226
h4. Usage
227
228
229
230
h3. SMS Plugin
231
232
233
234
h3. Quagga Plugin
235
236
237 3 Axel Neumann
238
239
*Misc*
240
241
242 2 Pau Escrich
[[Tunnel]]