Added -nofork option
[olsrd.git] / README
diff --git a/README b/README
index 2e60220..ef21924 100644 (file)
--- a/README
+++ b/README
 
-UnikOLSR 0.4.6
++====================================================================+
+| README - olsr.org OLSR daemon 0.4.8, 05.12.04                      |
++====================================================================+
 
-by Andreas Tonnesen(andreto@olsr.org)
-http://www.olsr.org
-
-04.08.04
-
-
-1. OLSR RFC COMPLIANCE
-
-  This version is RFC2636 compliant to my knowledge!
-
-  The OLSR-RFC definitions can be found in the olsr_protocol header file.
+Andreas Tonnesen(andreto@olsr.org)
+Thomas Lopatic  (thomas@lopatic.de)
 
+http://www.olsr.org
 
-2. EXTENTIONS
+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):
 
-  This version also has some extentions which are part of other projects:
+  - Dynamic Internet gateway. A plugin that dynamically adds and removes Internet
+    HNA transmissions based on if there exists a default gateway to Internet
+    with hop count = 0(non OLSR gateway). It has been extended to be able to
+    ping Internet nodes to check for connectivity as well.
 
-  Plugins:
+  - Dot draw. A plugin that produces output in the dot format representing
+    the network topology.
 
   - Secure OLSR plugin. This plugin adds a signature to all messages
     to ensure data integrity. This way only nodes with access to the
     shared key can participate in the routing.
-    The key is read as the first 128 bits from /root/.olsr/olsrd_secure_key
     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.
-
-  - 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).
-
-  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.
-
-  - Gateway tunneling. This is not easly configurated! For testing purposes.
-    This functioning will be updated in a later version. Do not try to
-    use this except you are 100% sure you need it!!
-
-  - Optional deletion of default gateways when recieving a 0.0.0.0/0.0.0.0
-    gw(in HNA).
-
-
-3. COMPILING & INSTALLING
+  - 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.
+
+
+========================
+ * 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
 
-  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.
+  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
 
-  These changes also go for the pluginmakefiles.
+  ./mkmf.sh
 
-  To compile:
-  'make'
+This will generate "Makefile.win32" by adding dependencies to
+"Makefile.win32.in". Then just say
 
-  To install(you must be root):
-  'make install'
+  make -f Makefile.win32
 
-  This also installs the standard configuration file((PREFIXDIR)/etc/olsrd.conf)
-  YOU MUST EDIT THIS FILE!
+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.
 
-  To clean up object files run
-  'make clean'
+*** INTERFACE NAMING
 
+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 power plugin:
-  cd lib/power
-  make; make install
+  "{EECD2AB6-C2FC-4826-B92E-CAA53B29D67C}"
 
-  To compile and install the dynamic GW plugin:
-  cd lib/dyn_gw
-  make; make install
+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:
 
-4. CONFIGURING & RUNNING:
+  olsrd.exe -int
 
-  OBS!!!!
-  Edit the configuration file to fit your needs.
+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.
 
-  Options in the config file can also be overridden by command line 
-  options. See the manual page olsrd(8) for details.
+"+" 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 "?".
 
-  To run the daemon you MUST specify which interface(s) to use either in
-  the config file or by using the -i option.
+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.
 
-  The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin. 
-  You must have root privelegies to run olsrd!
+*** CONFIGURATION FILE
 
-  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.
+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".
 
-  To use plugins add them to the configfile as explained in the file.
 
-  4.1 SOME COMMAND-LINE OPTIONS:
+===========
+ * FREEBSD
+===========
 
-  DEPRECATED
-  See the manpage for command line options.
+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
 
-5. BUGS
+  gmake OS=fbsd
 
-  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)
+to build the olsrd executable. Then say
 
+  gmake install
 
-6. FRONT-END
+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 fron-end
-    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 $