Projecte

General

Perfil

Wiki » Historial » Versió 52

Axel Neumann, 06-12-2012 07:01

1 52 Axel Neumann
{{>toc}}
2 1 Pau Escrich
3 51 Axel Neumann
!bmx6.png!
4 1 Pau Escrich
5 6 Axel Neumann
Bmx6 is a routing protocol for Linux based operating systems.
6
The following intro provides kind of tutorial to get started.
7 52 Axel Neumann
8 1 Pau Escrich
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 50 Pau Escrich
72
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
73 19 Axel Neumann
74
75
76
Status, network, and statistic information are accessible with dedicated parameters:
77
* status
78
* interfaces
79
* links
80
* originators
81 21 Axel Neumann
* descriptions, plus optional sub-parameters for filtering
82 19 Axel Neumann
* tunnels
83
* traffic=DEV where DEV:= all or eth1, ....
84
85
86 18 Axel Neumann
<pre>
87 1 Pau Escrich
root@mlc1001:~# bmx6 -c status
88
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes 
89
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:101 24100101  0:00:40:37 0.1 4
90
</pre>
91 18 Axel Neumann
92 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).
93 9 Axel Neumann
94 19 Axel Neumann
These desired types can be combined. Also the above given example shows kind of shortcut. The long argument would be
95
@ bmx6 connect show=status @. A more informative case using the long form would be:
96 1 Pau Escrich
<pre>
97 9 Axel Neumann
root@mlc1001:~# bmx6 connect show=status show=interfaces show=links show=originators show=tunnels
98 1 Pau Escrich
status:
99 18 Axel Neumann
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes
100
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:101 06100101  0:00:53:19 0.3 4
101 15 Axel Neumann
interfaces:
102 18 Axel Neumann
devName state type     rateMin rateMax llocalIp                    globalIp                           multicastIp primary
103
eth1    UP    ethernet 1000M   1000M   fe80::a2cd:efff:fe10:101/64 fd66:66:66:0:a2cd:efff:fe10:101/64 ff02::2     1
104 15 Axel Neumann
links:
105 18 Axel Neumann
globalId                     llocalIp                 viaDev rxRate txRate bestTxLink routes wantsOgms nbLocalId
106
mlc1000.0AE58311046412F248CD fe80::a2cd:efff:fe10:1   eth1   100    100    1          1      1         9B100001
107
mlc1002.91DCF042934B5913BB00 fe80::a2cd:efff:fe10:201 eth1   100    100    1          2      1         BB100201
108 15 Axel Neumann
originators:
109 18 Axel Neumann
globalId                     blocked primaryIp                       routes viaIp                    viaDev metric lastDesc lastRef
110
mlc1000.0AE58311046412F248CD 0       fd66:66:66:0:a2cd:efff:fe10:1   1      fe80::a2cd:efff:fe10:1   eth1   999M   3193     3 
111
mlc1001.7A7422752001EC4AC4C8 0       fd66:66:66:0:a2cd:efff:fe10:101 0      ::                       ---    128G   3197     0
112
mlc1002.91DCF042934B5913BB00 0       fd66:66:66:0:a2cd:efff:fe10:201 1      fe80::a2cd:efff:fe10:201 eth1   999M   3196     3 
113
mlc1003.09E796BC491D386248C3 0       fd66:66:66:0:a2cd:efff:fe10:301 1      fe80::a2cd:efff:fe10:201 eth1   576M   22       3 
114 1 Pau Escrich
</pre>
115
116 9 Axel Neumann
Only if relevant information for a requested type is available it will be shown.
117
In this example no tunnels are configured nor offered by other nodes and therefore no tunnel information is shown.
118 1 Pau Escrich
119 9 Axel Neumann
The loop argument can be prepended to the connect argument to continuously show the requested information.
120
Many of the long arguments are usable via a short notation, like l for loop, c for connect, s for show, d for debug.
121
And there is another shortcut summarizing my current favorite information types via debug level 8
122
The following commands do the same as above: @ bmx6 -lc status interfaces links originators tunnels @ or just @ bmx6 -lcd8 @.
123 1 Pau Escrich
124 18 Axel Neumann
Description of the provided info:
125 14 Axel Neumann
* interfaces: Followed by one line per configured interface
126
** dev: Interface name
127
** state and type: Whether the interface is UP or DOWN and its assumed link-layer type.
128
** rateMin and rateMax: Min- and maximum transmit rates assumed for this interface.
129
** llocalIp: IPv6 link-local address (used as source address for all outgoing protocol data).
130
** globalIp: Autoconfigured address used for sending network traffic via this interface and which is propagated to other nodes.
131
** multicastIp: Multicast IP (used as destination address for all bmx6 protocol traffic send via this interface).
132
** primary: Indicates whether the global ip of this interface is used as primary ip for this daemon.
133
* links: Followed by one line per detected neighboring bmx6 node.
134 16 Axel Neumann
** globalId: GlobalId of that neighbor (see: [[Wiki#Global-ID]] ).
135 14 Axel Neumann
** llocalIp: Link-local IP of the neighbor's interface building the other side of the link.
136
** viaDev: Interface of this node for the link.
137
** rxRate: Measured receive rate in percent for the link.
138
** txRate: Measured transmit rate in percent for the link.
139
** bestTxLink: Indicates whether this link is the best link to a neighboring nodes.
140 1 Pau Escrich
** routes: Indicates for how much routes to other nodes this link is used.
141
** wantsOgms: Indicates whether the neighboring node has requested (this node) to propagate originator messsages (OGMs) via this link.
142
** nbLocalId: Neighbors local ID.
143
* originators: Followed by one line per aware originator in the network (including itself).
144
** globalId: Global Id of that node (see: [[Wiki#Global-ID]] ).
145 30 Axel Neumann
** blocked: Indicates whether this node is currently blocked (see: [[Wiki#Blocked-Nodes]] ).
146 1 Pau Escrich
** primaryIp: The primary IP of that node. 
147
** routes: Number of potential routes towards this node.
148
** viaIp: Next hops link-local IP of the best route towards this node.
149
** viaDev: Outgoing interface of the best route towards this node.
150
** metric: The end to end path metric to this node
151
** lastDesc: Seconds since the last description update was received (see: [[Widi#Description]] )
152 18 Axel Neumann
** lastRef: Seconds since this node was referenced by any neighboring node (like last sign of life)
153
154
155
Quick summary of provided info:
156
* Node mlc1001 uses one wired interface (eth1) which is up and actively used for meshing.
157
* Node mlc1001 got aware of 2 neighbors and 4 nodes (originators) including itself.
158
* The link qualities (rx and tx rate) to its neighbors are perfect (100%) and actively used (bestTxLink)
159 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)
160
* 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).
161
162 21 Axel Neumann
The following links of the total network topology can be guessed from this information (further links may exist):
163 1 Pau Escrich
@ mlc1000 --- mlc1001 --- mlc1002 - - - mlc1003 @
164
165 21 Axel Neumann
166
167
168 19 Axel Neumann
h3. Simple Ping Test
169
170 1 Pau Escrich
This could be verified using traceroute6 towards the primary IP of the other nodes.
171 18 Axel Neumann
172 19 Axel Neumann
To mlc1000's primary IP fd66:66:66:0:a2cd:efff:fe10:1 shows one hop:
173 18 Axel Neumann
<pre>
174
root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:1
175
traceroute to fd66:66:66:0:a2cd:efff:fe10:1 (fd66:66:66:0:a2cd:efff:fe10:1), 30 hops max, 80 byte packets
176 1 Pau Escrich
 1  fd66:66:66:0:a2cd:efff:fe10:1  0.324 ms
177 18 Axel Neumann
</pre>
178
179 19 Axel Neumann
To mlc1002's primary IP fd66:66:66:0:a2cd:efff:fe10:201 shows one hop:
180 18 Axel Neumann
<pre>
181
root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:201
182
traceroute to fd66:66:66:0:a2cd:efff:fe10:201 (fd66:66:66:0:a2cd:efff:fe10:201), 30 hops max, 80 byte packets
183
 1  fd66:66:66:0:a2cd:efff:fe10:201  0.302 ms
184 1 Pau Escrich
</pre>
185
186 19 Axel Neumann
To mlc1003's primary IP fd66:66:66:0:a2cd:efff:fe10:301 shows two hops:
187 1 Pau Escrich
<pre>
188
root@mlc1001:~# traceroute6 -n -q 1 fd66:66:66:0:a2cd:efff:fe10:301
189 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
190
 1  fd66:66:66:0:a2cd:efff:fe10:201  0.313 ms
191
 2  fd66:66:66:0:a2cd:efff:fe10:301  0.429 ms
192
</pre>
193 19 Axel Neumann
194 1 Pau Escrich
195
h3. Dynamic Reconfiguration
196
197
Most bmx6 parameters can be applied not only at startup, but also dynamically to an already running main daemon, using the --connect command.
198 21 Axel Neumann
For example interfaces can be added, removed, or specified with more details:
199
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).
200
<pre>
201
bmx6 -c dev=-eth1 dev=eth2 /rateMax=100000
202
bmx6 -cd8
203
</pre>
204 1 Pau Escrich
205 21 Axel Neumann
Checking new status of interfaces, links, and originator:
206
<pre>
207
root@mlc1001:~# bmx6 -cd8
208
status:
209
version        compatibility codeVersion globalId                     primaryIp                       myLocalId uptime     cpu nodes 
210
BMX6-0.1-alpha 16            9           mlc1001.7A7422752001EC4AC4C8 fd66:66:66:0:a2cd:efff:fe10:102 06100101  0:02:26:00 0.1 4 
211
interfaces:
212
devName state type     rateMin rateMax llocalIp                    globalIp                           multicastIp primary 
213
eth2    UP    ethernet 100M    100M    fe80::a2cd:efff:fe10:102/64 fd66:66:66:0:a2cd:efff:fe10:102/64 ff02::2     1       
214
links:
215
globalId                     llocalIp               viaDev rxRate txRate bestTxLink routes wantsOgms nbLocalId 
216
mlc1000.0AE58311046412F248CD fe80::a2cd:efff:fe10:2 eth2   89     88     1          3      1         9B100001  
217
originators:
218
globalId                     blocked primaryIp                       routes viaIp                  viaDev metric lastDesc lastRef 
219
mlc1000.0AE58311046412F248CD 0       fd66:66:66:0:a2cd:efff:fe10:1   1      fe80::a2cd:efff:fe10:2 eth2   81757K 18       0      
220
mlc1001.7A7422752001EC4AC4C8 0       fd66:66:66:0:a2cd:efff:fe10:102 0      ::                     ---    128G   80       0      
221
mlc1002.91DCF042934B5913BB00 0       fd66:66:66:0:a2cd:efff:fe10:201 1      fe80::a2cd:efff:fe10:2 eth2   83620K 14       4      
222
mlc1003.09E796BC491D386248C3 0       fd66:66:66:0:a2cd:efff:fe10:301 1      fe80::a2cd:efff:fe10:2 eth2   81488K 9        0
223
</pre>
224 1 Pau Escrich
225 21 Axel Neumann
It can be seen that:
226
* Interface eth1 has been replaced by eth2 with a lower rate.
227
* The primary IP of the node has changed (using the autoconfigured IP from eth2.
228
* The old links (via eth1) are removed and a single new link via eth2 to mlc1000 has been detected
229
* All routes are now going via eth2 and mlc1000's link-local IP fe80::a2cd:efff:fe10:2
230 1 Pau Escrich
231 21 Axel Neumann
232
233
234
235 1 Pau Escrich
h2. Concepts
236 17 Axel Neumann
237
h3. Global ID
238
239
Each bmx6 node creates during its initialization (booting) a global ID for itself. 
240
This ID is created as a concatenation of the node's hostname and a random value.
241
In the above given example with node hostname: "mlc1001" the globalID is: mlc1001.7A7422752001EC4AC4C8
242 1 Pau Escrich
When the bmx6 daemon restarts the hostname will remain. But the rand part will change.
243
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.
244
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.
245
246 26 Axel Neumann
247
248 21 Axel Neumann
h3. Descriptions
249
250 22 Axel Neumann
Instead of propagating individual routing updates for each announced network and interface address, each bmx6 daemon summarizes this and other node specific attributes into a single node-specific description. A specific description is propagated only once to all other nodes. Subsequent routing updates are referencing to the corresponding description with it's hash.
251 23 Axel Neumann
If a node is reconfigured, for example because its interfaces change or a new network shall be announced, than also the node's description changes.
252
Other nodes are becoming aware of the changed attributes of a reconfigured node by receiving a corresponding description update.
253
Subsequent references to this node will use the hash of the new description.
254
255
Because the description is designed very generic it can be easily used to piggyback other non-routing specific data. For example the bmx6-sms plugin is taking advantage of this option by adding arbitrary short messages data to the node's description.
256
257 25 Axel Neumann
Currently there is a limit for the total size of a description of 1400 bytes. While this is more than sufficient for quite a number of interfaces and announced networks per node, it is critical few when considering a gateway node with BGP route exchange that is announcing 100eds of networks.
258 23 Axel Neumann
259 30 Axel Neumann
h3. Blocked Nodes
260 26 Axel Neumann
261 29 Axel Neumann
Nodes may be blocked by other nodes.
262
When a node is blocked no routing updates (OGMs) of the blocked node are propagated by the blocking node.
263
The decision for blocking another node is done locally based on the detection of more than one node announcing the same unique resource.
264
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 scenario leading to such events is the rebooting of a node. Once a bmx6 daemon restarts it appears as a new node (with a new global ID) 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).
265 26 Axel Neumann
266 1 Pau Escrich
267 29 Axel Neumann
268
269
h2. Unicast Host Network Announcements (UHNA)
270
271 26 Axel Neumann
A Host Network Announcements (HNA) describes the advertisement of IP addresses and networks by a node to other nodes in the mesh.
272 29 Axel Neumann
Typically (but not with BMX6), several nodes can announce the same or overlapping HNAs at the same time.
273
Announced networks do overlap if they are equal or one being a subset of another (eg. 10.1.1.0/24 is a subset and overlapped by 10.1.0.0/16).
274 26 Axel Neumann
Packets with a destination address matching an announced networks will be routed toward any node that originated a corresponding HNA.
275
Therefore these HNA types may also be called anycast HNA.
276
277 30 Axel Neumann
In bmx6, HNAs have an unicast nature (UHNAs) because each network can only be announced once and announced networks MUST NOT overlap (See also [[Wiki#Blocked-Nodes]]).
278 26 Axel Neumann
This way it can be ensured that the destination of an UHNA routed packet is exactly known.
279
280
In a sense the origination and propagation (by intermediate nodes) of UHNA announcements can be thought of a promise that guarantees:
281
1. All packets with a destination address matching an announced UHNA network will be routed exactly to the node (with the global ID) that originated the UHNA and
282
2. each node on the forwarding path towards the originator of the UHNA is supporting this promise.
283
284
By default, Bmx6 only announces primary and non-primary interface addresses via UHNAs.
285 1 Pau Escrich
The auto address configuration ensures that interface addresses are unique.
286 26 Axel Neumann
287 1 Pau Escrich
Using UHNAs for the announcements of networks requires a strict coordination to ensure that no network is announced twice.
288
289
Technically, multiple UHNAs, each wrapped into a single message, are aggregated into a UHNA frame and attached to the description of a node.
290
291 32 Axel Neumann
If Bmx6 is configured in IPv6 mode only IPv6 UHNAs can be announced and in IPv4 mode only IPv4 UHNAs
292
293
294 31 Axel Neumann
h3. UHNA Configuration
295 30 Axel Neumann
296
The announcement of UHNAs can be configured with the --unicastHna or -u parameter followed by a network specification in ip/prefixlen notation.
297
By default all interface addresses are announced via UHNAs. However, this can be disabled by setting the --dev subparameter /announce or /a to 0.
298
299
The following example reconfigures an already running bmx6 daemon (in IPv6 mode) to UHNA announce the network fd00:ffff:ffff:ffff::/64 and fd01:ffff:ffff::/48.
300
By omitting the --connect / -c parameter, the same could be configured as startup parameter for bmx6.
301
<pre>
302
bmx6 -c u=fd00:ffff:ffff:ffff::/64 u=fd01:ffff:ffff::/48
303
</pre>
304
305
An already active announcement can be removed by preceeding the network with the '-' char:
306
<pre>
307
bmx6 -c u=-fd00:ffff:ffff:ffff::/64
308
</pre>
309
310
Before bmx6 accepts a dynamically configured UHNA announcement it checks if this UHNA is not overlapping with an already existing UHNA announcement form another node.
311
If this is the case the configuration will fail.
312
To check if a chain of dynamic commands would be accepted by a bmx6 daemon without actually applying it, the --test command may follow the --connect /-c command.
313
314
315 26 Axel Neumann
316 29 Axel Neumann
h2. Tunnel Announcements
317 26 Axel Neumann
318 27 Axel Neumann
319
Tunnel announcements offer an alternative mechanism to propagate routes. 
320 32 Axel Neumann
Tunnel announcements are currently only implemented for Bmx6-IPv6 mode. However, in IPv6 mode IPv6 and IPv4 networks can be announced.
321 1 Pau Escrich
In contrast to UHNAs, using tunnel announcements, the same or overlapping networks can be announced from different nodes.
322 27 Axel Neumann
Tunnel announcements are an offer from the originating node to other nodes. Other nodes can take the offer or not.
323 29 Axel Neumann
For example several nodes in a network may offer to share their DSL connection by doing a default-route (0.0.0.0/0 or ::/0) tunnel announcement.
324 1 Pau Escrich
Other nodes looking for a route to the internet (a default route) can choose between the multiple offers by establishing a tunnel to one specific of the offering nodes.
325
Therefore an unidirectional (onw-way) tunnel is established from the searching to the offering node.
326 46 Axel Neumann
At the searching node, the remote (outer) tunnel address is configured with an UHNA address (usually the primary address) of the offering node.
327
The networks advertised with the tunnel announcements are configured at the client side as routes via (into) the unidirectional tunnel.
328 1 Pau Escrich
329
This way, each node can make an individual choice between networks offered via tunnel announcements.
330
The automatic selection can be specified via a policy description that considers parameters such as advertised bandwidth, path metric, trust in specific GW nodes, hysteresis, ... .
331 29 Axel Neumann
Since an UHNA address is used as the outer (remote) tunnel address, the client end of the tunnel can be sure that all packets routed into the tunnel will indeed end up at the intended GW node (see [[Wiki#Unicast-Host-Network-Announcements-UHNA]]).
332 1 Pau Escrich
333 26 Axel Neumann
Using tunnel announcements for offering GW services to networks requires NO coordination with other nodes since its up to the client node to select an appropriate GW.
334 29 Axel Neumann
335 1 Pau Escrich
Technically, multiple tunnel announcements, each wrapped into a single tun6in6-net message, are aggregated into a tun4in6 or tun6in6-net frame and attached to the description of a node.
336
337 32 Axel Neumann
Tunnel announcements are also used for redistributing routes from other routing protocols (see [[Wiki#Quagga-Plugin]]) into a bmx6 zone. 
338 1 Pau Escrich
Therefore, each announcements message is decorated with a route-type field indicating the routing protocol that exported the route for being redistributed.
339 31 Axel Neumann
340
341 33 Axel Neumann
h3. Tunnel Configuration and Debugging
342 31 Axel Neumann
343 34 Axel Neumann
In general, a specific tunnel configuration is described from two perspectives:
344 32 Axel Neumann
* Gateway (GW) nodes or just GWs are offering GW services to networks via the advertizement of tunnel announcements and the provisioning of tunnel-end-points.
345 31 Axel Neumann
* GW-client nodes (or just GW-clients) that are searching for GWs with tunnel endpoints and routing services to networks.
346 1 Pau Escrich
347 34 Axel Neumann
A node can (and usually is) operating in both modes (as GW and as GW-client). 
348
But regarding a specific network each node is operating either in GW or in GW-client mode!
349 1 Pau Escrich
350 34 Axel Neumann
351 1 Pau Escrich
h4. Gateway Nodes
352
353 33 Axel Neumann
Similar to the configuration of UHNAs the advertisement of a tunnel endpoint to a network can be configured with the --tunInNet parameter + network argument and a bandwidth specification (given as bits per second) using the /bandwidth or /b sub parameter.
354 32 Axel Neumann
Announcement can be removed by preceeding the network argument with a '-' char. 
355
The configuration can be done during daemon startup or dynamically (using --connect / -c parameter). 
356 1 Pau Escrich
357 32 Axel Neumann
The following command dynamically configures the advertisement of the following routes:
358 33 Axel Neumann
* An IPv4 default route 0.0.0.0/0 with a bandwidth of 32 Mbps.
359
* A more specific route to 10.10.0.0/16 with a bandwidth of 10 Mbps.
360
* An IPv6 route to the [RFC 4291] designated 2000::/3 global unicast address space with a bandwidth of 16 Mbps.
361
* A more specific route to the 2012:1234::/32 IPv6 space at 10 Mbps.
362 32 Axel Neumann
363 1 Pau Escrich
<pre>
364 33 Axel Neumann
bmx6 -c tunInNet=0.0.0.0/0 /b=32000000  tunInNet=10.10.0.0/16 /b=10000000  tunInNet=2000::/3 /b=16000000  tunInNet=2012:1234::/32 /b=10000000
365 1 Pau Escrich
</pre>
366
367 34 Axel Neumann
One aspect that must be considered when configuring GW nodes is that tunnels are unidirectional from the GW client to the GW.
368
But clients usually also need a route back from the GW to the client to allow a bidirectional communication.
369 1 Pau Escrich
370 34 Axel Neumann
One (however not recommended) option would be that GW clients are using their primary address as source address for all packets routed into the GW tunnel because a route from the GW to the GW-client via the client's primary address already exist. However, by default, the client's primary address is an autoconfigured ULA address which is not routable outside the bmx6 network. Also the primary address is either an IPv4 or an IPv6 address and can only be used to route to a corresponding destination network.
371 1 Pau Escrich
372 34 Axel Neumann
The recommended procedure to let clients use addresses that are routable outside of the bmx6 cloud is that also GW client nodes advertize a host-address via UHNA or tunnel announcements. In the latter (recommended) case, the client node also appears as a GW node to its private address space used for communication with other remote networks. To support this recommended case, the GW node must also be configured as a GW client searching for tunnel announcements from it's potential GW-client nodes to their (rather small) private (but outside routable) address space. The details for such configuration are described in the following section. 
373
However, for completeness a simple configuration for the GW-node to search for back routes to clients is given here. The following commands essentially configures a GW node to:
374 45 Axel Neumann
* use the IP addresses 10.254.10.1 and 2012:1234:5678:90ab::1 for tunnel traffic
375 46 Axel Neumann
* search and automatically configure back-wards tunnel to nodes that advertise an IPv4 prefix with a minimum length of 24 and are within the range of 10.254.0.0/16
376 45 Axel Neumann
* search and automatically configure back-wards tunnel to nodes that advertise an IPv6 prefix with a minimum length of 64 and are within the range of 2012:1234:5678::/48
377 1 Pau Escrich
378 34 Axel Neumann
<pre>
379 46 Axel Neumann
bmx6 -c tun4Address=10.254.10.1/32 tun6Address=2012:1234:5678:1::1/64 
380
bmx6 -c tunOut=v4Nodes /network=10.254.0.0/16 /minPrefixLen=24
381
bmx6 -c tunOut=v6Nodes /network=2012:1234:5678::/48 /minPrefixLen=64
382 34 Axel Neumann
</pre>
383
384 46 Axel Neumann
For more information please see [[Wiki#Gateway-Client-Nodes]].
385 34 Axel Neumann
386
387
388 1 Pau Escrich
h4. Gateway-Client Nodes
389 33 Axel Neumann
390 1 Pau Escrich
The configuration of GW clients can be simple but also, depending on the preferences of a desired GW-selection policy, very complex.
391
392
A general requirement for GW clients is the configuration of source addresses for all outgoing tunnels.
393
At least one network address must be configured for IPv6 and/or IPv4 tunnels using the the --tun4Address and/or --tun6Address parameters.
394 46 Axel Neumann
The specified network address will automatically be advertized as tunnel announcements, allowing the GW client to be reachable via the given addresses.
395 1 Pau Escrich
Thereby, each GW client node is also a GW node to its own (usually small) tunnel address space.
396
The selection of this address should be coordinated with GW administrators since (depending on the GW connection to other networks) only specific addresses are routable and considered to be originated from the bmx6 cloud.
397
398 46 Axel Neumann
In the following simple example a GW-client node is:
399
* specifying its own tunnel addresses for IPv4 and IPv6
400
* searching for any other kind of offered IPv4 and v6 tunnels
401 1 Pau Escrich
402 46 Axel Neumann
<pre>
403
bmx6 -c tun4Address=10.254.10.123/32 tun6Address=2012:1234:5678:123::1/64 
404
bmx6 -c tunOut=v4Default /network=0.0.0.0/0 tunOut=v6Default /network=::/0
405
</pre>
406
407
408
The disadvantage of the above configured tunnel selection policy is that offered tunnels are selected based on the path metric in the bmx6 cloud, ignoring the prefix-length of announced tunnels (routes that are more specific than others).
409
410
Imagine the following address assignment policy for the IPv4. The general idea can be straight translated to IPv6.
411
* Most nodes in the mesh cloud announce their private address ranges with a prefix length equal or larger than 24 and somewhere in the range of 10.254.0.0/16. Announcements of this type should always be preferred, even if any of the following announced types has a better end-to-end metric.
412
413
* Some BGP GW nodes are connected to other mesh clouds/areas of the same overall community network. These clouds are operating in a different IPv4 range (than 10.254.0.0/16) but always somewhere in the range of 10.0.0.0/8. Route announcements of this type should be preferred over the announcement of a default route. 
414
415
* Some DSL GW nodes are offering to share their DSL line and are announcing a default route (0.0.0.0/0). Only default route announcements from two well known GWs (with hostname pepe and paula) are acceptible. To mitigate the effects of GW switching if both GWs show a similar end-to-end metric a GW switch should only happen if the other GW is at least 30% better.
416
417
The following configuration configures a GW client respectively:
418
419
<pre>
420
bmx6 -c tun4Address=10.254.10.123/32
421
bmx6 -c tunOut=v4Nodes /network=10.254.0.0/16 /minPrefixLen=24 /ipMetric=2001
422
bmx6 -c tunOut=v4Clouds /network=10.0.0.0/8 /maxPrefixLen=16 bgp=1 /ipMetric=2002
423
bmx6 -c tunOut=-v4Default # revert the above configured v4 tunnel search
424
bmx6 -c tunOut=v4DefaultPepe  /network=0.0.0.0/0 /maxPrefixLen=0 /name=pepe  /hysteresis=30 /ipMetric=2003
425
bmx6 -c tunOut=v4DefaultPaula /network=0.0.0.0/0 /maxPrefixLen=0 /name=paula /hysteresis=30 /ipMetric=2003
426
</pre>
427 1 Pau Escrich
428 33 Axel Neumann
429
h4. Tunnel Status Information
430
431 36 Axel Neumann
Tunnel status information can be accessed with the --tunnels parameters.
432 29 Axel Neumann
433 10 Axel Neumann
434 1 Pau Escrich
435
436
h2. Bmx6 Plugins
437
438 36 Axel Neumann
h3. Compile and Install
439 1 Pau Escrich
440 36 Axel Neumann
To compile and install bmx6 daemon and all bmx6 plugins simply do:
441
<pre>
442
make build_all
443
sudo make install_all
444
</pre>
445 1 Pau Escrich
446 36 Axel Neumann
However. specific requirements may need to be fulfilled for some plugins in order to compile correctly.
447
These requirements are described in the corresponding plugin section.
448 32 Axel Neumann
449
450 1 Pau Escrich
451 36 Axel Neumann
h2. Config Plugin
452 1 Pau Escrich
453 8 Axel Neumann
454 36 Axel Neumann
h3. Requirements
455 1 Pau Escrich
456 8 Axel Neumann
uci libs are needed for the bmx6-config plugin.
457
To install it do:
458 1 Pau Escrich
<pre>
459 8 Axel Neumann
wget http://downloads.openwrt.org/sources/uci-0.7.5.tar.gz
460
tar xzvf uci-0.7.5.tar.gz
461
cd uci-0.7.5
462 1 Pau Escrich
make
463 8 Axel Neumann
sudo make install
464
</pre>
465 1 Pau Escrich
466 8 Axel Neumann
Depending on your system there happens to be an error during compilation.
467
Then edit cli.c and change line 465 to: @ char *argv[MAX_ARGS+2]; @
468
469 36 Axel Neumann
h3. Compile and Install
470 8 Axel Neumann
471
<pre>
472 36 Axel Neumann
make -C lib/bmx6_uci_config/ 
473
sudo make -C lib/bmx6_uci_config/ install
474 8 Axel Neumann
</pre>
475
476
477 36 Axel Neumann
h3. Usage
478 8 Axel Neumann
479
480
481 36 Axel Neumann
h2. Json Plugin
482 8 Axel Neumann
483
484 36 Axel Neumann
h3. Requirements
485 1 Pau Escrich
486 8 Axel Neumann
* json-c for bmx6_json plugin (debian package: libjson0 libjson0-dev)
487 1 Pau Escrich
488 8 Axel Neumann
489 1 Pau Escrich
json-c developer libs are needed!
490 8 Axel Neumann
For further reading check: http://json.org/ or https://github.com/jehiah/json-c
491
492
Note for debian sid:
493
The debian package libjson0-dev 0.10-1 seems to miss the file /usr/include/json/json_object_iterator.h
494
Manually copying it from the below mentioned json-c_0.10.orig.tar.gz archive helps.
495
496
497
To install manually (only if NOT installed via debian or other package management system):
498
<pre>
499
wget http://ftp.de.debian.org/debian/pool/main/j/json-c/json-c_0.10.orig.tar.gz
500
tar xzvf json-c_0.10.orig.tar.gz
501 1 Pau Escrich
cd json-c..
502 8 Axel Neumann
./configure ; make ; make install; ldconfig
503
</pre>
504
505
506 36 Axel Neumann
h3. Compile and Install
507 8 Axel Neumann
508 36 Axel Neumann
To compile and install only the  bmx6 json plugins:
509 1 Pau Escrich
<pre>
510 36 Axel Neumann
make -C lib/bmx6_json/ 
511
sudo make -C lib/bmx6_json/ install
512 8 Axel Neumann
</pre>
513
514
515 36 Axel Neumann
h3. Usage
516 3 Axel Neumann
517 35 Axel Neumann
518
519 36 Axel Neumann
h2. SMS Plugin
520 35 Axel Neumann
521 47 Pau Escrich
This plug-in uses routing packets to transmit any information from one node to the
522
whole network. The good point is that propagation works even if there is no continuous data-
523
path. Even though the WiFi network is under bad conditions (because the Wireless noise,
524
distance between nodes, etc...), the data will be propagated. However in the current implemen-
525 48 Simó Albert i Beltran
tation, there exist a maximum size limit of 240 Bytes for each file.
526 47 Pau Escrich
527
The API of the sms plug-in is very simple. It simply clones the content of one or more files
528
given by one node to all other nodes. All other nodes can do the same. Once started, each
529 48 Simó Albert i Beltran
node will have two directories:/var/run/bmx6/sms/rcvdSms and /var/run/bmx6/sms/sendSms. Files
530
put into the sendSms folder will be cloned to all other nodes inside rcvdSms folder.
531 47 Pau Escrich
QMP is using this feature for several things. The positioning Map information is transmitted
532
using it. There is a chat in web interface which uses it too. And in the future we are planning
533
to use it for more purposes like statistics, captive portal, MAC filter rules, etc...
534 35 Axel Neumann
535
536 36 Axel Neumann
h2. Quagga Plugin
537 35 Axel Neumann
538
The bmx6 quagga plugin can be used to exchange routes with a quagga/zebra daemon.
539
Both, export and redistribution of routes is supported.
540
541
542 36 Axel Neumann
h3. Requirements, Compile, and Install
543 35 Axel Neumann
544 41 Axel Neumann
h4. Quagga
545 1 Pau Escrich
546 41 Axel Neumann
Quagga version 0.99.21 must be patched for bmx6 support.
547
548
The bmx6 directory lib/bmx6_quagga/patches/ contains patches to enable quagga for bmx6 support.
549
The following example provides instructions for obtaining, patching, compiling, and installing quagga:
550
551
<pre>
552
wget http://download.savannah.gnu.org/releases/quagga/quagga-0.99.21.tar.gz
553
tar xzvf quagga-0.99.21.tar.gz
554
cd quagga-0.99.21
555
patch -p1 < ../bmx6/lib/bmx6_quagga/patches/quagga-0.99.21.tar.diff
556
./configure
557
make
558
sudo make install
559
</pre>
560
561
For further instructions to obtain, patch, compile, and install quagga please have a look at:
562 1 Pau Escrich
the file lib/bmx6_quagga/patches/README in the bmx6 sources.
563
564 41 Axel Neumann
h4. Bmx6
565
566 35 Axel Neumann
To compile and install the bmx6 part of the quagga plugin simply do:
567
<pre>
568 36 Axel Neumann
make -C lib/bmx6_quagga/ 
569
sudo make -C lib/bmx6_quagga/ install
570 2 Pau Escrich
</pre>
571 1 Pau Escrich
572 36 Axel Neumann
573 37 Axel Neumann
h3. Usage
574 38 Axel Neumann
575
To use the bmx6 quagga plugin it must be loaded during bmx6 daemon startup with the @ plugin=bmx6_quagga.so @ argument. 
576
Alternatively a plugin section can be defined in the bmx6 config file like this:
577
<pre>
578
config 'plugin'
579
        option 'plugin' 'bmx6_quagga.so'
580
</pre>
581
582
Once the plugin is successfully loaded, the bmx6 daemon will try to connect with the zebra process (via the ZAPI socket) 
583
and new parameters for exchanging routes with quagga/zebra daemon are enabled.
584
585
A quick documentation of the quagga-related parameters is available via the --help and --verboseHelp option.
586
If the quagga-enabled daemon is already running @ bmc6 -c verboseHelp /r=1 @ will print all currently supported parameters.
587 1 Pau Escrich
588
589 39 Axel Neumann
590
591 41 Axel Neumann
h3. Redistributing routes (from quagga/zebra to bmx6)
592 39 Axel Neumann
593
Redistribution of routes is configurable with the --redistribute parameter.
594 38 Axel Neumann
Similar to the --tunOutNet parameter,  --redistribute must be given with an arbitrary name for referencing to a specific redistribution directive and further sub-criterias.
595
596
Further mandatory sub-parameters are /bandwidth and at least one (to-be redistributed route type).
597
The following route types exist:
598
<pre>
599
  /system <VAL>                          def: 0       range: [ 0 , 1 ]
600
  /kernel <VAL>                          def: 0       range: [ 0 , 1 ]
601
  /connect <VAL>                         def: 0       range: [ 0 , 1 ]
602
  /rip <VAL>                             def: 0       range: [ 0 , 1 ]
603
  /ripng <VAL>                           def: 0       range: [ 0 , 1 ]
604
  /ospf <VAL>                            def: 0       range: [ 0 , 1 ]
605
  /ospf6 <VAL>                           def: 0       range: [ 0 , 1 ]
606
  /isis <VAL>                            def: 0       range: [ 0 , 1 ]
607
  /bgp <VAL>                             def: 0       range: [ 0 , 1 ]
608
  /babel <VAL>                           def: 0       range: [ 0 , 1 ]
609
  /hsls <VAL>                            def: 0       range: [ 0 , 1 ]
610
  /olsr <VAL>                            def: 0       range: [ 0 , 1 ]
611
  /batman <VAL>                          def: 0       range: [ 0 , 1 ]
612
</pre>
613
614 1 Pau Escrich
Only quagga/zebra routes types that are explicitly specified will be redistributed to the bmx6 network.
615 38 Axel Neumann
In addition, one usually wants to filter out networks from being redistributed based on their prefix.
616
Therefore the sub parameters /network, /minPrefixLen, and /maxPrefixLen can be used in the same way as for the --tunOutNet parameter.
617
618 41 Axel Neumann
h4. Route Aggregation
619 40 Axel Neumann
620 1 Pau Escrich
By default, maximum aggregation of to-be redistributed routes is enabled.
621 40 Axel Neumann
This means that to-be redistributed neighboring and overlapping networks with the same route type and bandwidth are aggregated if possible.
622
The extend of aggregation can be controlled with the /aggregatePrefixLen sub-parameter.
623
The given value limits the aggregation to a minimum prefix length.
624
The default of 0 defines maximum aggregation whenever possible which may not be wanted.
625
626 45 Axel Neumann
For example the GW node may be configured to redistribute the following routes:
627 40 Axel Neumann
628 45 Axel Neumann
* 10.254.20.1/32
629
* 10.254.20.0/24
630
* 10.254.21.0/24
631
* 10.254.22.0/24
632 40 Axel Neumann
* 0.0.0.0/0
633
634
The following bmx6 configuration would aggregate all 5 routes into a single 0.0.0.0/0 tunnel announcement since 0.0.0.0/0 is overlapping any other more-specific route:
635
<pre>
636
redistribute=ipv4 /bandwidth=10000000 /kernel=1 /aggregatePrefixLen=0
637
</pre>
638
639
This aggregation may be too generic since GW-client nodes are usually looking for more specific routes to specific destination.
640
The following configuration would aggregate only routes with a prefix-len larger than 16:
641
642
<pre>
643
redistribute=ipv4 /bandwidth=10000000 /kernel=1 /aggregatePrefixLen=16
644
</pre>
645
646
Resulting in the following aggregations:
647 45 Axel Neumann
* 10.254.20.1/32: Aggregated (sub-network of 10.254.20.0/24)! NOT announced!
648
* 10.254.20.0/24: Aggregated with 10.254.21.0/24! Announced as 10.254.20.0/23 
649
* 10.254.21.0/24: Aggregated with 10.254.20.0/24! Announced as 10.254.20.0/23 
650
* 10.254.22.0/24: Not aggregatable into larger network! Announced as is!
651 40 Axel Neumann
* 0.0.0.0/0:      Not aggregated (prefix-len smaller than /aggregatePrefixLen=16)! Announced as is!
652
653 38 Axel Neumann
654
655 41 Axel Neumann
h3. Exporting routes (from bmx6 to quagga/zebra)
656 42 Axel Neumann
657
658
For exporting routes received as bmx6 tunnel announcements, the /exportDistance can be used as a subparameter of the --tunOut parameter.
659
The default value of /exportDistance is 256 which is considered as infinit or disabled.
660
Any lower configured value will export the corresponding outgoing tunnel (once it becomes active) with the given distance to quagga/zebra.
661
662
A GW node usually only wants to export bmx6 routes that were announced by other (non-GW) bmx6 nodes in the mesh.
663
664 43 Axel Neumann
In the following example there are 3 other bmx6 nodes, each tunnel announcing a private /32 network.
665 1 Pau Escrich
666 43 Axel Neumann
The given parametrization configures a GW node to search, establish related tunnels, and export all tunnel announcements for other bmx6 daemons that have a prefix-length smaller that /27 and fall into the network range of 10.254.0.0/16:
667
668 1 Pau Escrich
<pre>
669 43 Axel Neumann
plugin=bmx6_quagga.so tunOut=privV4Nets /network=10.254.0.0/16 /minPrefixLen=27 /exportDistance=0
670
</pre>
671
672
Checking the export from the quagga perspective show the following:
673
<pre>
674
root@mlc1001:~# telnet localhost zebra
675
Trying ::1...
676
Trying 127.0.0.1...
677
Connected to localhost.
678
Escape character is '^]'.
679
680
Hello, this is Quagga (version 0.99.21).
681
Copyright 1996-2005 Kunihiro Ishiguro, et al.
682
683
User Access Verification
684
Password:
685
686
Router> show ip route
687
Codes: K - kernel route, C - connected, S - static, R - RIP,
688
       O - OSPF, I - IS-IS, B - BGP, H - HSLS, o - OLSR,
689
       b - BATMAN, x - BMX6, A - Babel,
690
       > - selected route, * - FIB route
691
692
K>* 0.0.0.0/0 via 10.0.0.1, eth0
693
C>* 10.0.0.0/11 is directly connected, eth0
694
x>* 10.254.10.0/32 [0/1024] is directly connected, bmx6_out0000, 00:03:24
695
C * 10.254.10.1/32 is directly connected, bmx6_out0003
696
C * 10.254.10.1/32 is directly connected, bmx6_out0002
697
C * 10.254.10.1/32 is directly connected, bmx6_out0001
698
C * 10.254.10.1/32 is directly connected, bmx6_out0000
699
C>* 10.254.10.1/32 is directly connected, bmx6_in0000
700
x>* 10.254.10.2/32 [0/1024] is directly connected, bmx6_out0001, 00:03:24
701
x>* 10.254.10.3/32 [0/1024] is directly connected, bmx6_out0002, 00:03:24
702
x>* 10.254.10.4/32 [0/1024] is directly connected, bmx6_out0003, 00:03:24
703
C>* 127.0.0.0/8 is directly connected, lo
704 42 Axel Neumann
</pre>