First draft of new README
[olsrd.git] / 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 extendible implementation. It features
54 a plugin interface, allowing for developers to extend OLDR 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 mailinglists:
59 olsr-dev@olsr.org   - develpoment discussion
60 olsr-users@olsr.org - usage discussion
61
62 A bugtracker is also available at the sourcefige 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 interoperate 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(dynamially loaded libraries) for 
90 functions like generation and processing of private packagetypes, 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    funtionallity.
96  * Users are free to implement olsrd plugins and licence 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 interperet 
107 a certain messagetype - 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 messagetype 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 custiom 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 hopcount = 0(non OLSR gateway). It has been extended to be able to
124     ping Intenet 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   - Powerplugin. A plugin that uses OLSRs MPR flooding to spread information
135     about the powerstatus of nodes. Ment as an example plugin to get coders
136     started.
137
138
139 ========================
140  * LINK QUALITY ROUTING
141 ========================
142
143 ==================
144  * KNOWN PROBLEMS
145 ==================
146
147 Thomas: something about the Vienna problems?
148
149 ===============
150  * FUTURE WORK
151 ===============
152
153 As the 0.4.8 release contains huge amounts of new code, the releases up to 0.5 
154 will focus much on bugfixing. If relativley serious bugs are found new releases
155 will be made fixing theese issues.
156 Asides from that there will be some focus on redesigning the IPC interface, and
157 hopefully we will end up with a neat platform independent GUI front-end to
158 work over this new IPC interface.
159 IPv6 support for Windows, FreeBSD and OSX will also be an issue.
160
161
162 ----------------------------------------------------------------------
163  II.  - BUILDING AND RUNNING OLSRD
164 ----------------------------------------------------------------------
165
166 =======================
167  * GENERAL INFORMATION
168 =======================
169
170 Olsrd is implemented in pure C with very few dependencies. The 0.4.8
171 release has removed the pthread dependency making olsrd even more
172 portable! Olsrd is known to run on various hardware like:
173  * x86    - your regular PC
174  * PPC    - Macintosh hardware
175  * MIPSEL - Embedded systems like the LinkSys WRT54g
176  * ARM    - Embedded systems like Compaq/HP iPaq
177 A binary tarball featuring x86, MIPSEL and ARM binaries is available
178 for download at olsr.org
179
180 ===========
181  * PLUGINS
182 ===========
183
184 All the available plugins are also implemented in C and requires gcc/libc
185 to build. the dot_draw plugin compiles for Windows and GNU/Linux. the rest
186 of the plugins will only compile for GNU/Linux.
187 Building the plugins are just a matter of executing:
188 make
189 while installing requires(as root):
190 make install
191 To use the plugins add them to the olsrd configuration file.
192
193 =================
194  * GUI FRONTENDS
195 =================
196
197 A GUI front end for GNU/Linux using GTK is available in the gui/ directory.
198 this implementation is really no longer supported, but it should work with
199 0.4.8 except that it will not show correct configuration parameters.
200
201 Thomas: windows GUI
202
203 =========
204  * LINUX
205 =========
206
207 To build olsrd you need to have all the regular development tools installed.
208 This includes gcc, make, glibc, makedep etc.
209 To install to a directoy different from /(/etc, /usr/bin) use INSTALL_PREFIX=targetdir
210 To use other compilers set CC=yourcompiler
211
212 To build:
213  make OS=linux
214 To install(as root):
215  make install
216 To delete object files run:
217  make clean
218
219
220 Before running olsrd you must edit the default configuration file /etc/olsrd.conf
221 adding atleast what interfaces olsrd is to run on. Options in the config file can 
222 also be overridden by command line options. See the manual pages olsrd(8) and 
223 olsrd.conf(5) for details.
224 The binary is named 'olsrd' and is installed in (PREFIX)/usr/sbin. 
225 You must have root privelegies to run olsrd!
226 To run olsrd just type:
227 olsrd
228
229 If debuglevel is set to 0 olsrd will detatch and run in the background, if not
230 it will keep running in your shell.
231
232 ===========
233  * WINDOWS
234 ===========
235
236 Thomas:
237
238 ===========
239  * FREEBSD
240 ===========
241
242 =======
243  * OSX
244 =======
245
246
247
248
249
250 $Id: README,v 1.7 2004/12/05 16:28:27 kattemat Exp $