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  * GUI FRONTENDS
 213 =================
 214
 215 A GUI front end for GNU/Linux using GTK is available in the gui/ directory.
 216 this implementation is really no longer supported, but it should work with
 217 0.4.8 except that it will not show correct configuration parameters.
 218
 219 There currently is, however, a native MFC-based Windows GUI. Unlike
 220 olsrd the GUI has to be compiled with Visual C++ 6. It can be found in
 221 the gui/win32/ directory. Simply open the "Frontend.dsw" workspace in
 222 the Visual C++ 6 IDE. Then compile "Frontend" and "Shim", which
 223 creates "Switch.exe" and "Shim.exe".
 224
 225 To run the Windows GUI simply make sure that "Switch.exe", "Shim.exe",
 226 "olsrd.exe", "olsrd_cfgparser.dll", and "Default.olsr" are located in
 227 the same directory and run "Switch.exe". "Shim.exe" is just an
 228 auxiliary console application that is required by "Switch.exe".
 229
 230 The GUI is pretty self-explanatory. The three buttons on the lower
 231 right of the GUI window start the OLSR server, stop the OLSR server,
 232 and exit the GUI.
 233
 234 Use the "Settings" tab to specify the options that the GUI uses to run
 235 the OLSR server "olsrd.exe". When you click "Start" the GUI generates
 236 a temporary configuration file from the information given by the
 237 "Settings" tab. This temporary configuration file is passed to the
 238 OLSR server via its "-f" option.
 239
 240 "Offer Internet connection" is only available if you have an Internet
 241 connection, i.e. if you have a default route configured. If you tick
 242 this option an HNA entry for the default route is added to the
 243 temporary configuration file, allowing other nodes in the OLSR network
 244 to use your Internet connection.
 245
 246 IP version 6 cannot currently be selected, as support for IPv6 is not
 247 yet complete in the Windows version.
 248
 249 "Enable ETX link quality" tells the OLSR server to detect the quality
 250 of its links to its neighbors using a variant of the ETX
 251 metric. "Window size" specifies the number of most recent packets to
 252 be used when calculating the packet loss. If, for example, this
 253 parameter is set to 10, then the OLSR server will calculate the packet
 254 loss among the most recent 10 OLSR packets received from each
 255 neighbor. If "For MPR selection only" is active, the link quality
 256 information is only used to select MPRs that offer the best paths to
 257 your two-hop neighbors. If "For MPR selection and routing" is active,
 258 the link quality is additionally used to create the routing table.
 259
 260 WARNING - Enabling ETX breaks compliance with the OLSR
 261 standard. ETX-enabled nodes do not inter-operate with nodes that have
 262 ETX switched off. DO NOT USE NODES WITH DIFFERENT ETX SETTINGS IN A
 263 SINGLE NETWORK!
 264
 265 The three buttons on the lower right of the "Settings" tab open
 266 previously saved settings, save the current settings to a
 267 configuration file, and reset the current settings to default values.
 268
 269 If you start the GUI with the path to a configuration file as the only
 270 command line argument, the GUI opens the given configuration file and
 271 runs the OLSR server with this configuration. So, saving a
 272 configuration file with a ".olsr" extension, for example, and making
 273 "Switch.exe" the handler for ".olsr" files enables you to run the OLSR
 274 server with a simple double click on the configuration file.
 275
 276 The "Output" tab shows the output of the currently running OLSR
 277 server. The output is limited to 1000 lines. The 1001st line will make
 278 the first line disappear and so on. When you click "Start" The GUI
 279 simply invokes the OLSR server "olsrd.exe" and intercepts its console
 280 output. Use the four buttons on the upper right of the tab to freeze
 281 the output, resume frozen output, save the output to a file, or clear
 282 the output.
 283
 284 The "Nodes" tab contains information about the nodes that the OLSR
 285 server currently knows about. If you click on the address of a node in
 286 the "Node list" list box, the GUI populates the three "Node
 287 information" list boxes on the right with the multi-point relays of
 288 the selected node (MPR), the interfaces of the selected node (MID),
 289 and the non-OLSR networks accessible via the selected node (HNA).
 290
 291 The "Routes" tab shows the routes that the currently running OLSR
 292 server has added.
 293
 294 The default settings for the "Settings" tab are taken from the
 295 "Default.olsr" file. The configuration of the last interface in this
 296 file is used to populate the per-interface settings (HELLO interval,
 297 etc.) in the "Settings" tab. If you do not want to specify any
 298 interface in "Default.olsr", the problem arises that you do not have
 299 such a last interface. In this case simply create an interface with
 300 the special name of "GUI". This tells the GUI to use the configuration
 301 of the interface for the per-interface settings and to forget about
 302 this interface afterward. See the comments in the "Default.olsr" file
 303 for details.
 304
 305
 306 =========
 307  * LINUX
 308 =========
 309
 310 To build olsrd you need to have all the regular development tools installed.
 311 This includes gcc, make, glibc, makedep etc.
 312 To install to a directory different from /(/etc, /usr/bin) use INSTALL_PREFIX=targetdir
 313 To use other compilers set CC=yourcompiler
 314
 315 To build:
 316  make OS=linux
 317 To install(as root):
 318  make install
 319 To delete object files run:
 320  make clean
 321
 322
 323 Before running olsrd you must edit the default configuration file /etc/olsrd.conf
 324 adding at least what interfaces olsrd is to run on. Options in the config file can
 325 also be overridden by command line options. See the manual pages olsrd(8) and
 326 olsrd.conf(5) for details.
 327 The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin.
 328 You must have root privileges to run olsrd!
 329 To run olsrd just type:
 330 olsrd
 331
 332 If debug level is set to 0 olsrd will detach and run in the background, if not
 333 it will keep running in your shell.
 334
 335 ===========
 336  * WINDOWS
 337 ===========
 338
 339 *** COMPILING
 340
 341 To compile the Windows version of the OLSR server or the dot_draw
 342 plugin you need a Cygwin installation with a current version of GCC
 343 and Mingw32. Simply use
 344
 345   make OS=win32
 346
 347 to build the olsrd executable. Building the dot_draw plugin works
 348 slightly different, we do not yet have a unified makefile for all
 349 architectures here. Switch to the dot_draw directory lib/dot_draw/ and
 350 generate the Windows makefile by saying
 351
 352   ./mkmf.sh
 353
 354 This will generate "Makefile.win32" by adding dependencies to
 355 "Makefile.win32.in". Then just say
 356
 357   make -f Makefile.win32
 358
 359 to build the dot_draw plugin. However, make sure that you have build
 360 olsrd before that, as the dot_draw plugin requires some object files
 361 that are only generated when olsrd is built.
 362
 363 *** INTERFACE NAMING
 364
 365 On Linux network interfaces have nice names like "eth0". In contrast,
 366 Windows internally identifies network interfaces by pretty awkward
 367 names, for example:
 368
 369   "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
 370
 371 Hence, the Windows version implements its own naming scheme that maps
 372 each internal name to a made-up name like "if03", which is easier to
 373 memorize. Simply invoke the OLSR server as follows to obtain its view
 374 of your interfaces:
 375
 376   olsrd.exe -int
 377
 378 This lists the made-up interface names along with their current IP
 379 addresses to enable you to find out which made-up interface name
 380 corresponds to which of your physical interfaces.
 381
 382 "+" in front of the IP addresses means that the OLSR server has
 383 identified the interface as a WLAN interface. "-" indicates that the
 384 OLSR server considers this interface to be a wired interface. "?"
 385 means "no idea". Detection currently only works on NT, 2000, and
 386 XP. Windows 9x and ME will always display "?".
 387
 388 For techies: The made-up names consist of the string "if" followed by
 389 a two-digit hex representation of the least significant byte of the
 390 Windows-internal interface index, which should be different for each
 391 interface and thus make each made-up name unique. Again, this is
 392 undocumented and this assumption may be wrong in certain cases. So, if
 393 the "-int" option reports two interfaces that have the same name,
 394 please do let me know.
 395
 396 *** CONFIGURATION FILE
 397
 398 If you do not specify a configuration file, the OLSR server
 399 ("olsrd.exe") by default attempts to use "olsrd.conf" in your Windows
 400 directory, e.g. "C:\WINDOWS\olsrd.conf".
 401
 402
 403 ===========
 404  * FREEBSD
 405 ===========
 406
 407 The FreeBSD version is an initial port. It has not been extensively
 408 tested beyond "doesn't core dump and it looks like it adds routes". In
 409 order to build it, you need GNU make. Then use
 410
 411   gmake OS=fbsd
 412
 413 to build the olsrd executable. Then say
 414
 415   gmake install
 416
 417 to install the executable, the default configuration file, and the
 418 manual pages. So, basically it's the same as on Linux. Have a look at
 419 the Linux section for details.
 420
 421 =======
 422  * OSX
 423 =======
 424
 425 The OS X port is a direct descendant of the FreeBSD port. So, the same
 426 limitations with respect to testing and maturity apply. Building and
 427 installing works in the same was as on FreeBSD, except that you have
 428 to use "osx" instead of "fbsd", as in
 429
 430   gmake OS=osx
 431
 432
 433 $Id: README,v 1.8 2004/12/05 21:45:46 tlopatic Exp $