Added -nofork option
[olsrd.git] / README
diff --git a/README b/README
index de7098e..ef21924 100644 (file)
--- a/README
+++ b/README
 
 
-olsr.org OLSR daemon 0.4.8
++====================================================================+
+| README - olsr.org OLSR daemon 0.4.8, 05.12.04                      |
++====================================================================+
 
 Andreas Tonnesen(andreto@olsr.org)
 Thomas Lopatic  (thomas@lopatic.de)
 
 http://www.olsr.org
 
 
 Andreas Tonnesen(andreto@olsr.org)
 Thomas Lopatic  (thomas@lopatic.de)
 
 http://www.olsr.org
 
-nn.11.04
-
-
-1. OLSR RFC COMPLIANCE
-
-  Olsrd is RFC3626 compliant. Most RFC realted definitions can be found 
-  in the olsr_protocol header file.
-
-
-2. EXTENTIONS
-
-  This version also has some extentions which are part of other projects:
-
-  Plugins:
+CONTENTS:
+
+I.   - GENERAL INFORMATION
+     * ABOUT
+     * GETTING HOLD OF OLSRD
+     * RELEASE NOTES
+     * RFC COMPLIANCE
+     * PLUGINS
+     * LINK QUALITY ROUTING
+     * KNOWN PROBLEMS
+     * FUTURE WORK
+
+II.  - BUILDING AND RUNNING OLSRD
+     * GENERAL INFORMATION
+     * PLUGINS
+     * GUI FRONTENDS
+
+     * LINUX
+     * WINDOWS
+     * FREEBSD
+     * OSX
+  
+
+
+----------------------------------------------------------------------
+ I.   - GENERAL INFORMATION
+----------------------------------------------------------------------
+
+=========
+ * ABOUT
+=========
+
+The olsr.org OLSR daemon is an implementation of the Optimized Link State
+routing protocol. The protocol is documented in RFC3626. The website
+of olsrd is http://www.olsr.org
+Olsrd started out as part of the master thesis project for Andreas T√łnnesen 
+at UniK University Graduate Center in Norway. This master thesis is now 
+finished(it is available for download at the olsrd website) but the olsrd 
+project moves on. Initially olsrd only compiled for GNU/Linux systems.
+Then Thomas Lopatic joined up with the project in aug. 04 and he has seen 
+to it that olsrd now, also compiles on MS-Windows, Mac OSX and FreeBSD.
+
+Olsrd is designed to be a modular an extensible implementation. It features
+a plugin interface, allowing for developers to extend OLSR operation without
+interfering with the core code. It also features a experimental link quality
+routing scheme, by Thomas and people at the c-base in Berlin.
+
+To ask questions or make comments, join up with the mailing lists:
+olsr-dev@olsr.org   - development discussion
+olsr-users@olsr.org - usage discussion
+
+A bug tracker is also available at the sourceforge project site
+http://sourceforge.net/projects/olsrd/
+
+Olsrd source or binaries can be downloaded from olsr.org. CVS is available
+for the brave ;)
+
+
+=================
+ * RELEASE NOTES
+=================
+
+
+
+==================
+ * RFC COMPLIANCE
+==================
+
+If olsrd is ran without using link-quality routing/MPR selection it is RFC3626
+compliant in that it will inter-operate with other RFC3626 implementations.
+Internally there are a few things that are solved differently that proposed 
+in the RFC. Check out the "Conclusions" section of my master thesis for details.
+
+
+===========
+ * PLUGINS
+===========
+
+Olsrd supports dynamic loading of plugins(dynamically loaded libraries) for 
+functions like generation and processing of private package types, setting
+olsrd configurations in run-time and much more. This design is chosen for
+amongst others, the following reasons:
+
+ * No need to change any code in the olsr daemon to add custom packages or 
+   functionality.
+ * Users are free to implement olsrd plugins and license them under whatever 
+   terms they like.
+ * If you, unlike yours truly, don't love C, the plugins can be written in 
+   any language that can be compiled as a dynamic library. Linux even allows 
+   scripts!
+ * No need for people with extended OLSR versions to rely on heavy patching 
+   to maintain functionality when new olsrd versions are released.
+
+OLSR provides a default forwarding algorithm that allows for forwarding of OLSR 
+messages of unknown types. This is really neat - because it means that even if 
+only a subset of the nodes in the network actually known how to interpret 
+a certain message type - all nodes will forward them according to the MPR 
+pragma. A user may want to use the optimized flooding technique in OLSR to 
+broadcast certain information, routing related or not, to all nodes that knows 
+how to handle this message. Services that needs to broadcast/multicast data can 
+encapsulate data in a private OLSR message type using a olsrd plugin. 
+
+The design of the various entities of OLSR allows one to easily add special 
+functionality into most aspects of OLSR. One can both register functions and 
+unregister them with the socket parser, packet parser, scheduler and HNA set etc. 
+This opens up for possibilities like intercepting current operation and replacing 
+it with custom actions.
+
+  Plugins that are part of this release(can be found in the lib/ directory):
 
   - Dynamic Internet gateway. A plugin that dynamically adds and removes Internet
     HNA transmissions based on if there exists a default gateway to Internet
 
   - Dynamic Internet gateway. A plugin that dynamically adds and removes Internet
     HNA transmissions based on if there exists a default gateway to Internet
