View source for OLSR.org Network Framework

== What is OONF ==

The OLSR.org Network Framework (OONF) is a collection of libraries that can be used
as the building blocks for networking daemons. Based on the experience with [[olsrd]]
the infrastructure was split from the routing protocol implementation itself to
make the code easier to reuse for other people.

OONF is released with a BSD style licence, which makes it easy to use and integrate
into other software projects. It this developed as an open source project on the
[[Mailinglists|Olsr.org mailing lists]] which means that everyone is welcome to
contribute feedback, bug reports or new code.

'''OONF is the basis for multiple applications!'''

This means that you can generate multiple programs (which contain different sets
of plugins) from this codebase. You do not need to use all of them at once
(see [[#Applications|Applications]]).

=== What is about BSD or Windows? ===

OONF contains an internal operation system abstraction layer similar to olsrd that
makes it easy to port it to other operation systems than Linux. Unfortunately there
is nobody in the OLSR.org team with the knowledge and time to write and maintain
the necessary code for BSD or Windows, which means both are not supported at the
moment.

If you are interested in maintaining the os abstraction code for a different
operation system we would be very happy if you speak up on the
[[Mailinglists#OLSR-dev mailing list|Developer Mailinglist]].

== Configuration ==

The [[OONF Configuration]] system has its own page.

== Logging ==

The [[OONF Logging]] system has its own page.

== Telnet Interface ==

The [[OONF Telnet Plugin|Telnet Plugin]] provides a TCP port where you can use text commands to communicate with the OONF application.
The [[OONF HTTP Plugin|HTTP Plugin]] provides another TCP port for HTTP access which also includes a way to send arbitrary text commands to the telnet port and get the result as the HTTP response.

Look at the [[:Category:OONF Telnet Commands|list of Plugins providing telnet commands]] for more information.

== Structure ==

With the release of version 0.6.0 the code of the OLSRv2 application (and its plugins)
was integrated into the OLSR.org network framework. Since then all code for OLSRv2 and
similar application has been put into a single [https://github.com/OLSR/OONF repository].

The OLSR.org network framework (OONF) main code is made from three libraries. These
libraries can be used as shared libraries or linked directly into an executable.

The rest of the functionality is made from plugins that can also be used as shared
libraries or linked statically into an executable. Plugins can also be loaded during
runtime.

=== Common-API ===

The Common-API is a loose collection of basic functions that started during in the olsrd
routing agent (the content of the src/common directory). It contains code for dynamic sized
buffers, double-linked lists, avl-trees, generic network address objects, string
and number handling.

The Common-API has no further dependencies beyond a modern libc like glibc or uclibc.

=== Config-API ===

The Config-API is a library handling configuration data. It can load and save
configurations through exchangeable format handlers, can validate the content of a
configuration against a schema defined in a program and can automatically convert
configuration data into binary data for known types.

The Config-API depends on the Common-API.

=== Core-API ===

The Core-API contains the main program of OONF that glues the configuration handling
together with a plugin loader system and an extendable logging system. The API contains
a few operation system dependent functions time handling, random numbers, lock files
and syslog access.

The Core-API depends on both the Config-API and the Common-API.

=== Plugins ===

[[OONF Plugins]] have their own page.

== Compile OONF ==

=== Requirements ===

The current OLSR.org Network Framework works on Linux systems with Kernel 2.6 or newer. It has been mostly tested with the current Debian/Ubuntu/OpenWRT kernels and GCC, but older kernels and LLVM should also work.

You need to following software to compile OONF:
* a current build system (GCC, GNU-Make, ...)
* CMake version 2.8.12 or better
* Git
* pkg-config
* libnl-3-dev (including libnl-genl-3-dev) or libnl-tiny for the [[NL80211 Listener Plugin|nl80211-listener]] plugin
* libuci for the [[UCI Configuration Plugin|cfg_uciloader]] plugin
* libtomcrypt-dev for the [[Hash Tomcrypt Plugin|hash_tomcrypt]] plugin

=== Configuration ===

There are a couple of things you can configure when building the OLSR.org Network Framework.

The most important configuration is done in the CMakeLists.txt file in the applications subfolder in ''src''. Here you can set the configuration of the executable generated by the build process including the
list of plugins statically built into the ''<name-of-executable>_static'' file.

There is also a second configuration file ''cmake/lib_config.cmake'', but in most cases
you don't need to change it. The options are either internal or can be configured with
a global cmake variable.

=== Compile by hand ===

1.) clone the OONF-API repository (Olsr.Org Network Framework)

<pre>git clone https://github.com/OLSR/OONF.git</pre>

2.) go into the "build" subdirectory of the cloned repository and compile it

<pre>
cd oonf/build
cmake ..
make
</pre>

In the end you get a couple of executables and a lot of libraries. The ''olsrd2_static'' contains both the three main libraries and all necessary plugins for a full OLSRv2 routing agent.

There are a couple of global cmake variables to change the the parameters
of the build process. You can either set them with the ''ccmake'' command
or directly when calling the ''cmake'' command to setup the makefiles.

* CMAKE_BUILD_TYPE allows you to set the compilation type. Typical values for this variable are ''Debug'' (include debug symbols), ''Release'' (exclude debug symbols, activate optimizer) or ''MinSizeRel'' (optimize for minimal size)
* OONF_LOGGING_LEVEL sets what level of logging output will be compiled into the executable. ''debug'' means you get all logging, ''info'' will remove all debug level output and ''warn'' removes everything except warnings.
* OONF_REMOVE_HELPTEXT is a boolean variable that allows to remove all the help texts from the executable. Only set it to ''false'' if you really need a few more bytes.

You can set these options directly as parameters of the cmake call:

<pre>
cmake -D CMAKE_BUILD_TYPE:String=MinSizeRel -D OONF_REMOVE_HELPTEXT:Bool=true ..
</pre>

==== Compile from tarball ====

By default OONF uses the git-command to detect its own version and integrate this information into the executable (visible with the [[Using OONF|--version command]]).

If you compile the source from a tarball, the '''.git''' subdirectory will be missing, which means the compilation will fail, which means you have to supply the two version strings by hand like this:

<pre>
cmake -D OONF_LIB_GIT:String=v0.6.1-archive -D OONF_VERSION:String=0.6.1 ..
make
</pre>

The ''OONF_VERSION'' string is used to generate the version numbers for the shared libraries, so don't place text in it. ''OONF_LIB_GIT'' is just displayed by the '''--version''' command, so you should a string in there that will allow someone else to recognize this was compiled from tarball.

The exception is a tarball made by the OONF build system itself:

<pre>
make targz
make tarbz2
make zip
</pre>

These tarballs contain an additional file that allows OONF to remember the git version information it was built from.

==== Make a debian package ====
Since February 2016 OONF contains a script to automatically build a debian package for OONF applications.

You need two dependencies installed (in addition to the ones for olsrd2 itself):
* devscripts
* dh-systemd

<pre>
apt-get install devscripts dh-systemd
</pre>

Once the dependencies are installed go into the '''./files''' subdirectory and launch the script.

'''Warning''': there is NO REASON to run this script as '''root'''. Do not do it.

<pre>
cd files
./create_debian_package.sh
</pre>

The script will automatically generate a build directory in your /tmp folder, generate the Debian package and copy it to your OONF working directory.

----

At the moment only the ''olsrd2'' application has the necessary files to build a Debian package.

It contains the ''olsrd2_static'' executable (in ''/usr/sbin''), a short man-page, a systemd service file called '''olsrd2''' (and a sysv-init one) and an (empty) config file in ''/etc/olsrd2''.

=== Compile with OpenWRT ===

OONF has been tested mostly with OpenWRT Barrier Breaker (14.07). It should also work with Attitude Adjustment (12.09), but might need a cmake backport from Barrier Breaker. Building with current trunk (Chaos Camler) is also possible.

==== Compile from openwrt-routing feed ====

Since version 0.8.2 there are OpenWRT packages in the default openwrt routing git tree.

<pre>
src-git routing https://github.com/openwrt-routing/packages.git; ...
</pre>

The package feed of the repository generates a subfolder named ''OLSR.org network framework'' in the ''Network'' folder.

There are three applications in the routing feed:
* oonf-olsrd2
* oonf-dlep-radio
* oonf-dlep-proxy

'''oonf-olsrd2''' is olsrd2 implementation with all the plugins a normal user should need.

'''oonf-dlep-radio''' is a pure dlep-radio implementation with netlink-listener, but without and routing components.

'''oonf-dlep-proxy''' contains both a dlep-radio and a dlep-router subsystem, which can be used to relay dlep information between interfaces that must not be bridged together.

==== Compile from OONF git archive ====
The OONF repository can directly be used as a package feed for OpenWRT.

Open the ''feeds.conf'' file and add the following line:
<pre>
src-git-full oonf https://github.com/OLSR/OONF
</pre>

''src-git-full'' is needed to get the release name from git tags. ''git-src-full'' is included in ''openwrt/scripts/feeds'' since 10.05.2015 (553fb6fb168ce841db476e343010e7b3f4748da3).

The package feed of the repository generates a subfolder named ''OLSR.org network framework'' in the ''Network'' folder.

You will find two packages in the folder:
* olsrd2-git
* dlep-radio-git

Both generate a statically linked binary including default configuration file and startup script.

Run ''make'' to build the selected package(s).

== Applications ==

See also [[Using OONF]] for generic information about using a OONF application.

While OONF is a generic framework, it is often compiled with a set of static plugins to build a specific application.

The standard makefile target build all applications, both with dynamically linked Core API and with statically linked Core API.

To build only statically linked executables, use the ''static'' makefile target.
To build only dynamically linked executables, use the ''dynamic'' makefile target.
In both cases the executables will contain the statically linked [[OONF Plugins|plugins]] defined in their makefile.

<pre>
> make         # build everything
...
> make static  # build all static linked executables
...
> make dynamic # build all dynamically linked executables
</pre>

=== olsrd2 ===

[[olsrd2]] can be run both with and without a configuration file. In many cases the configuration file should not be necessary at all.

In a typical mesh you might just run olsrd2 without special parameters and configuration files, just by adding the mesh interfaces as parameters:

<pre>
> ./olsrd2_static wlan0 wlan1 lo
</pre>

You just need to set your "main/node IP" on the loopback interface. Set linklocal IPs on the mesh interfaces and everything should work. You also can set NO IPv4 addresses on the mesh interfaces, OLSRd2 will generate IPv4 linklocal IPs automatically.

To build only the olsrd2 application use the ''olsrd2_dynamic'' and ''olsrd2_static'' makefile target.

<pre>
> make olsrd2_dynamic # build dynamically linked olsrd2
...
> make olsrd2_static  # build static linked olsrd2
</pre>

=== DLEP ===

[[DLEP Plugins|DLEP]] has its own page.

To build only the dlep-radio application use the ''dlep_radio_dynamic'' and ''dlep_radio_static'' makefile target.

<pre>
> make dlep_radio_dynamic # build dynamically linked dlep radio
...
> make dlep_radio_static  # build static linked dlep radio
</pre>

=== OONF base application ===

The OONF base application does not contain any plugins, everything (except the configuration file format plugin) will be loaded during runtime as a shared library. It will create the smallest executable that allows an user to share the plugin code with other applications.

To build only the oonf application use the ''oonf_dynamic'' and ''oonf_static'' makefile target.

<pre>
> make oonf_dynamic # build dynamically linked oonf
...
> make oonf_static  # build static linked oonf
</pre>