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