-    with hopcount = 0(non OLSR gateway).
+    with hop count = 0(non OLSR gateway). It has been extended to be able to
+    ping Internet nodes to check for connectivity as well.
 
   - Dot draw. A plugin that produces output in the dot format representing
     the network topology.
 
   - Dot draw. A plugin that produces output in the dot format representing
     the network topology.
@@ -33,98 +131,303 @@ nn.11.04
     shared key can participate in the routing.
     You need to have the OpenSSL libs installed to use this plugin.
 
     shared key can participate in the routing.
     You need to have the OpenSSL libs installed to use this plugin.
 
-  - Powerplugin. A plugin that uses OLSRs MPR flooding to spread information
-    about the powerstatus of nodes. Ment as an example plugin to get coders
+  - Power plugin. A plugin that uses OLSRs MPR flooding to spread information
+    about the power status of nodes. Meant as an example plugin to get coders
     started.
 
     started.
 
-  Built in:
-
-  - IPC to GUI front-end. A gui front-end can connect to the daemon
-    if started with the -ipc switch or set in the configfile.
-
-
-3. COMPILING & INSTALLING
 
 
-  The makefile is updated in this version.
-  To install to a directoy different from / use INSTALL_PREFIX=targetdir
-  To use other compilers set CC=yourcompiler
-  All this can be done on the command line(or in scripts), so there should
-  not be any need to update the Makefile for different environments.
+========================
+ * LINK QUALITY ROUTING
+========================
+
+Release 0.4.8 is the first version of olsrd that implements the ETX
+link quality metric. This enables olsrd to prefer routes that have a
+superior overall quality to routes that are worse but consist of less
+hops. Have a look at the README-Link-Quality.html file for details.
+
+==================
+ * KNOWN PROBLEMS
+==================
+
+We suspect that in the previous version 0.4.7 OLSR traffic, in
+particular HELLO messages, is more prone to packet loss than data
+traffic. We think so, because the OLSR people of Vienna have excellent
+links but link detection reports links as broken very often. This
+problem exists in 0.4.7. We think that the reason for this is that in
+multi-interface configurations olsrd 0.4.7 sends HELLO messages via
+all interfaces at the same time without any jitter, which probably
+results in interference, as HELLO messages from different interfaces
+"collide". 0.4.8 should solve this problem, as we now have
+per-interface jitter when sending HELLO messages. So collisions
+between HELLO messages of different interfaces should be significantly
+reduced. So, if you have a multi-interface configuration, too, please
+let us know if you observe anything unusual. We'll also keep
+investigating this problem with the Vienna guys.
+
+===============
+ * FUTURE WORK
+===============
+
+As the 0.4.8 release contains huge amounts of new code, the releases up to 0.5 
+will focus much on bug fixing. If relatively serious bugs are found new releases
+will be made fixing thees issues.
+Asides from that there will be some focus on redesigning the IPC interface, and
+hopefully we will end up with a neat platform independent GUI front-end to
+work over this new IPC interface.
+IPv6 support for Windows, FreeBSD and OSX will also be an issue.
+
+
+----------------------------------------------------------------------
+ II.  - BUILDING AND RUNNING OLSRD
+----------------------------------------------------------------------
+
+=======================
+ * GENERAL INFORMATION
+=======================
+
+Olsrd is implemented in pure C with very few dependencies. The 0.4.8
+release has removed the pthread dependency making olsrd even more
+portable! Olsrd is known to run on various hardware like:
+ * x86    - your regular PC
+ * PPC    - Macintosh hardware
+ * MIPSEL - Embedded systems like the LinkSys WRT54g
+ * ARM    - Embedded systems like Compaq/HP iPaq
+A binary tarball featuring x86, MIPSEL and ARM binaries is available
+for download at olsr.org
+
+===========
+ * PLUGINS
+===========
+
+All the available plugins are also implemented in C and requires gcc/libc
+to build. the dot_draw plugin compiles for Windows and GNU/Linux. the rest
+of the plugins will only compile for GNU/Linux.
+Building the plugins are just a matter of executing:
+make
+while installing requires(as root):
+make install
+To use the plugins add them to the olsrd configuration file.
+
+=================
+ * GUI FRONTENDS
+=================
+
+A GUI front end for GNU/Linux using GTK is available in the gui/ directory.
+this implementation is really no longer supported, but it should work with
+0.4.8 except that it will not show correct configuration parameters.
+
+There currently is, however, a native MFC-based Windows GUI. Unlike
+olsrd the GUI has to be compiled with Visual C++ 6. It can be found in
+the gui/win32/ directory. Simply open the "Frontend.dsw" workspace in
+the Visual C++ 6 IDE. Then compile "Frontend" and "Shim", which
+creates "Switch.exe" and "Shim.exe".
+
+To run the Windows GUI simply make sure that "Switch.exe", "Shim.exe",
+"olsrd.exe", "olsrd_cfgparser.dll", and "Default.olsr" are located in
+the same directory and run "Switch.exe". "Shim.exe" is just an
+auxiliary console application that is required by "Switch.exe".
+
+The GUI is pretty self-explanatory. The three buttons on the lower
+right of the GUI window start the OLSR server, stop the OLSR server,
+and exit the GUI.
+
+Use the "Settings" tab to specify the options that the GUI uses to run
+the OLSR server "olsrd.exe". When you click "Start" the GUI generates
+a temporary configuration file from the information given by the
+"Settings" tab. This temporary configuration file is passed to the
+OLSR server via its "-f" option.
+
+"Offer Internet connection" is only available if you have an Internet
+connection, i.e. if you have a default route configured. If you tick
+this option an HNA entry for the default route is added to the
+temporary configuration file, allowing other nodes in the OLSR network
+to use your Internet connection.
+
+IP version 6 cannot currently be selected, as support for IPv6 is not
+yet complete in the Windows version.
+
+"Enable ETX link quality" tells the OLSR server to detect the quality
+of its links to its neighbors using a variant of the ETX
+metric. "Window size" specifies the number of most recent packets to
+be used when calculating the packet loss. If, for example, this
+parameter is set to 10, then the OLSR server will calculate the packet
+loss among the most recent 10 OLSR packets received from each
+neighbor. If "For MPR selection only" is active, the link quality
+information is only used to select MPRs that offer the best paths to
+your two-hop neighbors. If "For MPR selection and routing" is active,
+the link quality is additionally used to create the routing table.
+
+WARNING - Enabling ETX breaks compliance with the OLSR
+standard. ETX-enabled nodes do not inter-operate with nodes that have
+ETX switched off. DO NOT USE NODES WITH DIFFERENT ETX SETTINGS IN A
+SINGLE NETWORK!
+
+The three buttons on the lower right of the "Settings" tab open
+previously saved settings, save the current settings to a
+configuration file, and reset the current settings to default values.
+
+If you start the GUI with the path to a configuration file as the only
+command line argument, the GUI opens the given configuration file and
+runs the OLSR server with this configuration. So, saving a
+configuration file with a ".olsr" extension, for example, and making
+"Switch.exe" the handler for ".olsr" files enables you to run the OLSR
+server with a simple double click on the configuration file.
+
+The "Output" tab shows the output of the currently running OLSR
+server. The output is limited to 1000 lines. The 1001st line will make
+the first line disappear and so on. When you click "Start" The GUI
+simply invokes the OLSR server "olsrd.exe" and intercepts its console
+output. Use the four buttons on the upper right of the tab to freeze
+the output, resume frozen output, save the output to a file, or clear
+the output.
+
+The "Nodes" tab contains information about the nodes that the OLSR
+server currently knows about. If you click on the address of a node in
+the "Node list" list box, the GUI populates the three "Node
+information" list boxes on the right with the multi-point relays of
+the selected node (MPR), the interfaces of the selected node (MID),
+and the non-OLSR networks accessible via the selected node (HNA).
+
+The "Routes" tab shows the routes that the currently running OLSR
+server has added.
+
+The default settings for the "Settings" tab are taken from the
+"Default.olsr" file. The configuration of the last interface in this
+file is used to populate the per-interface settings (HELLO interval,
+etc.) in the "Settings" tab. If you do not want to specify any
+interface in "Default.olsr", the problem arises that you do not have
+such a last interface. In this case simply create an interface with
+the special name of "GUI". This tells the GUI to use the configuration
+of the interface for the per-interface settings and to forget about
+this interface afterward. See the comments in the "Default.olsr" file
+for details.
+
+
+=========
+ * LINUX
+=========
+
+To build olsrd you need to have all the regular development tools installed.
+This includes gcc, make, glibc, makedep etc.
+To install to a directory different from /(/etc, /usr/bin) use INSTALL_PREFIX=targetdir
+To use other compilers set CC=yourcompiler
+
+To build:
+ make OS=linux
+To install(as root):
+ make install
+To delete object files run:
+ make clean
+
+
+Before running olsrd you must edit the default configuration file /etc/olsrd.conf
+adding at least what interfaces olsrd is to run on. Options in the config file can 
+also be overridden by command line options. See the manual pages olsrd(8) and 
+olsrd.conf(5) for details.
+The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin. 
+You must have root privileges to run olsrd!
+To run olsrd just type:
+olsrd
+
+If debug level is set to 0 olsrd will detach and run in the background, if not
+it will keep running in your shell.
+
+===========
+ * WINDOWS
+===========
+
+*** COMPILING
+
+To compile the Windows version of the OLSR server or the dot_draw
+plugin you need a Cygwin installation with a current version of GCC
+and Mingw32. Simply use
 
 
-  These changes also go for the pluginmakefiles.
+  make OS=win32
+
+to build the olsrd executable. Building the dot_draw plugin works
+slightly different, we do not yet have a unified makefile for all
+architectures here. Switch to the dot_draw directory lib/dot_draw/ and
+generate the Windows makefile by saying
 
 
-  To compile:
-  'make OS=targetos'
-  Just type 'make' to see a list of available targets.
+  ./mkmf.sh
 
 
-  To install(you must be root):
-  'make install'
+This will generate "Makefile.win32" by adding dependencies to
+"Makefile.win32.in". Then just say
 
 
-  This also installs the standard configuration file((PREFIXDIR)/etc/olsrd.conf)
-  YOU MUST EDIT THIS FILE!
+  make -f Makefile.win32
 
 
-  To clean up object files run
-  'make clean'
+to build the dot_draw plugin. However, make sure that you have build
+olsrd before that, as the dot_draw plugin requires some object files
+that are only generated when olsrd is built.
 
 
+*** INTERFACE NAMING
 
 
-  To compile and install the power plugin:
-  cd lib/power
-  make; make install
+On Linux network interfaces have nice names like "eth0". In contrast,
+Windows internally identifies network interfaces by pretty awkward
+names, for example:
 
 
-  To compile and install the dynamic GW plugin:
-  cd lib/dyn_gw
-  make; make install
+  "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
 
 
-4. CONFIGURING & RUNNING:
+Hence, the Windows version implements its own naming scheme that maps
+each internal name to a made-up name like "if03", which is easier to
+memorize. Simply invoke the OLSR server as follows to obtain its view
+of your interfaces:
 
 
-  OBS!!!!
-  Edit the configuration file to fit your needs.
+  olsrd.exe -int
 
 
-  Options in the config file can also be overridden by command line 
-  options. See the manual pages olsrd(8) and olsrd.conf(5) for details.
+This lists the made-up interface names along with their current IP
+addresses to enable you to find out which made-up interface name
+corresponds to which of your physical interfaces.
 
 
-  To run the daemon you MUST specify which interface(s) to use either in
-  the config file or by using the -i option.
+"+" in front of the IP addresses means that the OLSR server has
+identified the interface as a WLAN interface. "-" indicates that the
+OLSR server considers this interface to be a wired interface. "?"
+means "no idea". Detection currently only works on NT, 2000, and
+XP. Windows 9x and ME will always display "?".
 
 
-  The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin. 
-  You must have root privelegies to run olsrd!
+For techies: The made-up names consist of the string "if" followed by
+a two-digit hex representation of the least significant byte of the
+Windows-internal interface index, which should be different for each
+interface and thus make each made-up name unique. Again, this is
+undocumented and this assumption may be wrong in certain cases. So, if
+the "-int" option reports two interfaces that have the same name,
+please do let me know.
 
 
-  To run the daemon in the background you can either start olsrd
-  with the '-d 0' switch or set DEBUG to 0 in the config file.
+*** CONFIGURATION FILE
 
 
-  To use plugins add them to the configfile as explained in the file.
+If you do not specify a configuration file, the OLSR server
+("olsrd.exe") by default attempts to use "olsrd.conf" in your Windows
+directory, e.g. "C:\WINDOWS\olsrd.conf".
 
 
-  4.1 SOME COMMAND-LINE OPTIONS:
 
 
-  DEPRECATED
-  See the manpage for command line options.
+===========
+ * FREEBSD
+===========
 
 
-5. BUGS
+The FreeBSD version is an initial port. It has not been extensively
+tested beyond "doesn't core dump and it looks like it adds routes". In
+order to build it, you need GNU make. Then use
 
 
-  Problems have been reported when running in daemon mode(DEBUG 0). If this
-  causes problems and you need to run olsrd in the background you could
-  just redirect output to /dev/null( > /dev/null)
+  gmake OS=fbsd
 
 
+to build the olsrd executable. Then say
 
 
-6. FRONT-END
+  gmake install
 
 
-  These are instructions to build the Linux GTK-based GUI.
+to install the executable, the default configuration file, and the
+manual pages. So, basically it's the same as on Linux. Have a look at
+the Linux section for details.
 
 
-  6.1 COMPILING
+=======
+ * OSX
+=======
 
 
-    To compile:
-    cd linux-gui
-    make
-    The binary is put in the bin directory
+The OS X port is a direct descendant of the FreeBSD port. So, the same
+limitations with respect to testing and maturity apply. Building and
+installing works in the same was as on FreeBSD, except that you have
+to use "osx" instead of "fbsd", as in
 
 
-  6.2 RUNNING
+  gmake OS=osx
 
 
-    To run simply:
-    cd bin
-    ./olsrd-gui
-    REMEMBER olsrd must be started using the -ipc switch or the
-    IPC option must be set to yes to be able to use the GUI front-end
 
 
-  6.3 BUGS
+$Id: README,v 1.8 2004/12/05 21:45:46 tlopatic Exp $