gateway: introduce and use removeGatewayFromList function
[olsrd.git] / unmaintained / README
1
2 +====================================================================+
3 | README - olsr.org OLSR daemon 0.5.4, 21.10.2007                    |
4 +====================================================================+
5
6 Authors:
7 Andreas Tonnesen(andreto@olsr.org)
8 Thomas Lopatic  (thomas@lopatic.de)
9 Aaron Kaplan (aaron@lo-res.org)
10
11
12 http://www.olsr.org
13
14
15 CONTENTS:
16
17 I.   - GENERAL INFORMATION
18      * ABOUT
19      * GETTING HOLD OF OLSRD
20      * RELEASE NOTES
21      * RFC COMPLIANCE
22      * PLUGINS
23      * LINK QUALITY ROUTING
24      * KNOWN PROBLEMS
25      * FUTURE WORK
26
27 II.  - BUILDING AND RUNNING OLSRD
28      * GENERAL INFORMATION
29      * PLUGINS
30      * GUI FRONTENDS
31
32      * LINUX
33      * WINDOWS
34      * FREEBSD
35      * OSX
36   
37
38
39 ----------------------------------------------------------------------
40  I.   - GENERAL INFORMATION
41 ----------------------------------------------------------------------
42
43 =========
44  * ABOUT
45 =========
46
47 The olsr.org OLSR daemon is an implementation of the Optimized Link State
48 routing protocol. The protocol is documented in RFC3626. The website
49 of olsrd is http://www.olsr.org
50
51 Olsrd is designed to be a modular an extensible implementation. It features
52 a plugin interface, allowing for developers to extend OLSR operation without
53 interfering with the core code. It also features a experimental link quality
54 routing scheme.
55
56 To ask questions or make comments, join up with the mailing lists:
57 olsr-dev@olsr.org   - development discussion
58 olsr-users@olsr.org - usage discussion
59
60 A bug tracker is also available at the sourceforge project site
61 http://sourceforge.net/projects/olsrd/
62
63 Olsrd source or binaries can be downloaded from olsr.org. CVS is available
64 for the cutting edge features ;-)
65
66 The current Olsrd work is done via http://olsr.funkfeuer.at/ in the OLSR-NG
67 project.
68
69
70 =================
71  * RELEASE NOTES
72 =================
73
74
75
76 ==================
77  * RFC COMPLIANCE
78 ==================
79
80 If olsrd is ran without using link-quality routing/MPR selection it is RFC3626
81 compliant in that it will inter-operate with other RFC3626 implementations.
82 Internally there are a few things that are solved differently that proposed 
83 in the RFC. Check out the "Conclusions" section of the "Implementing And
84 Extending The Optimized Link State routing Protocol" thesis available at
85 olsr.org.
86
87
88 ===========
89  * PLUGINS
90 ===========
91
92 Olsrd supports dynamic loading of plugins (dynamically loaded libraries) for 
93 functions like generation and processing of private package types, setting
94 olsrd configurations in run-time and much more. This design is chosen for
95 amongst others, the following reasons:
96
97  * No need to change any code in the olsr daemon to add custom packages or 
98    functionality.
99  * Users are free to implement olsrd plugins and license them under whatever 
100    terms they like.
101  * The plugins can be written in any language that can be compiled as 
102    a dynamic library. Linux even allows scripts!
103  * No need for people with extended OLSR versions to rely on heavy patching 
104    to maintain functionality when new olsrd versions are released.
105
106 OLSR provides a default forwarding algorithm that allows for forwarding of OLSR 
107 messages of unknown types. This is really neat - because it means that even if 
108 only a subset of the nodes in the network actually known how to interpret 
109 a certain message type - all nodes will forward them according to the MPR 
110 pragma. A user may want to use the optimized flooding technique in OLSR to 
111 broadcast certain information, routing related or not, to all nodes that knows 
112 how to handle this message. Services that needs to broadcast/multicast data can 
113 encapsulate data in a private OLSR message type using a olsrd plugin. 
114
115 The design of the various entities of OLSR allows one to easily add special 
116 functionality into most aspects of OLSR. One can both register functions and 
117 unregister them with the socket parser, packet parser, scheduler and HNA set etc. 
118 This opens up for possibilities like intercepting current operation and replacing 
119 it with custom actions.
120
121   Plugins that are part of this release(can be found in the lib/ directory):
122
123   - HttpInfo. This plugin implements a simple HTTP server that serves dynamic
124     pages with lots of information about the running olsrd process.
125
126   - TxtInfo. This delivers output similar to the above. However, it is intended
127     for external tools to use the output.
128
129   - Mini.
130
131   - Nameservice.
132
133   - Dynamic Internet gateway. A plugin that dynamically adds and removes Internet
134     HNA transmissions based on if there exists a default gateway to Internet
135     with hop count = 0(non OLSR gateway). It has been extended to be able to
136     ping Internet nodes to check for connectivity as well.
137
138   - Dot draw. A plugin that produces output in the dot format representing
139     the network topology.
140
141   - Secure OLSR plugin. This plugin adds a signature to all messages
142     to ensure data integrity. This way only nodes with access to the
143     shared key can participate in the routing.
144     You need to have the OpenSSL libs installed to use this plugin.
145
146
147
148 ========================
149  * LINK QUALITY ROUTING
150 ========================
151
152 Release 0.4.8 is the first version of olsrd that implements the ETX
153 link quality metric. This enables olsrd to prefer routes that have a
154 superior overall quality to routes that are worse but consist of less
155 hops. Have a look at the README-Link-Quality.html file for details.
156
157 ==================
158  * KNOWN PROBLEMS
159 ==================
160
161 There is no synchronization concept (and thus - and for Gods sake -  no
162 code). Some plugins use threads for concurrency so this should be solved.
163 ATM the bmf plugin is the only one using threads.
164
165 ===============
166  * FUTURE WORK
167 ===============
168
169 Future work concentrates on reduction of ressource (ab)use and to make
170 it more scalable. Of course additional useful plugins are always
171 appreciated.
172
173 The current track of development is documented in the OLSR-NG 
174 project: http://olsr.funkfeuer.at
175
176
177 ----------------------------------------------------------------------
178  II.  - BUILDING AND RUNNING OLSRD
179 ----------------------------------------------------------------------
180
181 =======================
182  * GENERAL INFORMATION
183 =======================
184
185 Olsrd is implemented in pure C with very few dependencies. Olsrd is 
186 known to run on various hardware like:
187  * x86    - your regular PC
188  * PPC    - Macintosh hardware
189  * MIPSEL - Embedded systems like the LinkSys WRT54g
190  * ARM    - Embedded systems like Compaq/HP iPaq
191 A binary tarball featuring x86, MIPSEL and ARM binaries is available
192 for download at olsr.org
193
194 Ports exist for all major operating systems:
195 - Linux
196 - Mac OS X
197 - NetBSD/OpenBSD/FreeBSD: ATM the main development occurs on Linux with
198          GNU tools so occasionally it needs some minor tweaks to compile
199          it on *BSD. Please send patches if you fix problems there.
200 - Win32: You need (the relevant parts of) cygwin to compile the daemon
201          as such. The installer and GUI needs VisualC++ though.
202          Win32 is the least supported port. Feel free to send patches!
203
204 Packages for the operating systems and various distributions are available
205 at olsr.org. Feel free to package it and announce it on the mailing lists.
206
207
208 ===========
209  * PLUGINS
210 ===========
211
212 All the available plugins are also implemented in C and requires gcc/libc
213 to build. the dot_draw plugin compiles for Windows and GNU/Linux. the rest
214 of the plugins will only compile for GNU/Linux.
215 Building the plugins are just a matter of executing:
216 make
217 while installing requires(as root):
218 make install
219 in the plugins top directory (i.e. "lib/$plugin/").
220 To use the plugins add them to the olsrd configuration file.
221
222 =====================
223  * OS SUPPORT STATUS
224 =====================
225
226 COMPONENT/OS    Linux   Win32   FreeBSD NetBSD  OpenBSD OSX
227 ------------------------------------------------------------
228 olsrd           +/+     +/+     +/+     +/+     +/+     ?
229 olsr_switch     +/+     +/+     +/+     +/+     +/+     ?
230 ------------------------------------------------------------
231 PLUGINS
232 bmf             +/+     +/?     +/+     +/+     +/+     -
233 dot_draw        +/+     +/?     +/+     +/+     +/+     +/+
234 dyn_gw          +/+     +/?     +/-     +/-     +/-     +/+
235 dyn_gw_plain    +/+     +/?     +/-     +/-     +/-     +/+
236 httpinfo        +/+     +/+     +/+     +/+     +/+     +/+
237 mini            +/+     +/?     +/+     +/+     +/+     +/+
238 nameservice     +/+     +/?     +/+     +/+     +/+     +/+
239 pgraph          +/+     +/+     +/+     +/+     +/+     +/+
240 quagga          +/+     -/-     +/+     +/+     +/+     ?
241 secure          +/+     +/+     +/+     +/+     +/+     +/+
242 txtinfo         +/+     +/+     +/+     +/+     +/+     +/+
243 ------------------------------------------------------------
244
245 LEGEND:   +/+ = compiles/runs
246           +/- = compiles/does not work
247           -   = does not compile
248           ?   = unknown
249
250 =================
251  * GUI FRONTENDS
252 =================
253
254 A GUI front end for GNU/Linux using GTK is available in the gui/ 
255 directory. This implementation is no longer supported, and might
256 not work any more. It will be completly removed in a future release.
257
258 There currently is, however, a native MFC-based Windows GUI. Unlike
259 olsrd the GUI has to be compiled with Visual C++ 6. It can be found in
260 the gui/win32/ directory. Simply open the "Frontend.dsw" workspace in
261 the Visual C++ 6 IDE. Then compile "Frontend" and "Shim", which
262 creates "Switch.exe" and "Shim.exe".
263
264 To run the Windows GUI simply make sure that "Switch.exe", "Shim.exe",
265 "olsrd.exe", "olsrd_cfgparser.dll", and "Default.olsr" are located in
266 the same directory and run "Switch.exe". "Shim.exe" is just an
267 auxiliary console application that is required by "Switch.exe".
268
269 The GUI is pretty self-explanatory. The three buttons on the lower
270 right of the GUI window start the OLSR server, stop the OLSR server,
271 and exit the GUI.
272
273 Use the "Settings" tab to specify the options that the GUI uses to run
274 the OLSR server "olsrd.exe". When you click "Start" the GUI generates
275 a temporary configuration file from the information given by the
276 "Settings" tab. This temporary configuration file is passed to the
277 OLSR server via its "-f" option.
278
279 "Offer Internet connection" is only available if you have an Internet
280 connection, i.e. if you have a default route configured. If you tick
281 this option an HNA entry for the default route is added to the
282 temporary configuration file, allowing other nodes in the OLSR network
283 to use your Internet connection.
284
285 IP version 6 cannot currently be selected, as support for IPv6 is not
286 yet complete in the Windows version.
287
288 "Enable ETX link quality" tells the OLSR server to detect the quality
289 of its links to its neighbors using a variant of the ETX
290 metric. "Window size" specifies the number of most recent packets to
291 be used when calculating the packet loss. If, for example, this
292 parameter is set to 10, then the OLSR server will calculate the packet
293 loss among the most recent 10 OLSR packets received from each
294 neighbor. If "For MPR selection only" is active, the link quality
295 information is only used to select MPRs that offer the best paths to
296 your two-hop neighbors. If "For MPR selection and routing" is active,
297 the link quality is additionally used to create the routing table.
298
299 WARNING - Enabling ETX breaks compliance with the OLSR
300 standard. ETX-enabled nodes do not inter-operate with nodes that have
301 ETX switched off. DO NOT USE NODES WITH DIFFERENT ETX SETTINGS IN A
302 SINGLE NETWORK!
303
304 The three buttons on the lower right of the "Settings" tab open
305 previously saved settings, save the current settings to a
306 configuration file, and reset the current settings to default values.
307
308 If you start the GUI with the path to a configuration file as the only
309 command line argument, the GUI opens the given configuration file and
310 runs the OLSR server with this configuration. So, saving a
311 configuration file with a ".olsr" extension, for example, and making
312 "Switch.exe" the handler for ".olsr" files enables you to run the OLSR
313 server with a simple double click on the configuration file.
314
315 The "Output" tab shows the output of the currently running OLSR
316 server. The output is limited to 1000 lines. The 1001st line will make
317 the first line disappear and so on. When you click "Start" The GUI
318 simply invokes the OLSR server "olsrd.exe" and intercepts its console
319 output. Use the four buttons on the upper right of the tab to freeze
320 the output, resume frozen output, save the output to a file, or clear
321 the output.
322
323 The "Nodes" tab contains information about the nodes that the OLSR
324 server currently knows about. If you click on the address of a node in
325 the "Node list" list box, the GUI populates the three "Node
326 information" list boxes on the right with the multi-point relays of
327 the selected node (MPR), the interfaces of the selected node (MID),
328 and the non-OLSR networks accessible via the selected node (HNA).
329
330 The "Routes" tab shows the routes that the currently running OLSR
331 server has added.
332
333 The default settings for the "Settings" tab are taken from the
334 "Default.olsr" file. The configuration of the last interface in this
335 file is used to populate the per-interface settings (HELLO interval,
336 etc.) in the "Settings" tab. If you do not want to specify any
337 interface in "Default.olsr", the problem arises that you do not have
338 such a last interface. In this case simply create an interface with
339 the special name of "GUI". This tells the GUI to use the configuration
340 of the interface for the per-interface settings and to forget about
341 this interface afterward. See the comments in the "Default.olsr" file
342 for details.
343
344
345 =========
346  * LINUX
347 =========
348
349 To build olsrd you need to have all the regular development tools 
350 installed. This includes gcc, make, glibc, makedep etc.
351 To install to a directory different from /(/etc, /usr/bin) use 
352 DESTDIR=targetdir. To use other compilers set CC=yourcompiler.
353
354 To build:
355  make
356 To install(as root):
357  make install
358 To delete object files run:
359  make clean
360 Optionally, to clean all generated files:
361  make uberclean
362
363 Before running olsrd you must edit the default configuration file 
364 /etc/olsrd.conf adding at least what interfaces olsrd is to run on. 
365 Options in the config file can also be overridden by command line 
366 options. See the manual pages olsrd(8) and olsrd.conf(5) for details.
367 The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin. 
368 You must have root privileges to run olsrd!
369 To run olsrd just type:
370 olsrd
371
372 If debug level is set to 0 olsrd will detach and run in the background, 
373 if not it will keep running in your shell.
374
375 ===========
376  * WINDOWS
377 ===========
378
379 *** COMPILING
380
381 To compile the Windows version of the OLSR server or the dot_draw
382 plugin you need a Cygwin installation with a current version of GCC
383 and Mingw32. Simply use
384
385   make
386
387 to build the olsrd executable. Building the dot_draw plugin works
388 slightly different, we do not yet have a unified makefile for all
389 architectures here. Switch to the dot_draw directory lib/dot_draw/ and
390 generate the Windows makefile by saying
391
392   ./mkmf.sh
393
394 This will generate "Makefile.win32" by adding dependencies to
395 "Makefile.win32.in". Then just say
396
397   make -f Makefile.win32
398
399 to build the dot_draw plugin. However, make sure that you have build
400 olsrd before that, as the dot_draw plugin requires some object files
401 that are only generated when olsrd is built.
402
403 *** INTERFACE NAMING
404
405 On Linux network interfaces have nice names like "eth0". In contrast,
406 Windows internally identifies network interfaces by pretty awkward
407 names, for example:
408
409   "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
410
411 Hence, the Windows version implements its own naming scheme that maps
412 each internal name to a made-up name like "if03", which is easier to
413 memorize. Simply invoke the OLSR server as follows to obtain its view
414 of your interfaces:
415
416   olsrd.exe -int
417
418 This lists the made-up interface names along with their current IP
419 addresses to enable you to find out which made-up interface name
420 corresponds to which of your physical interfaces.
421
422 "+" in front of the IP addresses means that the OLSR server has
423 identified the interface as a WLAN interface. "-" indicates that the
424 OLSR server considers this interface to be a wired interface. "?"
425 means "no idea". Detection currently only works on NT, 2000, and
426 XP. Windows 9x and ME will always display "?".
427
428 For techies: The made-up names consist of the string "if" followed by
429 a two-digit hex representation of the least significant byte of the
430 Windows-internal interface index, which should be different for each
431 interface and thus make each made-up name unique. Again, this is
432 undocumented and this assumption may be wrong in certain cases. So, if
433 the "-int" option reports two interfaces that have the same name,
434 please do let me know.
435
436 *** CONFIGURATION FILE
437
438 If you do not specify a configuration file, the OLSR server
439 ("olsrd.exe") by default attempts to use "olsrd.conf" in your Windows
440 directory, e.g. "C:\WINDOWS\olsrd.conf".
441
442
443 =========================
444  * FREEBSD/NETBSD/OPENBSD
445 =========================
446
447 The FreeBSD port should be relativley stable at this point.
448 The OpenBSD and NetBSD versions are pretty much untested. They have 
449 not been extensively tested beyond "doesn't core dump and it looks 
450 like it adds routes". In order to build it, you need GNU make. Then 
451 use:
452
453   gmake
454
455 to build the olsrd executable. Then do:
456
457   gmake install
458
459 to install the executable, the default configuration file, and the
460 manual pages. So, basically it's the same as on Linux. Have a look at
461 the Linux section for details.
462
463 =======
464  * OSX
465 =======
466
467 The OS X port is a direct descendant of the FreeBSD port. So, the same
468 limitations with respect to testing and maturity apply. Building and
469 installing works in the same was as on FreeBSD.
470
471