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