Initial commit of olsr_switch README
[olsrd.git] / README-Olsr-Switch.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <HTML>
3 <HEAD>
4         <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
5         <TITLE>Olsr Switch</TITLE>
6         <STYLE>
7         <!--
8                 H1 { color: #000000 }
9                 P { color: #000000; font-family: "verdana", "arial", sans-serif; font-size: 10pt }
10                 H2 { color: #000000 }
11                 H3 { color: #000000 }
12                 PRE { color: #000000 }
13         -->
14         </STYLE>
15 </HEAD>
16 <BODY>
17 <H1>Olsr_Switch network simulation</H1>
18 <P><I>$Id: README-Olsr-Switch.html,v 1.1 2005/06/03 17:25:12 kattemat Exp $</I> 
19 </P>
20 <H2>Summary</H2>
21 <P>This document gives a brief introduction to the <A HREF="http://www.olsr.org/">olsr.org</A>
22 OLSR daemon network simulation extentions and tools. The network
23 simulation tool olsr_switch provides olsrd processes running in a
24 special <I>host-emultion</I> mode with access to a virtual network.
25 Multiple such processes can run on a host. This network can be freely
26 manipulated by the user allowing for simulation of dynamic
27 large-scale networks. 
28 </P>
29 <P>Only IPv4 is supported for now. 
30 </P>
31 <H2>Background</H2>
32 <P>olsr_switch was inspired by the uml_switch used to communicate
33 between <A HREF="http://user-mode-linux.sourceforge.net/">UML</A>
34 instances, which I have used for olsrd testing. Also I remember
35 seeing that the guys at LRI working on the <A HREF="http://qolsr.lri.fr/">qolsr</A>
36 project has done something similar. 
37 </P>
38 <P>The target users for this kind of things are probably mainly
39 developers and researchers. But it might come in handy for others as
40 well. 
41 </P>
42 <H2>Description</H2>
43 <H3>olsr.org</H3>
44 <P>The olsr.org OLSR daemon is an implementation of the <A HREF="http://ietf.org/rfc/rfc3626.txt">Optimized
45 Link State Routing protocol</A> a IP routing protocol for mobile
46 ad-hoc networks. Multiple interesting extensions are available for
47 the implementation. Read more at <A HREF="http://www.olsr.org/">olsr.org</A>.
48 </P>
49 <H3>olsr_switch</H3>
50 <P>The application, called olsr_switch, is really a traffic router
51 that will allow multiple olsrd instances to connect and communicate
52 over TCP via the loopback interface. Connecting to olsr_switch on
53 remote hosts will be possible, but it is not implemented at the
54 current time. 
55 </P>
56 <P>Basically olsr_switch works on two datasets - clients and links. A
57 client is a connected olsrd process and there are two uni-directional
58 link between all nodes(A-&gt;B and B-&gt;A) that can be manipulated
59 independently. When receiving traffic from a olsrd client the switch
60 will forward this traffic to all other clients to which it has a
61 valid link. Links can be set to three different &quot;modes&quot;
62 based on the <I>quality</I> set on the link: 
63 </P>
64 <UL>
65         <LI><P STYLE="margin-bottom: 0in"><B>Open</B>(quality 100) - all
66         traffic will be forwarded over this link. 
67         </P>
68         <LI><P STYLE="margin-bottom: 0in"><B>Closed</B>(quality 0) - no
69         traffic will be forwarded over this link. 
70         </P>
71         <LI><P><B>Lossy</B>(quality 1-99) - in this mode the quality
72         constraint is used as the chance in percentage, for traffic to be
73         forwarded over the link. So if quality is set to 25 there will in
74         average be 75% packet loss. 
75         </P>
76 </UL>
77 <P>The application provides the user with a prompt/shell where
78 various commands for topology manipulation or data retrieval are
79 available. A help command is provided for the users convenience. This
80 help command will also provide the user with specific help on all
81 available commands. More on this later. 
82 </P>
83 <H3>olsrd host-emulation clients</H3>
84 <P>The communication interface against olsr_switch can naturally not
85 be 100% transparent for the olsrd process which normally runs on
86 UDP/698 on &quot;real&quot; network interfaces. Olsrd itself had to
87 be modified to set up a virtual interface connecting to olsr_switch.
88 This virtual interface is transparent to all overlying functionality.
89 This means that that olsrd host-emulation can run in both RFC and LQ
90 mode, and that plugins can be loaded normally etc. But no routes are
91 added by the olsrd process. Later on route information might be
92 signaled from the olsrd instance to olsr_switch so that a centralized
93 route database is available to the user. As of now, you can watch the
94 olsrd debug output or easier yet, run one node with the httpinfo
95 plugin to get the route/topology/link information. 
96 </P>
97 <P>Currently olsrd cannot run on both real and host-emulation
98 interfaces, but this might change in the future if I get convinced
99 that it is useful. No routes can be added by the host-emulating olsrd
100 instances, so 
101 </P>
102 <H2>Building and running</H2>
103 <P>As of yet, olsr_switch builds and runs on GNU/Linux and FreeBSD
104 systems. 
105 </P>
106 <H3>Building</H3>
107 <P>The olsr.org olsrd source code and pre-compiled packages can be
108 downloaded from the olsr.org <A HREF="http://www.olsr.org/index.cgi?action=download">download</A>
109 section. But as of now you need the CVS version if you want the
110 olsr_switch code. To check out the current snapshot do: 
111 </P>
112 <PRE>cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/olsrd login
113
114 cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/olsrd co olsrd-current</PRE><P>
115 Now enter the olsrd source directory and do: 
116 </P>
117 <PRE STYLE="margin-bottom: 0.2in">olsrd-current# make</PRE><P>
118 to build olsrd itself, and: 
119 </P>
120 <PRE STYLE="margin-bottom: 0.2in">olsrd-current# make switch</PRE><P>
121 to build olsr_switch. If no error messages occurred, you should now
122 have the two executables <I>olsrd</I> and <I>olsr_switch</I>
123 available in the current directory. 
124 </P>
125 <H3>Running</H3>
126 <P>Before starting any olsrd host-emu clients the switch must be
127 started. This is done using the command <I>olsr_switch</I> and the
128 application will initiate the communication socket and provide the
129 user with a prompt for input: 
130 </P>
131 <PRE>olsrd-current# ./olsr_switch
132 olsrd host-switch daemon version 0.1 starting
133 Initiating socket TCP port 10150
134 OHS command interpreter reading from STDIN
135 &gt;</PRE><P>
136 <BR><BR>
137 </P>
138 <P>To start olsrd in host-emulation mode do: 
139 </P>
140 <PRE STYLE="margin-bottom: 0.2in">./olsrd -hemu <B>IP-ADDRESS</B></PRE><P>
141 Here <I>IP-ADDRESS</I> will be the IP address that the process will
142 set as its main address in the emulation mode. This address has no
143 connection to the real IP-stack and can be chosen freely. Of cause,
144 no two instances can run using the same IP.<BR>It might be wise to
145 have a separate olsrd configuration file for host-emulation. In that
146 case issue: 
147 </P>
148 <PRE STYLE="margin-bottom: 0.2in">./olsrd -f <B>FILENAME</B> -hemu <B>IP-ADDRESS</B></PRE><P>
149 As of now there is no emulated destination address used. All traffic
150 will be passed on regardless of the network address used. Olsrd
151 communicates using broadcast/multicast so that multiple &quot;overlapping&quot;
152 networks might exist. 
153 </P>
154 <H2>Command-line interface</H2>
155 <P>Blah blah blah 
156 </P>
157 <H3>help</H3>
158 <P>Type 'help cmd' for help on a specific command 
159 </P>
160 <PRE>&gt; help
161 Olsrd host switch version 0.1
162 Available commands:
163         help - Help on shell commands
164         exit - Exits olsr host switch
165         log - Displays or sets log bits
166         list - List all connected clients or links
167         link - Manipulate links</PRE><H3>
168 list</H3>
169 <P>The <I>list</I> command is used for client and link listing. The
170 help page states: 
171 </P>
172 <PRE>&gt; help list
173 Usage: <B>list &lt;clients|links&gt;</B>
174 Description:
175 <I>This command will list all the clients or all the links registered </I>
176 <I>by olsr_switch. By default clients are listed.</I></PRE><H3>
177 link</H3>
178 <P>The <I>link</I> command is used for manipulating links. Here is
179 the help page for this command: 
180 </P>
181 <PRE>&gt; help link
182 Usage: <B>link &lt;bi&gt; [srcIP|*] [dstIP|*] [0-100]</B>
183 Description:
184 <I>This command is used for manipulating olsr links. The link quality </I>
185 <I>is a number between 0-100 representing the chance in percentage </I>
186 <I>for a packet to be forwarded</I>
187 <I>on the link.</I>
188 To make the link between 10.0.0.1 and 10.0.0.2 have 50% packetloss do:
189  link 10.0.0.1 10.0.0.2 50
190 Note that this will only effect the unidirectional link 
191 10.0.0.1 -&gt; 10.0.0.2. To make the changes affect traffic 
192 in both directions do:
193  link bi 10.0.0.1 10.0.0.2 50
194 To completely block a link do:
195  link 10.0.0.1 10.0.0.2 0
196 To make all traffic pass(delete the entry) do:
197  link 10.0.0.1 10.0.0.2 100
198 Note that &quot;bi&quot; can be used in all these examples.
199 Wildcard source and/or destinations are also supported.
200 To block all traffic from a node do:
201 link 10.0.0.1 * 0
202 To set 50% packetloss on all links to 10.0.0.2 do:
203  link * 10.0.0.2 50
204 To delete all links do:
205  link * * 100
206 Wildcards can also be used in combination with 'bi'.
207 To list all manipulated links use 'list links'.</PRE><H3>
208 others</H3>
209 <P>Two other commands are available: 
210 </P>
211 <UL>
212         <LI><P STYLE="margin-bottom: 0in"><B>exit</B> - terminates
213         olsr_switch. 
214         </P>
215         <LI><P><B>log</B> - sets the log level. 
216         </P>
217 </UL>
218 <P>Read the help pages for details. 
219 </P>
220 <H2>Running olsrd in host-emulation mode</H2>
221 <P>Now for a real world example of connecting olsrd instances. Let's
222 assume we have a modified configuration file, <I>/etc/olsrd.emu.conf</I>
223 that we use for host-emu instances. We'll choose the 10.0.0.0/24 IP
224 address space for our clients.<BR>First start the olsr_switch in one
225 terminal: 
226 </P>
227 <PRE STYLE="margin-bottom: 0.2in">./olsr_switch</PRE><P>
228 Now start the olsrd instances in other terminal(s). If you want to
229 follow olsrd operation you should use a debug value &gt; 0. To easen
230 CPU usage and terminal count you can start multiple instances that
231 will run in the background using the <I>-d 0</I> option. In this
232 example we'll run our olsrd instances in the foreground using debug
233 level 1. Start them off(in separate terminals) using: 
234 </P>
235 <PRE STYLE="margin-bottom: 0.2in">./olsrd -f /etc/olsrd.emu.conf -hemu 10.0.0.x -d 1</PRE><P>
236 where x is 1-8(we'll run 8 instances). The <A HREF="http://www.gnu.org/software/screen/">screen</A>
237 terminal multiplexer application is <I>highly</I> recomended for
238 making your life easier if working on multiple terminals. 
239 </P>
240 <P>Here is the output form the 10.0.0.1 instance of olsrd after some
241 time: 
242 </P>
243 <PRE>       *** olsr.org - 0.4.10-pre (May 30 2005) ***
244
245 --- 20:53:26.58 ---------------------------------------------------- LINKS
246
247 IP address       hyst   LQ     lost   total  NLQ    ETX
248 10.0.0.8         0.000  1.000  0      10     1.000  1.00
249 10.0.0.7         0.000  1.000  0      10     1.000  1.00
250 10.0.0.6         0.000  1.000  0      10     1.000  1.00
251 10.0.0.5         0.000  1.000  0      10     1.000  1.00
252 10.0.0.4         0.000  1.000  0      10     1.000  1.00
253 10.0.0.3         0.000  1.000  0      10     1.000  1.00
254 10.0.0.2         0.000  1.000  0      10     1.000  1.00
255
256 --- 20:53:26.58 ------------------------------------------------ NEIGHBORS
257
258 IP address       LQ     NLQ    SYM   MPR   MPRS  will
259 10.0.0.2         1.000  1.000  YES   NO    NO    3
260 10.0.0.3         1.000  1.000  YES   NO    NO    3
261 10.0.0.4         1.000  1.000  YES   NO    NO    3
262 10.0.0.5         1.000  1.000  YES   NO    NO    3
263 10.0.0.6         1.000  1.000  YES   NO    NO    3
264 10.0.0.7         1.000  1.000  YES   NO    NO    3
265 10.0.0.8         1.000  1.000  YES   NO    NO    3
266
267 --- 20:53:26.58 ------------------------------------------------- TOPOLOGY
268
269 Source IP addr   Dest IP addr     LQ     ILQ    ETX
270 </PRE><P>
271 We have our own virtual network! :-) At out switch prompt the command
272 <I>list</I> yields the following output: 
273 </P>
274 <PRE>All connected clients:
275         10.0.0.8 - Rx: 647 Tx: 89 LinkCnt: 0
276         10.0.0.7 - Rx: 752 Tx: 105 LinkCnt: 0
277         10.0.0.6 - Rx: 790 Tx: 120 LinkCnt: 0
278         10.0.0.5 - Rx: 809 Tx: 112 LinkCnt: 0
279         10.0.0.4 - Rx: 811 Tx: 125 LinkCnt: 0
280         10.0.0.3 - Rx: 804 Tx: 138 LinkCnt: 0
281         10.0.0.2 - Rx: 805 Tx: 140 LinkCnt: 0
282         10.0.0.1 - Rx: 829 Tx: 119 LinkCnt: 0</PRE><P>
283 Hey - everything is running a-ok! 
284 </P>
285 <H2>Manipulating links</H2>
286 <P>So lets create some link trouble. This introduction has become too
287 long already, so we'll introduce two simple example conditions: 
288 </P>
289 <UL>
290         <LI><P STYLE="margin-bottom: 0in">We want 10.0.0.1 only to have a
291         link to 10.0.0.2 and no one else. 
292         </P>
293         <LI><P>We want 10.0.0.8 only to have 25% chance of getting direct
294         traffic trough to 10.0.0.2,3,4 
295         </P>
296 </UL>
297 <P>Here's what we need to do: 
298 </P>
299 <PRE>&gt; link bi 10.0.0.1 * 0
300 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.8 quality 0
301 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.7 quality 0
302 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.6 quality 0
303 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.5 quality 0
304 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.4 quality 0
305 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.3 quality 0
306 Setting bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.2 quality 0
307
308
309 &gt; link bi 10.0.0.1 10.0.0.2 100
310 Removing bidirectional link(s) 10.0.0.1 &lt;=&gt; 10.0.0.2 quality 100
311
312 &gt; list links
313 All configured links:
314         10.0.0.8 =&gt; 10.0.0.1 Quality: 0
315         10.0.0.7 =&gt; 10.0.0.1 Quality: 0
316         10.0.0.6 =&gt; 10.0.0.1 Quality: 0
317         10.0.0.5 =&gt; 10.0.0.1 Quality: 0
318         10.0.0.4 =&gt; 10.0.0.1 Quality: 0
319         10.0.0.3 =&gt; 10.0.0.1 Quality: 0
320         10.0.0.1 =&gt; 10.0.0.3 Quality: 0
321         10.0.0.1 =&gt; 10.0.0.4 Quality: 0
322         10.0.0.1 =&gt; 10.0.0.5 Quality: 0
323         10.0.0.1 =&gt; 10.0.0.6 Quality: 0
324         10.0.0.1 =&gt; 10.0.0.7 Quality: 0
325         10.0.0.1 =&gt; 10.0.0.8 Quality: 0
326 </PRE><P>
327 Now our first condition is met. First all bidirectional links from
328 10.0.0.1 was blocked and then the bidirectional link to 10.0.0.2 was
329 opened. Now 10.0.0.1 can only see 10.0.0.2 as a neighbor. Note that
330 only manipulated links are listed when issuing 'list links'. olsrd at
331 10.0.0.1 now shows: 
332 </P>
333 <PRE>       *** olsr.org - 0.4.10-pre (May 30 2005) ***
334
335 --- 21:17:46.06 ---------------------------------------------------- LINKS
336
337 IP address       hyst   LQ     lost   total  NLQ    ETX
338 10.0.0.2         0.000  1.000  0      10     1.000  1.00
339
340 --- 21:17:46.06 ------------------------------------------------ NEIGHBORS
341
342 IP address       LQ     NLQ    SYM   MPR   MPRS  will
343 10.0.0.2         1.000  1.000  YES   YES   NO    3
344
345 --- 21:17:46.06 ------------------------------------------------- TOPOLOGY
346
347 Source IP addr   Dest IP addr     LQ     ILQ    ETX
348 10.0.0.2         10.0.0.1         1.000  1.000  1.00
349 10.0.0.2         10.0.0.3         1.000  1.000  1.00
350 10.0.0.2         10.0.0.4         1.000  1.000  1.00
351 10.0.0.2         10.0.0.5         1.000  1.000  1.00
352 10.0.0.2         10.0.0.6         1.000  1.000  1.00
353 10.0.0.2         10.0.0.7         1.000  1.000  1.00
354 10.0.0.2         10.0.0.8         1.000  1.000  1.00</PRE><P>
355 works like a charm. Now let's make sure we can meet condition two: 
356 </P>
357 <PRE>&gt; link bi 10.0.0.8 10.0.0.2 25
358 Setting bidirectional link(s) 10.0.0.8 &lt;=&gt; 10.0.0.2 quality 25
359
360 &gt; link bi 10.0.0.8 10.0.0.3 25
361 Setting bidirectional link(s) 10.0.0.8 &lt;=&gt; 10.0.0.3 quality 25
362
363 &gt; link bi 10.0.0.8 10.0.0.4 25
364 Setting bidirectional link(s) 10.0.0.8 &lt;=&gt; 10.0.0.4 quality 25
365
366 &gt; list links
367 All configured links:
368         10.0.0.8 =&gt; 10.0.0.4 Quality: 25
369         10.0.0.8 =&gt; 10.0.0.3 Quality: 25
370         10.0.0.8 =&gt; 10.0.0.2 Quality: 25
371         10.0.0.8 =&gt; 10.0.0.1 Quality: 0
372         10.0.0.7 =&gt; 10.0.0.1 Quality: 0
373         10.0.0.6 =&gt; 10.0.0.1 Quality: 0
374         10.0.0.5 =&gt; 10.0.0.1 Quality: 0
375         10.0.0.4 =&gt; 10.0.0.8 Quality: 25
376         10.0.0.4 =&gt; 10.0.0.1 Quality: 0
377         10.0.0.3 =&gt; 10.0.0.8 Quality: 25
378         10.0.0.3 =&gt; 10.0.0.1 Quality: 0
379         10.0.0.2 =&gt; 10.0.0.8 Quality: 25
380         10.0.0.1 =&gt; 10.0.0.3 Quality: 0
381         10.0.0.1 =&gt; 10.0.0.4 Quality: 0
382         10.0.0.1 =&gt; 10.0.0.5 Quality: 0
383         10.0.0.1 =&gt; 10.0.0.6 Quality: 0
384         10.0.0.1 =&gt; 10.0.0.7 Quality: 0
385         10.0.0.1 =&gt; 10.0.0.8 Quality: 0
386 </PRE><P>
387 Now for a look at olsrd 10.0.0.8s output: 
388 </P>
389 <PRE>       *** olsr.org - 0.4.10-pre (May 30 2005) ***
390
391 --- 21:23:00.35 ---------------------------------------------------- LINKS
392
393 IP address       hyst   LQ     lost   total  NLQ    ETX
394 10.0.0.7         0.000  1.000  0      10     1.000  1.00
395 10.0.0.5         0.000  1.000  0      10     1.000  1.00
396 10.0.0.6         0.000  1.000  0      10     1.000  1.00
397 10.0.0.2         0.000  0.800  2      10     0.498  2.51
398 10.0.0.3         0.000  0.600  4      10     0.498  3.35
399 10.0.0.4         0.000  0.900  1      10     0.800  1.39
400
401 --- 21:23:00.35 ------------------------------------------------ NEIGHBORS
402
403 IP address       LQ     NLQ    SYM   MPR   MPRS  will
404 10.0.0.2         0.800  0.498  YES   YES   NO    3
405 10.0.0.3         0.600  0.498  NO    NO    NO    3
406 10.0.0.4         0.900  0.800  YES   NO    NO    3
407 10.0.0.5         1.000  1.000  YES   NO    NO    3
408 10.0.0.6         1.000  1.000  YES   YES   NO    3
409 10.0.0.7         1.000  1.000  YES   YES   NO    3
410
411 --- 21:23:00.35 ------------------------------------------------- TOPOLOGY
412
413 Source IP addr   Dest IP addr     LQ     ILQ    ETX
414 10.0.0.2         10.0.0.1         1.000  1.000  1.00
415 10.0.0.2         10.0.0.3         1.000  1.000  1.00
416 10.0.0.2         10.0.0.4         1.000  1.000  1.00
417 10.0.0.2         10.0.0.5         1.000  1.000  1.00
418 10.0.0.2         10.0.0.6         1.000  1.000  1.00
419 10.0.0.2         10.0.0.7         1.000  1.000  1.00
420 10.0.0.2         10.0.0.8         0.898  0.498  2.24
421 10.0.0.5         10.0.0.4         1.000  1.000  1.00
422 10.0.0.6         10.0.0.8         1.000  1.000  1.00
423 10.0.0.7         10.0.0.2         1.000  1.000  1.00
424 10.0.0.7         10.0.0.3         1.000  1.000  1.00
425 10.0.0.7         10.0.0.8         1.000  1.000  1.00
426 </PRE><P>
427 Yes, there most certainly are some very weak links here. 
428 </P>
429 <P>Well, lets leave it at that :-) The command line interface is
430 meant to be used by applications as well as humans, so if somebody
431 wants to create a GUI front-end that should not be to much work. 
432 </P>
433 <H2>Performance</H2>
434 <P>Regarding CPU load I have not done any real testing, but I did try
435 seeing how far I could get on my 1.3Ghz/512MB-RAM desktop system
436 running olsrd instances in the background against olsrd_switch. 20
437 instances seems to work ok, but at 30 things got worse. However, this
438 was only using a idle network(no topology changes). But as soon as
439 olsrd instances can connect from other hosts one can distribute the
440 load. Also the application will be subject to various future
441 optimizations. 
442 </P>
443 <HR>
444 <P><I>by <A HREF="mailto:andreto--at--olsr.org">Andreas T&oslash;nnesen</A></I>
445 </P>
446 </BODY>
447 </HTML>