README

   1
   2 +====================================================================+
   3 | README - olsr.org OLSR daemon 0.5.4, 21.10.2007                    |
   4 +====================================================================+
   5
   6 Authors:
   7 Andreas Tønnesen(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   - Tiny Application Server (TAS).
 124
 125   - HttpInfo. This plugin implements a simple HTTP server that serves dynamic
 126     pages with lots of information about the running olsrd process.
 127
 128   - TxtInfo. This delivers output similar to the above. However, it is intended
 129     for external tools to use the output.
 130
 131   - Mini.
 132
 133   - Nameservice.
 134
 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.
 139
 140   - Dot draw. A plugin that produces output in the dot format representing
 141     the network topology.
 142
 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.
 147
 148
 149
 150 ========================
 151  * LINK QUALITY ROUTING
 152 ========================
 153
 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.
 158
 159 ==================
 160  * KNOWN PROBLEMS
 161 ==================
 162
 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.
 166
 167 ===============
 168  * FUTURE WORK
 169 ===============
 170
 171 Future work concentrates on reduction of ressource (ab)use and to make
 172 it more scalable. Of course additional useful plugins are always
 173 appreciated.
 174
 175 The current track of development is documented in the OLSR-NG
 176 project: http://olsr.funkfeuer.at
 177
 178
 179 ----------------------------------------------------------------------
 180  II.  - BUILDING AND RUNNING OLSRD
 181 ----------------------------------------------------------------------
 182
 183 =======================
 184  * GENERAL INFORMATION
 185 =======================
 186
 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
 195
 196 Ports exist for all major operating systems:
 197 - Linux
 198 - Mac OS X
 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!
 205
 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.
 208
 209
 210 ===========
 211  * PLUGINS
 212 ===========
 213
 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:
 218 make
 219 while installing requires(as root):
 220 make install
 221 in the plugins top directory (i.e. "lib/$plugin/").
 222 To use the plugins add them to the olsrd configuration file.
 223
 224 =====================
 225  * OS SUPPORT STATUS
 226 =====================
 227
 228 COMPONENT/OS    Linux   Win32   FreeBSD NetBSD  OpenBSD OSX
 229 ------------------------------------------------------------
 230 olsrd           +/+     +/+     +/+     +/+     +/+     ?
 231 olsr_switch     +/+     +/+     +/+     +/+     +/+     ?
 232 ------------------------------------------------------------
 233 PLUGINS
 234 bmf             +/+     +/?     +/+     +/+     +/+     -
 235 dot_draw        +/+     +/?     +/+     +/+     +/+     +/+
 236 dyn_gw          +/+     +/?     +/-     +/-     +/-     +/+
 237 dyn_gw_plain    +/+     +/?     +/-     +/-     +/-     +/+
 238 httpinfo        +/+     +/+     +/+     +/+     +/+     +/+
 239 mini            +/+     +/?     +/+     +/+     +/+     +/+
 240 nameservice     +/+     +/?     +/+     +/+     +/+     +/+
 241 pgraph          +/+     +/+     +/+     +/+     +/+     +/+
 242 quagga          +/+     -/-     +/+     +/+     +/+     ?
 243 secure          +/+     +/+     +/+     +/+     +/+     +/+
 244 tas             +/+     -       -       -       -       ?
 245 txtinfo         +/+     +/+     +/+     +/+     +/+     +/+
 246 ------------------------------------------------------------
 247
 248 LEGEND:   +/+ = compiles/runs
 249           +/- = compiles/does not work
 250           -   = does not compile
 251           ?   = unknown
 252
 253 =================
 254  * GUI FRONTENDS
 255 =================
 256
 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.
 260
 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".
 266
 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".
 271
 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,
 274 and exit the GUI.
 275
 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.
 281
 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.
 287
 288 IP version 6 cannot currently be selected, as support for IPv6 is not
 289 yet complete in the Windows version.
 290
 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.
 301
 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
 305 SINGLE NETWORK!
 306
 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.
 310
 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.
 317
 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
 324 the output.
 325
 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).
 332
 333 The "Routes" tab shows the routes that the currently running OLSR
 334 server has added.
 335
 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
 345 for details.
 346
 347
 348 =========
 349  * LINUX
 350 =========
 351
 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.
 356
 357 To build:
 358  make
 359 To install(as root):
 360  make install
 361 To delete object files run:
 362  make clean
 363 Optionally, to clean all generated files:
 364  make uberclean
 365
 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:
 373 olsrd
 374
 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.
 377
 378 ===========
 379  * WINDOWS
 380 ===========
 381
 382 *** COMPILING
 383
 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
 387
 388   make
 389
 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
 394
 395   ./mkmf.sh
 396
 397 This will generate "Makefile.win32" by adding dependencies to
 398 "Makefile.win32.in". Then just say
 399
 400   make -f Makefile.win32
 401
 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.
 405
 406 *** INTERFACE NAMING
 407
 408 On Linux network interfaces have nice names like "eth0". In contrast,
 409 Windows internally identifies network interfaces by pretty awkward
 410 names, for example:
 411
 412   "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
 413
 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
 417 of your interfaces:
 418
 419   olsrd.exe -int
 420
 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.
 424
 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 "?".
 430
 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.
 438
 439 *** CONFIGURATION FILE
 440
 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".
 444
 445
 446 =========================
 447  * FREEBSD/NETBSD/OPENBSD
 448 =========================
 449
 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
 454 use:
 455
 456   gmake
 457
 458 to build the olsrd executable. Then do:
 459
 460   gmake install
 461
 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.
 465
 466 =======
 467  * OSX
 468 =======
 469
 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.
 473
 474