2 +====================================================================+
3 | README - olsr.org OLSR daemon 0.5.4, 21.10.2007 |
4 +====================================================================+
7 Andreas Tønnesen(andreto@olsr.org)
8 Thomas Lopatic (thomas@lopatic.de)
9 Aaron Kaplan (aaron@lo-res.org)
17 I. - GENERAL INFORMATION
19 * GETTING HOLD OF OLSRD
23 * LINK QUALITY ROUTING
27 II. - BUILDING AND RUNNING OLSRD
39 ----------------------------------------------------------------------
40 I. - GENERAL INFORMATION
41 ----------------------------------------------------------------------
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
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
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
60 A bug tracker is also available at the sourceforge project site
61 http://sourceforge.net/projects/olsrd/
63 Olsrd source or binaries can be downloaded from olsr.org. CVS is available
64 for the cutting edge features ;-)
66 The current Olsrd work is done via http://olsr.funkfeuer.at/ in the OLSR-NG
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
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:
97 * No need to change any code in the olsr daemon to add custom packages or
99 * Users are free to implement olsrd plugins and license them under whatever
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.
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.
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.
121 Plugins that are part of this release(can be found in the lib/ directory):
123 - Tiny Application Server (TAS).
125 - HttpInfo. This plugin implements a simple HTTP server that serves dynamic
126 pages with lots of information about the running olsrd process.
128 - TxtInfo. This delivers output similar to the above. However, it is intended
129 for external tools to use the output.
135 - Dynamic Internet gateway. A plugin that dynamically adds and removes Internet
136 HNA transmissions based on if there exists a default gateway to Internet
137 with hop count = 0(non OLSR gateway). It has been extended to be able to
138 ping Internet nodes to check for connectivity as well.
140 - Dot draw. A plugin that produces output in the dot format representing
141 the network topology.
143 - Secure OLSR plugin. This plugin adds a signature to all messages
144 to ensure data integrity. This way only nodes with access to the
145 shared key can participate in the routing.
146 You need to have the OpenSSL libs installed to use this plugin.
150 ========================
151 * LINK QUALITY ROUTING
152 ========================
154 Release 0.4.8 is the first version of olsrd that implements the ETX
155 link quality metric. This enables olsrd to prefer routes that have a
156 superior overall quality to routes that are worse but consist of less
157 hops. Have a look at the README-Link-Quality.html file for details.
163 There is no synchronization concept (and thus - and for Gods sake - no
164 code). Some plugins use threads for concurrency so this should be solved.
165 ATM the bmf plugin is the only one using threads.
171 Future work concentrates on reduction of ressource (ab)use and to make
172 it more scalable. Of course additional useful plugins are always
175 The current track of development is documented in the OLSR-NG
176 project: http://olsr.funkfeuer.at
179 ----------------------------------------------------------------------
180 II. - BUILDING AND RUNNING OLSRD
181 ----------------------------------------------------------------------
183 =======================
184 * GENERAL INFORMATION
185 =======================
187 Olsrd is implemented in pure C with very few dependencies. Olsrd is
188 known to run on various hardware like:
189 * x86 - your regular PC
190 * PPC - Macintosh hardware
191 * MIPSEL - Embedded systems like the LinkSys WRT54g
192 * ARM - Embedded systems like Compaq/HP iPaq
193 A binary tarball featuring x86, MIPSEL and ARM binaries is available
194 for download at olsr.org
196 Ports exist for all major operating systems:
199 - NetBSD/OpenBSD/FreeBSD: ATM the main development occurs on Linux with
200 GNU tools so occasionally it needs some minor tweaks to compile
201 it on *BSD. Please send patches if you fix problems there.
202 - Win32: You need (the relevant parts of) cygwin to compile the daemon
203 as such. The installer and GUI needs VisualC++ though.
204 Win32 is the least supported port. Feel free to send patches!
206 Packages for the operating systems and various distributions are available
207 at olsr.org. Feel free to package it and announce it on the mailing lists.
214 All the available plugins are also implemented in C and requires gcc/libc
215 to build. the dot_draw plugin compiles for Windows and GNU/Linux. the rest
216 of the plugins will only compile for GNU/Linux.
217 Building the plugins are just a matter of executing:
219 while installing requires(as root):
221 in the plugins top directory (i.e. "lib/$plugin/").
222 To use the plugins add them to the olsrd configuration file.
224 =====================
226 =====================
228 COMPONENT/OS Linux Win32 FreeBSD NetBSD OpenBSD OSX
229 ------------------------------------------------------------
230 olsrd +/+ +/+ +/+ +/+ +/+ ?
231 olsr_switch +/+ +/+ +/+ +/+ +/+ ?
232 ------------------------------------------------------------
234 bmf +/+ +/? +/+ +/+ +/+ -
235 dot_draw +/+ +/? +/+ +/+ +/+ +/+
236 dyn_gw +/+ +/? +/- +/- +/- +/+
237 dyn_gw_plain +/+ +/? +/- +/- +/- +/+
238 httpinfo +/+ +/+ +/+ +/+ +/+ +/+
239 mini +/+ +/? +/+ +/+ +/+ +/+
240 nameservice +/+ +/? +/+ +/+ +/+ +/+
241 pgraph +/+ +/+ +/+ +/+ +/+ +/+
242 quagga +/+ -/- +/+ +/+ +/+ ?
243 secure +/+ +/+ +/+ +/+ +/+ +/+
245 txtinfo +/+ +/+ +/+ +/+ +/+ +/+
246 ------------------------------------------------------------
248 LEGEND: +/+ = compiles/runs
249 +/- = compiles/does not work
257 A GUI front end for GNU/Linux using GTK is available in the gui/
258 directory. This implementation is no longer supported, and might
259 not work any more. It will be completly removed in a future release.
261 There currently is, however, a native MFC-based Windows GUI. Unlike
262 olsrd the GUI has to be compiled with Visual C++ 6. It can be found in
263 the gui/win32/ directory. Simply open the "Frontend.dsw" workspace in
264 the Visual C++ 6 IDE. Then compile "Frontend" and "Shim", which
265 creates "Switch.exe" and "Shim.exe".
267 To run the Windows GUI simply make sure that "Switch.exe", "Shim.exe",
268 "olsrd.exe", "olsrd_cfgparser.dll", and "Default.olsr" are located in
269 the same directory and run "Switch.exe". "Shim.exe" is just an
270 auxiliary console application that is required by "Switch.exe".
272 The GUI is pretty self-explanatory. The three buttons on the lower
273 right of the GUI window start the OLSR server, stop the OLSR server,
276 Use the "Settings" tab to specify the options that the GUI uses to run
277 the OLSR server "olsrd.exe". When you click "Start" the GUI generates
278 a temporary configuration file from the information given by the
279 "Settings" tab. This temporary configuration file is passed to the
280 OLSR server via its "-f" option.
282 "Offer Internet connection" is only available if you have an Internet
283 connection, i.e. if you have a default route configured. If you tick
284 this option an HNA entry for the default route is added to the
285 temporary configuration file, allowing other nodes in the OLSR network
286 to use your Internet connection.
288 IP version 6 cannot currently be selected, as support for IPv6 is not
289 yet complete in the Windows version.
291 "Enable ETX link quality" tells the OLSR server to detect the quality
292 of its links to its neighbors using a variant of the ETX
293 metric. "Window size" specifies the number of most recent packets to
294 be used when calculating the packet loss. If, for example, this
295 parameter is set to 10, then the OLSR server will calculate the packet
296 loss among the most recent 10 OLSR packets received from each
297 neighbor. If "For MPR selection only" is active, the link quality
298 information is only used to select MPRs that offer the best paths to
299 your two-hop neighbors. If "For MPR selection and routing" is active,
300 the link quality is additionally used to create the routing table.
302 WARNING - Enabling ETX breaks compliance with the OLSR
303 standard. ETX-enabled nodes do not inter-operate with nodes that have
304 ETX switched off. DO NOT USE NODES WITH DIFFERENT ETX SETTINGS IN A
307 The three buttons on the lower right of the "Settings" tab open
308 previously saved settings, save the current settings to a
309 configuration file, and reset the current settings to default values.
311 If you start the GUI with the path to a configuration file as the only
312 command line argument, the GUI opens the given configuration file and
313 runs the OLSR server with this configuration. So, saving a
314 configuration file with a ".olsr" extension, for example, and making
315 "Switch.exe" the handler for ".olsr" files enables you to run the OLSR
316 server with a simple double click on the configuration file.
318 The "Output" tab shows the output of the currently running OLSR
319 server. The output is limited to 1000 lines. The 1001st line will make
320 the first line disappear and so on. When you click "Start" The GUI
321 simply invokes the OLSR server "olsrd.exe" and intercepts its console
322 output. Use the four buttons on the upper right of the tab to freeze
323 the output, resume frozen output, save the output to a file, or clear
326 The "Nodes" tab contains information about the nodes that the OLSR
327 server currently knows about. If you click on the address of a node in
328 the "Node list" list box, the GUI populates the three "Node
329 information" list boxes on the right with the multi-point relays of
330 the selected node (MPR), the interfaces of the selected node (MID),
331 and the non-OLSR networks accessible via the selected node (HNA).
333 The "Routes" tab shows the routes that the currently running OLSR
336 The default settings for the "Settings" tab are taken from the
337 "Default.olsr" file. The configuration of the last interface in this
338 file is used to populate the per-interface settings (HELLO interval,
339 etc.) in the "Settings" tab. If you do not want to specify any
340 interface in "Default.olsr", the problem arises that you do not have
341 such a last interface. In this case simply create an interface with
342 the special name of "GUI". This tells the GUI to use the configuration
343 of the interface for the per-interface settings and to forget about
344 this interface afterward. See the comments in the "Default.olsr" file
352 To build olsrd you need to have all the regular development tools
353 installed. This includes gcc, make, glibc, makedep etc.
354 To install to a directory different from /(/etc, /usr/bin) use
355 DESTDIR=targetdir. To use other compilers set CC=yourcompiler.
361 To delete object files run:
363 Optionally, to clean all generated files:
366 Before running olsrd you must edit the default configuration file
367 /etc/olsrd.conf adding at least what interfaces olsrd is to run on.
368 Options in the config file can also be overridden by command line
369 options. See the manual pages olsrd(8) and olsrd.conf(5) for details.
370 The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin.
371 You must have root privileges to run olsrd!
372 To run olsrd just type:
375 If debug level is set to 0 olsrd will detach and run in the background,
376 if not it will keep running in your shell.
384 To compile the Windows version of the OLSR server or the dot_draw
385 plugin you need a Cygwin installation with a current version of GCC
386 and Mingw32. Simply use
390 to build the olsrd executable. Building the dot_draw plugin works
391 slightly different, we do not yet have a unified makefile for all
392 architectures here. Switch to the dot_draw directory lib/dot_draw/ and
393 generate the Windows makefile by saying
397 This will generate "Makefile.win32" by adding dependencies to
398 "Makefile.win32.in". Then just say
400 make -f Makefile.win32
402 to build the dot_draw plugin. However, make sure that you have build
403 olsrd before that, as the dot_draw plugin requires some object files
404 that are only generated when olsrd is built.
408 On Linux network interfaces have nice names like "eth0". In contrast,
409 Windows internally identifies network interfaces by pretty awkward
412 "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
414 Hence, the Windows version implements its own naming scheme that maps
415 each internal name to a made-up name like "if03", which is easier to
416 memorize. Simply invoke the OLSR server as follows to obtain its view
421 This lists the made-up interface names along with their current IP
422 addresses to enable you to find out which made-up interface name
423 corresponds to which of your physical interfaces.
425 "+" in front of the IP addresses means that the OLSR server has
426 identified the interface as a WLAN interface. "-" indicates that the
427 OLSR server considers this interface to be a wired interface. "?"
428 means "no idea". Detection currently only works on NT, 2000, and
429 XP. Windows 9x and ME will always display "?".
431 For techies: The made-up names consist of the string "if" followed by
432 a two-digit hex representation of the least significant byte of the
433 Windows-internal interface index, which should be different for each
434 interface and thus make each made-up name unique. Again, this is
435 undocumented and this assumption may be wrong in certain cases. So, if
436 the "-int" option reports two interfaces that have the same name,
437 please do let me know.
439 *** CONFIGURATION FILE
441 If you do not specify a configuration file, the OLSR server
442 ("olsrd.exe") by default attempts to use "olsrd.conf" in your Windows
443 directory, e.g. "C:\WINDOWS\olsrd.conf".
446 =========================
447 * FREEBSD/NETBSD/OPENBSD
448 =========================
450 The FreeBSD port should be relativley stable at this point.
451 The OpenBSD and NetBSD versions are pretty much untested. They have
452 not been extensively tested beyond "doesn't core dump and it looks
453 like it adds routes". In order to build it, you need GNU make. Then
458 to build the olsrd executable. Then do:
462 to install the executable, the default configuration file, and the
463 manual pages. So, basically it's the same as on Linux. Have a look at
464 the Linux section for details.
470 The OS X port is a direct descendant of the FreeBSD port. So, the same
471 limitations with respect to testing and maturity apply. Building and
472 installing works in the same was as on FreeBSD.