Removed superfluous maxplen config var
[olsrd.git] / files / olsrd-manpages.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <article id="olsrd_manpages" lang="en">
5   <title>Unik OLSRD Man Pages</title>
6
7   <articleinfo>
8     <titleabbrev>Olsrd Man Pages</titleabbrev>
9
10     <releaseinfo>Version 0.5.7-pre</releaseinfo>
11
12     <authorgroup>
13       <author>
14         <firstname>Sven-Ola</firstname>
15
16         <surname>Tücke</surname>
17
18         <email>sven-ola@gmx.de</email>
19       </author>
20     </authorgroup>
21
22     <abstract>
23       <para>Source for <productname>olsrd</productname> man pages and other
24       materials</para>
25     </abstract>
26   </articleinfo>
27
28   <para>This document contains sources for man pages and other materials. They
29   where converted from the original man page files which are maintained by
30   Andreas Tønnesen until 2005. Because the 0.5.7 version of
31   <productname>olsrd</productname> introduces several configuration changes
32   and removes old configuration options, a re-write was necessary in late
33   2008.</para>
34
35   <para>To process this file and convert the included man pages, use the
36   <ulink url="http://docbook2x.sourceforge.net/">docbook2X</ulink> tool
37   kit.</para>
38
39   <procedure>
40     <step>
41       <para>Install docbook2X: <command>sudo apt-get install
42       docbook2x</command></para>
43     </step>
44
45     <step>
46       <para>Install the XML DTD: <command>sudo apt-get install
47       docbook-xml</command></para>
48     </step>
49
50     <step>
51       <para>Run the converter: <command>cd ./files &amp;&amp;
52       make</command></para>
53     </step>
54   </procedure>
55
56   <bridgehead>History (cited from Andreas Tønnesen's Master Thesis, Aug
57   2004)</bridgehead>
58
59   <para>Work on the olsrd implementation was started spring 2003. At first the
60   plan was to add and experiment with MID functionality in the existing <ulink
61   url="http://hipercom.inria.fr/olsr/draft-ietf-manet-olsr-03.txt">draft3</ulink>
62   compatible OLSR implementation by <ulink
63   url="http://hipercom.inria.fr/olsr/#code">INRIA</ulink>. This was completed
64   by summer 2003. This means that much olsrd code originally was based on the
65   INRIA implementation. But since then, close to all code has been rewritten
66   or heavily modified. Olsrd is therefore considered an independent OLSR
67   implementation and not just an extension to the INRIA implementation.
68   [...]</para>
69
70   <para>In October 2003 RFC3626 was released and now full RFC compliance
71   became the goal of the project. In November 2003 UniK olsrd version 0.2.0
72   was made public available through a website. But full RFC core compliance
73   was not reached until release 0.3.8 in January 2004. Not much later 0.4.0
74   was released. It covered all auxiliary functionality as well, except
75   link-layer notifications. [...]</para>
76
77   <variablelist>
78     <varlistentry>
79       <term>Andreas Tønnesen</term>
80
81       <listitem>
82         <para>Active 2003-2006: Funder of the project, active contributor and
83         maintainer until 2007, still owning the domain olsr.org. Also created
84         the dotdraw, dyn_gw, httpinfo, and secure plugins. While Andreas
85         Tønnesen published the original implementation under GPLv2, he as well
86         as all other contributors switched to BSD in Nov 2004.</para>
87       </listitem>
88     </varlistentry>
89   </variablelist>
90
91   <bridgehead>Further History (a very brief version, WOS 03 to
92   OLSRD-NG)</bridgehead>
93
94   <para>In Juli 2004, Andreas Tønnesen presented his implementation on the
95   <ulink url="http://www.wizards-of-os.org/archiv/wos_3.html">Wizards of OS
96   03</ulink> conference in Berlin. He met a couple of free public network
97   activists from the <ulink url="http://www.c-base.org/">C-Base</ulink> /
98   <ulink url="http://www.freifunk.net/">Freifunk</ulink> community. While some
99   of them tried to test wireless mobility cycling around the conference center
100   with a moped, others established a general agreement of cooperation. This
101   leads to several contributors to jump in, namely (AFAICR, please add
102   yourself if your name is missing or sort the list if you think you're in the
103   wrong position):</para>
104
105   <variablelist>
106     <varlistentry>
107       <term>Thomas Lopatic</term>
108
109       <listitem>
110         <para>Active 2004-2007: Implemented the Link Quality Extensions (ETX),
111         solved lots of implementation issues, created the Windows GUI and
112         maintained the olsrd code base as well.</para>
113       </listitem>
114     </varlistentry>
115
116     <varlistentry>
117       <term>Bruno Randolf</term>
118
119       <listitem>
120         <para>Active 2004-2005: Solved lots of wireless driver/hardware
121         issues, contributed to olsrd implementation (fixes, cleanups),
122         contributed to TAS and Dotdraw plugins, created the Nameservice
123         plugin.</para>
124       </listitem>
125     </varlistentry>
126
127     <varlistentry>
128       <term>Sven-Ola Tücke</term>
129
130       <listitem>
131         <para>Active 2004-[...]: Started the olsrd-based <ulink
132         url="http://ff-firmware.sourceforge.net/">Freifunk Firmware</ulink> in
133         late 2004, contributed bug fixes and maintenance (general and
134         Windows), the dyn_gw_plain and arprefresh plugins as well as some
135         documentation.</para>
136       </listitem>
137     </varlistentry>
138
139     <varlistentry>
140       <term>Jens Nachtigall</term>
141
142       <listitem>
143         <para>Active 2004-2005: Contributed bug fixes, contributed to dyn_gw
144         plugin and nameservice plugins.</para>
145       </listitem>
146     </varlistentry>
147
148     <varlistentry>
149       <term>Elektra Wagenfeld</term>
150
151       <listitem>
152         <para>Active 2004-2006: Contributed ideas and valuable comments, also
153         initiated the fish-eye routing scheme.</para>
154       </listitem>
155     </varlistentry>
156
157     <varlistentry>
158       <term>Erik Tromp</term>
159
160       <listitem>
161         <para>Active 2006-[...]: Created the <ulink
162         url="http://sourceforge.net/projects/olsr-bmf/">BMF</ulink> (Basic
163         Multicast Forwarding) plugin.</para>
164       </listitem>
165     </varlistentry>
166
167     <varlistentry>
168       <term>Lorenz Schori</term>
169
170       <listitem>
171         <para>Active 2006-[...]: Created the txtinfo plugin and contributed
172         bug fixes.</para>
173       </listitem>
174     </varlistentry>
175
176     <varlistentry>
177       <term>John Hay</term>
178
179       <listitem>
180         <para>Active 2006-2008: Contributed maintenance and bug fixes for
181         IPv6.</para>
182       </listitem>
183     </varlistentry>
184
185     <varlistentry>
186       <term>Thomas Martin</term>
187
188       <listitem>
189         <para>Active 2008: Code base maintenance (mainly BSD and
190         vxWorks).</para>
191       </listitem>
192     </varlistentry>
193
194     <varlistentry>
195       <term>Immo 'FaUl' Wehrenberg</term>
196
197       <listitem>
198         <para>Active 2006-[...]: Contributed the quagga plugin.</para>
199       </listitem>
200     </varlistentry>
201   </variablelist>
202
203   <bridgehead>OLSRD-NG History (also a brief version)</bridgehead>
204
205   <para>In late 2006, the Vienna based <ulink
206   url="http://www.funkfeuer.at/">Funkfeuer</ulink> community managed to get
207   some sponsoring from <ulink url="http://www.netidee.at/">IPA</ulink>. They
208   established the OLSRD-NG project which should basically lead to a much
209   larger node count and better code quality (see <ulink
210   url="http://wiki.funkfeuer.at//index.php/Olsrd-ng">Funkfeuer Wiki on
211   OLSRD-NG</ulink>). This in turn attracts new developers for the somewhat
212   silenced team from there on:</para>
213
214   <variablelist>
215     <varlistentry>
216       <term>Aaron Kaplan</term>
217
218       <listitem>
219         <para>Active 2005-[...]: Initiator/Coordinator of the OLSRD-NG
220         project, contributed bug fixes (BSD, MacOS) and documentation.</para>
221       </listitem>
222     </varlistentry>
223
224     <varlistentry>
225       <term>Bernd Petrovitsch</term>
226
227       <listitem>
228         <para>Active 2006-[...]: Patch-juggler for the olsrd repository,
229         rewrote the build system (Makefiles) and plugin subsystem, generalized
230         commonly used code and functions, also lots of code base maintenance
231         and bug fixes as well.</para>
232       </listitem>
233     </varlistentry>
234
235     <varlistentry>
236       <term>Hannes Gredler</term>
237
238       <listitem>
239         <para>Active 2007-[...] Contributed the SPF refactoring (routing code
240         optimization), code refactorings for scheduler and nearly all internal
241         data structures, code base maintenance and bug fixes. Currently also
242         hosts the mercurial repository.</para>
243       </listitem>
244     </varlistentry>
245
246     <varlistentry>
247       <term>Henning Rogge</term>
248
249       <listitem>
250         <para>Active 2008-[...]: Reworked the LQ/ETX algorithm, contributed
251         the netsimcap (network simulation, GPL), also lots of code base
252         maintenance and bug fixes.</para>
253       </listitem>
254     </varlistentry>
255   </variablelist>
256
257   <refentry id="olsrd_8">
258     <indexterm>
259       <primary><productname>olsrd</productname></primary>
260     </indexterm>
261
262     <refentryinfo>
263       <titleabbrev><productname>olsrd</productname> Optimized Link State
264       Routing Protocol Daemon</titleabbrev>
265
266       <authorgroup>
267         <author>
268           <firstname>Sven-Ola</firstname>
269
270           <surname>Tücke</surname>
271
272           <email>sven-ola@gmx.de</email>
273         </author>
274
275         <author>
276           <firstname>Andreas</firstname>
277
278           <surname>Tønnesen</surname>
279
280           <email>andreto@olsr.org</email>
281         </author>
282       </authorgroup>
283     </refentryinfo>
284
285     <refmeta>
286       <refentrytitle id="olsrd_8-title">olsrd</refentrytitle>
287
288       <manvolnum>8</manvolnum>
289     </refmeta>
290
291     <refnamediv>
292       <refname>olsrd</refname>
293
294       <refpurpose>Optimized Link State Routing protocol daemon</refpurpose>
295     </refnamediv>
296
297     <refsynopsisdiv>
298       <para><cmdsynopsis>
299           <command>olsrd</command>
300
301           <group>
302             <arg>-h</arg>
303
304             <arg>--help</arg>
305           </group>
306
307           <group>
308             <arg>-v</arg>
309
310             <arg>--version</arg>
311           </group>
312
313           <group choice="req">
314             <arg>-f</arg>
315
316             <arg>--config</arg>
317
318             <replaceable>configfile</replaceable>
319           </group>
320
321           <group choice="req">
322             <arg>-d</arg>
323
324             <arg>--DebugLevel</arg>
325
326             <replaceable>level</replaceable>
327           </group>
328
329           <group>
330             <arg>-n</arg>
331
332             <arg>--nofork</arg>
333           </group>
334
335           <group>
336             <arg>-X</arg>
337
338             <arg>--dispin</arg>
339           </group>
340
341           <group>
342             <arg>-O</arg>
343
344             <arg>--dispout</arg>
345           </group>
346
347           <group>
348             <arg>-D</arg>
349
350             <arg>--delgw</arg>
351           </group>
352
353           <group>
354             <arg>-P</arg>
355
356             <arg>--ipc</arg>
357           </group>
358
359           <group choice="req">
360             <arg>-H</arg>
361
362             <arg>--hemu</arg>
363
364             <replaceable>ipaddr</replaceable>
365           </group>
366
367           <arg>interface1</arg>
368
369           <arg rep="repeat">interface2</arg>
370         </cmdsynopsis></para>
371
372       <para><emphasis role="strong">Note</emphasis>: Only if
373       <productname>olsrd</productname> is started without arguments, the
374       default config file is loaded - which is usually
375       <filename>/etc/olsrd.conf</filename> or
376       <filename>/usr/local/etc/olsrd.conf</filename>.</para>
377     </refsynopsisdiv>
378
379     <refsect1>
380       <title>Description</title>
381
382       <para>The <productname>olsrd</productname> daemon is an implementation
383       of the <emphasis>O</emphasis>ptimized <emphasis>L</emphasis>ink
384       <emphasis>S</emphasis>tate <emphasis>R</emphasis>outing protocol (OLSR)
385       for <emphasis>M</emphasis>obile <emphasis>A</emphasis>d-hoc
386       <emphasis>NET</emphasis>works (MANETs). The protocol is described in
387       RFC3626. It is designed to be run as a standalone server process - but
388       as it is still in an experimental stage most users will prefer running
389       it with some debug output.</para>
390
391       <para>This implementation of the OLSR protocol features an alternative
392       routing scheme based on link quality using an ETX-like metric which was
393       initially developed by the c-base community in Berlin and extended by
394       the Funkfeuer community in Vienna. This alternative routing scheme uses
395       non-standard messages and is therefore incompatible to standard OLSR as
396       it is described in the RFC. To switch back to RFC-mode, you need to
397       enable a (currently unavailable) metrics plugin using the
398       <option>LinkQualityAlgorithm</option> option (see <xref
399       endterm="olsrd_conf_5-title" linkend="olsrd_conf_5" />).</para>
400
401       <para>The home page of <productname>olsrd</productname> is <ulink
402       url="http://www.olsr.org">http://www.olsr.org</ulink></para>
403     </refsect1>
404
405     <refsect1>
406       <title>Getting Started</title>
407
408       <para>Running and maintaining a larger mesh network is a complex task.
409       Nevertheless, you may simply want to test
410       <productname>olsrd</productname>. If you have at least 3 devices, all
411       equipped with a WLAN card, the following short list of steps may
412       help.</para>
413
414       <orderedlist>
415         <listitem>
416           <para>Set up the necessary connectivity. Configure all WLAN cards to
417           Ad hoc (IBSS) or similar, use same ESSID and channel setting. All
418           WLAN cards need to use a fixed IP in the same IP address range (e.g.
419           10.0.0.0/8). Verify, that the interfaces are configured with the
420           correct broadcast address. Otherwise you will experience ARP lookups
421           on the broadcast address when running
422           <productname>olsrd</productname>. Also stop any firewalling and
423           enable forwarding. Test the connectivity by using the
424           <command>ping</command> command. Remember:
425           <productname>olsrd</productname> is a layer 3 routing daemon and
426           therefore simply is not responsible for any layer 2 problems. No
427           ping - no routes.</para>
428         </listitem>
429
430         <listitem>
431           <para>Install <productname>olsrd</productname> on every device. This
432           is different for several supported operating systems:</para>
433
434           <variablelist>
435             <varlistentry>
436               <term>Linux</term>
437
438               <listitem>
439                 <para>Download a stable source tar.gz. Unpack. Be sure to
440                 install the build tools (e.g. <command>apt-get install
441                 build-essential flex bison</command>). Do <command>make
442                 build_all</command>. Do <command>sudo make
443                 install_all</command>. Edit the
444                 <filename>/usr/local/etc/olsrd.conf</filename> file and change
445                 at least the <option>Interface</option> section for your WLAN
446                 card. You may also want to enable the httpinfo plugin. Start
447                 with <command>olsrd -f /usr/local/etc/olsrd.conf -d
448                 1</command>.</para>
449
450                 <para>You may add <option>PREFIX=/usr</option> to the
451                 <command>make</command> commands which changes the
452                 installation pathes to <filename>/etc</filename>,
453                 <filename>/usr/sbin</filename>, and
454                 <filename>/usr/lib</filename> as it is the default with
455                 previous <productname>olsrd</productname> versions.</para>
456               </listitem>
457             </varlistentry>
458
459             <varlistentry>
460               <term>Windows</term>
461
462               <listitem>
463                 <para>Download the Windows installer. Install and run the
464                 <filename>Switch.exe</filename> GUI as admin. Select the WLAN
465                 card and de-select any other interface offered. Click the
466                 <guibutton>Start</guibutton> button. Keep in mind: only a user
467                 with admin rights can change the routing table. Because a
468                 personal operating system is optimize to give you a maximum of
469                 security and convenience. As a consequence, it does not
470                 support cooperation too well. To cooperate, disable at least
471                 any active firewall solution on the WLAN card to enable
472                 forwarding for others. For security, disable all protocols and
473                 services for the WLAN card with the exception of basic
474                 TCP/IP.</para>
475               </listitem>
476             </varlistentry>
477
478             <varlistentry>
479               <term>BSD</term>
480
481               <listitem>
482                 <para>Basically use the same procedure as with Linux. You need
483                 to install and use the <command>gmake</command> command to
484                 build and install.</para>
485               </listitem>
486             </varlistentry>
487
488             <varlistentry>
489               <term>Embedded:</term>
490
491               <listitem>
492                 <para>Your mileage may vary with different embedded firmwares
493                 and operating systems. You may flash the Freifunk Firmware.
494                 DD-WRT has <productname>olsrd</productname> support. OpenWrt
495                 comes with a pre-compiled binary for
496                 <productname>olsrd</productname>. There is an ongoing
497                 OpenWrt/Kamikaze project with <productname>olsrd</productname>
498                 named ffluci. Installation and configuration is different for
499                 those Linux flavours - be sure to read their docs or online
500                 help files.</para>
501               </listitem>
502             </varlistentry>
503           </variablelist>
504         </listitem>
505
506         <listitem>
507           <para>If <productname>olsrd</productname> detects the correct
508           topology as well as installs/removes routes matching that topology,
509           you may offer Internet on one of your devices. Either enable a
510           manual <quote>HNA { 0.0.0.0 0.0.0.0 }</quote> in the configuration
511           file or use the dyn_gw or dyn_gw_plain plugins. For most Internet
512           connections, you need to enable NAT/MASQUERADING to translate the
513           private IP addresses to the globally valid IP address on the
514           Internet gateway device.</para>
515         </listitem>
516
517         <listitem>
518           <para>Start debugging if necessary. Use the <ulink
519           url="http://localhost:8080/">http://localhost:8080/</ulink> URL to
520           query information from the httpinfo plugin. Use
521           <command>wireshark</command> or <command>tcpdump -ni [iface] udp and
522           port 698</command> to verify OLSR messaging. Take special care for
523           the WLAN cards in Ad hoc / IBSS mode: typical driver/card
524           combinations tend to disagree about the auto-negotiated BSSID over
525           time (also called IBSS-split) which may be solved by using a
526           manually configured BSSID.</para>
527         </listitem>
528       </orderedlist>
529     </refsect1>
530
531     <refsect1>
532       <title>Options</title>
533
534       <para>You can specify options either on the command line or by using a
535       config file - usually <filename>/etc/olsrd.conf</filename> or
536       <filename>/usr/local/etc/olsrd.conf</filename>. The getopt parser
537       replaces the <option>--config</option> option with options acquired in
538       from the specified config file. While it is possible to operate using
539       only command line options, you may want a config file especially for
540       readability of the larger config options (e.g. <option>Interface { ...
541       }</option> or <option>LoadPlugin { ... }</option> option blocks). To
542       preset a config file setting, add an option before
543       <option>--config</option>. To overwrite a config file setting, add an
544       option after <option>--config</option>.</para>
545
546       <para>The following list summarizes options frequently specified on the
547       command line. If you use one or more command line options, you normally
548       also have to specify <option>--config</option> for the desired config
549       file.</para>
550
551       <variablelist>
552         <varlistentry>
553           <term><option>-h</option> or <option>--help</option></term>
554
555           <listitem>
556             <para>Prints out the list of valid command line / config file
557             options and exits.</para>
558           </listitem>
559         </varlistentry>
560
561         <varlistentry>
562           <term><option>-v</option> or <option>--version</option></term>
563
564           <listitem>
565             <para>Prints out the current version number and exits.</para>
566           </listitem>
567         </varlistentry>
568
569         <varlistentry>
570           <term><option>-f <replaceable>configfile</replaceable></option> or
571           <option>--config
572           <replaceable>configfile</replaceable></option></term>
573
574           <listitem>
575             <para>Reads in the specified config file. The acquired options are
576             inserted into the command line at the position of the
577             <option>-f</option> or <option>--config</option> option.</para>
578           </listitem>
579         </varlistentry>
580
581         <varlistentry>
582           <term><option>-d level</option> or <option>--DebugLevel
583           <replaceable>level</replaceable></option></term>
584
585           <listitem>
586             <para>Specifies the amount of debug information to be printed out
587             during operation. If set to 0, <productname>olsrd</productname>
588             will run in the background.</para>
589           </listitem>
590         </varlistentry>
591
592         <varlistentry>
593           <term><option>-n</option> or <option>--nofork</option></term>
594
595           <listitem>
596             <para>This option causes <productname>olsrd</productname> not to
597             fork into the background, even when started with
598             <option>--DebugLevel 0</option>.</para>
599           </listitem>
600         </varlistentry>
601
602         <varlistentry>
603           <term><option>-X</option> or <option>--dispin</option></term>
604
605           <listitem>
606             <para>This option causes <productname>olsrd</productname> to
607             display all incoming packet data.</para>
608           </listitem>
609         </varlistentry>
610
611         <varlistentry>
612           <term><option>-O</option> or <option>--dispout</option></term>
613
614           <listitem>
615             <para>This option causes <productname>olsrd</productname> to
616             display all outgoing packet data.</para>
617           </listitem>
618         </varlistentry>
619
620         <varlistentry>
621           <term><option>-D</option> or <option>--delgw</option></term>
622
623           <listitem>
624             <para>This option will remove a static default route when
625             <productname>olsrd</productname> adds an Internet route based on
626             OLSR routing.</para>
627           </listitem>
628         </varlistentry>
629
630         <varlistentry>
631           <term><option>-P</option> or <option>--ipc</option></term>
632
633           <listitem>
634             <para>This option allows the GUI front end to create one
635             connection to <productname>olsrd</productname> at runtime.</para>
636           </listitem>
637         </varlistentry>
638
639         <varlistentry>
640           <term><option>-i</option></term>
641
642           <listitem>
643             <para>Ignored for compatibility - older versions of
644             <productname>olsrd</productname> expect one or more interface
645             names after this option (see below).</para>
646           </listitem>
647         </varlistentry>
648
649         <varlistentry>
650           <term><option><replaceable>interface1</replaceable>
651           interface2...</option></term>
652
653           <listitem>
654             <para>Any character combination without a leading dash is
655             interpreted as a list of interfaces. The list specifies on what
656             network interfaces <productname>olsrd</productname> should run.
657             Only the main IP address of an interface is evaluated, so you
658             cannot specify an interface alias such as eth0:1. Note, that you
659             also cannot change the interface parameters such as intervals and
660             validity times. Use the <option>Interface { ... }</option> option
661             block instead.</para>
662           </listitem>
663         </varlistentry>
664       </variablelist>
665     </refsect1>
666
667     <refsect1>
668       <title>Files</title>
669
670       <simplelist type="vert">
671         <member><filename><?install-datadir ?>/etc/olsrd.conf</filename></member>
672       </simplelist>
673     </refsect1>
674
675     <refsect1>
676       <title>See Also</title>
677
678       <simplelist type="inline">
679         <member><xref endterm="olsrd_conf_5-title" linkend="olsrd_conf_5" />
680         <xref endterm="olsrd_metrics_3-title"
681         linkend="olsrd_metrics_3" /></member>
682       </simplelist>
683     </refsect1>
684   </refentry>
685
686   <refentry id="olsrd_conf_5">
687     <indexterm>
688       <primary><filename>olsrd.conf</filename></primary>
689     </indexterm>
690
691     <refentryinfo>
692       <titleabbrev>Configuration File for
693       <productname>olsrd</productname></titleabbrev>
694
695       <authorgroup>
696         <author>
697           <firstname>Sven-Ola</firstname>
698
699           <surname>Tücke</surname>
700
701           <email>sven-ola@gmx.de</email>
702         </author>
703
704         <author>
705           <firstname>Andreas</firstname>
706
707           <surname>Tønnesen</surname>
708
709           <email>andreto@olsr.org</email>
710         </author>
711       </authorgroup>
712     </refentryinfo>
713
714     <refmeta>
715       <refentrytitle id="olsrd_conf_5-title">olsrd.conf</refentrytitle>
716
717       <manvolnum>5</manvolnum>
718     </refmeta>
719
720     <refnamediv>
721       <refname><filename>olsrd.conf</filename></refname>
722
723       <refpurpose>configuration file for <xref endterm="olsrd_8-title"
724       linkend="olsrd_8" /></refpurpose>
725     </refnamediv>
726
727     <refsect1>
728       <title>Description</title>
729
730       <para>The <filename>olsrd.conf</filename> file is located in /etc or
731       /usr/local/etc by default. The file contains run-time configuration
732       settings for the Optimized Link State Routing daemon <xref
733       endterm="olsrd_8-title" linkend="olsrd_8" />. During startup, the
734       <productname>olsrd</productname> daemon reads in the file. If no command
735       line options are present, the default configuration file is read in.
736       Otherwise, the file specified by the <option>-f</option> or
737       <option>--config</option> command line option is used. All settings are
738       inserted as command line options by prepending a double dash and feeding
739       them to the getopt parser. The configuration file consists of comments,
740       single options and option blocks explained below.</para>
741
742       <para><emphasis role="strong">Note</emphasis>: With earlier versions of
743       <productname>olsrd</productname>, the configuration parser was offered
744       as stand alone shared library or DLL. With the exception of the Windows
745       GUI program (<command>Switch.exe</command>), this was unused. To
746       optimize the file size for embedded devices, the stand-alone
747       configuration parser was discarded.</para>
748     </refsect1>
749
750     <refsect1>
751       <title>Comments</title>
752
753       <para>Comments are everything following a hash character
754       (<emphasis>#</emphasis>) on a line. This data is discarded. Commenting
755       out an option is an easy way to make <productname>olsrd</productname>
756       use the default value for that option.</para>
757     </refsect1>
758
759     <refsect1>
760       <title>Option Syntax</title>
761
762       <para>An option starts with a keyword. If the option accepts arguments,
763       separate the keyword and the arguments with one or more space characters
764       (or tabs) on the same line. You can surround arguments with double or
765       single quotes, for example if an argument contains a space
766       character.</para>
767     </refsect1>
768
769     <refsect1>
770       <title>Single Options</title>
771
772       <para><emphasis role="strong">Caution</emphasis>: The current
773       implementation discards several single options controlling the Link
774       Quality Extensions valid with earlier versions. If you want the
775       RFC-compatible mode, load the <filename>olsrd_lq_rfc.so.1</filename>
776       plugin (see <xref endterm="olsrd_conf_5_plugins-title"
777       linkend="olsrd_conf_5_plugins" />). If you want to use another LQ
778       measurement than the compiled in
779       <filename>olsrd_lq_etx_ff.so.1</filename>, consider one of the other LQ
780       plugins (also see <xref endterm="olsrd_conf_5_plugins-title"
781       linkend="olsrd_conf_5_plugins" />). Discarded options:
782       <option>UseHysteresis</option>, <option>HystScaling</option>,
783       <option>HystThrHigh</option>, <option>HystThrLow</option>,
784       <option>LinkQualityLevel</option>, <option>LinkQualityWinsize</option>,
785       <option>LinkQualityAlgorithm</option> and
786       <option>LinkQualityAging</option>.</para>
787
788       <para>Single options consists of a keyword and a value. Note, that a
789       comment can follow such a option on the same line. Valid single options
790       are:</para>
791
792       <variablelist>
793         <varlistentry>
794           <term><option>config</option>
795           <replaceable>configfile</replaceable></term>
796
797           <listitem>
798             <para>Nesting within config files is not supported. Do not
799             use.</para>
800           </listitem>
801         </varlistentry>
802
803         <varlistentry>
804           <term><option>delgw</option>, <option>dispin</option>,
805           <option>dispout</option>, <option>help</option>,
806           <option>hemu</option>, <option>iface</option>, <option>ipc</option>,
807           <option>nofork</option>, <option>version</option>:</term>
808
809           <listitem>
810             <para>While these are valid options, they do not make much sense
811             in a config file. Refer to <xref endterm="olsrd_8-title"
812             linkend="olsrd_8" /> for their meaning.</para>
813           </listitem>
814         </varlistentry>
815
816         <varlistentry>
817           <term><option>AllowNoInt</option>
818           <replaceable>yes</replaceable>|<replaceable>no</replaceable></term>
819
820           <listitem>
821             <para><productname>olsrd</productname> supports dynamic
822             configuration of network interfaces. This means that interfaces on
823             which <productname>olsrd</productname> runs on can be reconfigured
824             and <productname>olsrd</productname> will update itself with no
825             need to be restarted. <productname>olsrd</productname> also
826             supports removal and addition of interfaces in run-time. This
827             option specifies that <productname>olsrd</productname> should keep
828             running if no network interfaces are available. Defaults to
829             <replaceable>yes</replaceable>.</para>
830           </listitem>
831         </varlistentry>
832
833         <varlistentry>
834           <term><option>ClearScreen</option>
835           <replaceable>yes</replaceable>|<replaceable>no</replaceable></term>
836
837           <listitem>
838             <para>If set to <replaceable>yes</replaceable> and
839             <productname>olsrd</productname> running with a
840             <option>DebugLevel</option> other that
841             <replaceable>0</replaceable>, the terminal to which output is sent
842             (STDOUT) is cleared prior to writing updated tables. This makes it
843             easier to follow changes in real-time.</para>
844           </listitem>
845         </varlistentry>
846
847         <varlistentry>
848           <term><option>DebugLevel</option>
849           <replaceable>0</replaceable>-<replaceable>9</replaceable></term>
850
851           <listitem>
852             <para>Controls the amount of debug output
853             <productname>olsrd</productname> prints out. If set to
854             <replaceable>0</replaceable>, <productname>olsrd</productname>
855             will detach from the current process and run in the background. A
856             value of <replaceable>9</replaceable> yields a maximum of debug
857             output. Defaults to <replaceable>0</replaceable>.</para>
858           </listitem>
859         </varlistentry>
860
861         <varlistentry>
862           <term><option>FIBMetric</option>
863           <replaceable>flat</replaceable>|<replaceable>correct</replaceable>|<replaceable>approx</replaceable></term>
864
865           <listitem>
866             <para>This setting controls how the metric value for kernel routes
867             is handled. While analyzing new information of the mesh topology,
868             <productname>olsrd</productname> may change the internal routing
869             path to several distant nodes (in hops). If this setting is set to
870             <replaceable>flat</replaceable>, kernel routes always have a
871             metric of 2. No route update is necessary if the internal routing
872             pathes change. If this setting is set to
873             <replaceable>correct</replaceable>, the kernel metric shows the
874             number of hops to the destination. This induces frequent routing
875             changes in larger meshes. If this setting is set to
876             <replaceable>approx</replaceable>, the current hop number is set
877             as a route metric but not updated if
878             <productname>olsrd</productname> detects a hop number change.
879             Defaults to <replaceable>flat</replaceable>.</para>
880           </listitem>
881         </varlistentry>
882
883         <varlistentry>
884           <term><option>IpVersion</option>
885           <replaceable>4</replaceable>|<replaceable>6</replaceable></term>
886
887           <listitem>
888             <para><productname>olsrd</productname> supports both IP versions:
889             <replaceable>4</replaceable> and <replaceable>6</replaceable>.
890             This option controls what IP version
891             <productname>olsrd</productname> uses. Defaults to
892             <replaceable>4</replaceable>.</para>
893           </listitem>
894         </varlistentry>
895
896         <varlistentry>
897           <term><option>LinkQualityDijkstraLimit</option>
898           <replaceable>0</replaceable>|<replaceable>255</replaceable>
899           <replaceable>[Pollrate]</replaceable>-<replaceable>120.0</replaceable></term>
900
901           <listitem>
902             <para>This setting configures a calculation optimization which may
903             be necessary for large meshes with slow nodes (e.g. 100 MHz ARM
904             CPU). Normally, an incoming TC message triggers a re-calculation
905             of the internal network model. This setting can be used switch to
906             a regularly calculation (first value set to
907             <replaceable>0</replaceable>) and to use a specific calculation
908             interval in seconds (second value larger then
909             <replaceable>[Pollrate]</replaceable>). Note, that infrequent
910             re-calculation may introduce routing loops because nodes need more
911             time to adapt their routing tables. Defaults to
912             <replaceable>255</replaceable> <replaceable>0.0</replaceable>
913             (inactive).</para>
914           </listitem>
915         </varlistentry>
916
917         <varlistentry>
918           <term><option>LinkQualityFishEye</option>
919           <replaceable>0</replaceable>|<replaceable>1</replaceable></term>
920
921           <listitem>
922             <para>Enables (<replaceable>1</replaceable>) or disables
923             (<replaceable>0</replaceable>) the experimental fish eye
924             algorithm. In mesh network with high packet loss, the topology
925             information does not spread fast and synchronized, which
926             introduces routing loops. The fish eye algorithm will send TC
927             (Topology Control) messages with varying TTL values. Which floods
928             the near neighborhood more often with topology information than
929             distant nodes (in hops). Use this option together with a shorter
930             <option>TcInterval</option> and a higher
931             <option>MprCoverage</option> setting.</para>
932           </listitem>
933         </varlistentry>
934
935         <varlistentry>
936           <term><option>MprCoverage</option> <replaceable>1</replaceable> or
937           higher</term>
938
939           <listitem>
940             <para>This value decides, how many MPRs a node should attempt to
941             select for every two hop neighbor. Defaults to
942             <emphasis><replaceable>1</replaceable></emphasis>, and any other
943             setting will severely reduce the optimization introduced by the
944             MPR scheme. Note, that when using the
945             <option>LinkQualityFishEye</option> option, a higher value is
946             recommended.</para>
947           </listitem>
948         </varlistentry>
949
950         <varlistentry>
951           <term><option>NatThreshold</option>
952           <replaceable>0.1</replaceable>-<replaceable>1.0</replaceable></term>
953
954           <listitem>
955             <para>In a large mesh network, several gateways may announce HNA
956             0/0 which basically says <quote>Internet here</quote>. Because
957             most Internet gateways offer their service using a translated
958             globally valid IP (NAT), switching the current gateway terminates
959             all running NATted connections. In other words: if you live
960             between 2 Internet gateways and start download, the download may
961             block some OLSR packets. The download will stop because this
962             triggers a route change - especially if you do not use traffic
963             shaping to prioritize OLSR packets. This setting introduces a
964             threshold to stop switching the default gateway on minor LQ/ETX
965             changes if another (NATted) gateway is to be used. As a trade off,
966             this may introduce routing loops or selects a bad gateway if the
967             threshold is too low. Defaults to <replaceable>1.0</replaceable>
968             (inactive).</para>
969           </listitem>
970         </varlistentry>
971
972         <varlistentry>
973           <term><option>NicChgsPollInt</option>
974           <replaceable>0.1</replaceable>-<replaceable>100.0</replaceable></term>
975
976           <listitem>
977             <para>This option sets the interval, in seconds, that
978             <productname>olsrd</productname> will check the configured
979             interfaces for changes in configuration. Defaults to
980             <replaceable>2.5</replaceable>.</para>
981           </listitem>
982         </varlistentry>
983
984         <varlistentry>
985           <term><option>Pollrate</option>
986           <replaceable>0.1</replaceable>-<replaceable>10.0</replaceable></term>
987
988           <listitem>
989             <para>This option sets the sleep interval, in seconds. While
990             polling the interfaces, the <productname>olsrd</productname>
991             scheduler will sleep for this time if no packets are to be
992             received. If the value is set too high for the current UDP receive
993             buffer size, packet loss will occur. Note, that the current
994             <productname>olsrd</productname> implementation internally
995             calculates timing values in milliseconds (1/1000s). Defaults to
996             <replaceable>0.1</replaceable>.</para>
997           </listitem>
998         </varlistentry>
999
1000         <varlistentry>
1001           <term><option>RtProto</option>
1002           <replaceable>0</replaceable>|<replaceable>1</replaceable>-<replaceable>255</replaceable></term>
1003
1004           <listitem>
1005             <para>This setting configures the routing protocol ID to be used
1006             when setting routes via rtnetlink, see RTNETLINK(7) for the
1007             <emphasis>rtm_protocol</emphasis> keyword. Use
1008             <replaceable>0</replaceable> to specify the operating system
1009             default, e.g. RTPROT_BOOT on Linux). Defaults to
1010             <replaceable>0</replaceable>.</para>
1011           </listitem>
1012         </varlistentry>
1013
1014         <varlistentry>
1015           <term><option>RtTableDefault</option>
1016           <replaceable>0</replaceable>|<replaceable>1</replaceable>-<replaceable>254</replaceable></term>
1017
1018           <listitem>
1019             <para>Defines the routing table for inserting a new default route.
1020             Defaults to <replaceable>0</replaceable> (use
1021             <option>RtTable</option>)</para>
1022           </listitem>
1023         </varlistentry>
1024
1025         <varlistentry>
1026           <term><option>RtTable</option>
1027           <replaceable>1</replaceable>-<replaceable>254</replaceable></term>
1028
1029           <listitem>
1030             <para>With Linux and BSD, more than one routing table exist in the
1031             system. Together with a rules set that determines which table
1032             handles what packets, these system functions are called
1033             <quote>iproute2</quote> or <quote>Policy Routing</quote>. You may
1034             want to read the <ulink url="http://lartc.org/">Linux Advanced
1035             Routing &amp; Traffic Control</ulink> for details. Defaults to
1036             <replaceable>254</replaceable> (or <quote>main</quote>, see
1037             <filename>/etc/iproute2/rt_tables</filename>)</para>
1038           </listitem>
1039         </varlistentry>
1040
1041         <varlistentry>
1042           <term><option>TcRedundancy</option>
1043           <replaceable>0</replaceable>|<replaceable>1</replaceable>|<replaceable>2</replaceable></term>
1044
1045           <listitem>
1046             <para>This value controls the TC redundancy used by the local node
1047             in TC message generation. To enable a more robust understanding of
1048             the topology, nodes can be set to announce more than just their
1049             MPR selector set in TC messages. If set to
1050             <replaceable>0</replaceable>, the advertised link set of the node
1051             is limited to the MPR selectors. If set to
1052             <replaceable>1</replaceable>, the advertised link set of the node
1053             is the union of its MPR set and its MPR selector set. If set to
1054             <replaceable>2</replaceable>, the advertised link set of the node
1055             is the full symmetric neighbor set of the node. Defaults to
1056             <replaceable>0</replaceable>.</para>
1057           </listitem>
1058         </varlistentry>
1059
1060         <varlistentry>
1061           <term><option>TosValue</option>
1062           <replaceable>0</replaceable>-<replaceable>16</replaceable></term>
1063
1064           <listitem>
1065             <para>This value controls the type of service value to set in the
1066             IP header of OLSR control traffic. Defaults to
1067             <replaceable>16</replaceable>.</para>
1068           </listitem>
1069         </varlistentry>
1070
1071         <varlistentry>
1072           <term><option>Willingness</option>
1073           <replaceable>0</replaceable>-<replaceable>7</replaceable></term>
1074
1075           <listitem>
1076             <para>Nodes participating in an OLSR routed network will announce
1077             their willingness to act as relays for OLSR control traffic for
1078             their neighbors (MPR). This option specifies a fixed willingness
1079             value to be announced by the local node.
1080             <replaceable>4</replaceable> is a neutral option here, while
1081             <replaceable>0</replaceable> specifies that this node will never
1082             act as a relay, and <replaceable>7</replaceable> specifies that
1083             this node will always act as such a relay. If this option is unset
1084             in the configuration file, then <productname>olsrd</productname>
1085             will try to retrieve information about the system power and
1086             dynamically update willingness according to this info. If no such
1087             info can be retrieved willingness is set to
1088             <replaceable>4</replaceable>.</para>
1089           </listitem>
1090         </varlistentry>
1091       </variablelist>
1092     </refsect1>
1093
1094     <refsect1 id="olsrd_conf_5_optionblocks">
1095       <title id="olsrd_conf_5_optionblocks-title">Option Blocks</title>
1096
1097       <para>Option blocks are configuration options that holds a body of
1098       sub-options encapsulated in curled braces <quote>{...}</quote>. Note,
1099       that you need to separate the keyword and the starting brace with one or
1100       more whitespace characters (spaces, tabs, or newlines). Also separate
1101       sub-options as well as the closing brace with additional whitespace
1102       characters. Valid options are:</para>
1103
1104       <variablelist>
1105         <varlistentry>
1106           <term><option>IpcConnect { <replaceable>sub-options</replaceable>
1107           }</option></term>
1108
1109           <listitem>
1110             <para><productname>olsrd</productname> can allow processes to make
1111             a TCP connection to itself on which data regarding the topology
1112             will be transmitted. This is typically used by GUI applications to
1113             provide a user-friendly front-end to
1114             <productname>olsrd</productname>. This option block controls the
1115             IPC access. Sub options are:</para>
1116
1117             <variablelist>
1118               <varlistentry>
1119                 <term><option>MaxConnections</option>
1120                 <replaceable>0</replaceable>-<replaceable>5</replaceable></term>
1121
1122                 <listitem>
1123                   <para>This option specifies how many connections that can
1124                   exist simultaneously. Multiple connections have not been
1125                   tested, and probably do not work! This option should only be
1126                   used to control whether or not processes can connect to
1127                   <productname>olsrd</productname> by setting it either to
1128                   <replaceable>0</replaceable>, which will tell
1129                   <productname>olsrd</productname> not to allow any
1130                   connections, or by setting it to a positive value. Defaults
1131                   to <replaceable>0</replaceable>.</para>
1132                 </listitem>
1133               </varlistentry>
1134
1135               <varlistentry>
1136                 <term><option>Host</option>
1137                 <replaceable>ipaddr</replaceable></term>
1138
1139                 <listitem>
1140                   <para>This option specifies a single host that is allowed to
1141                   connect to <productname>olsrd</productname>. By default only
1142                   the loopback address (127.0.0.1) is allowed to access. If
1143                   you want to be able to connect from another host, you should
1144                   add that IP address. You may add multiple hosts.</para>
1145                 </listitem>
1146               </varlistentry>
1147
1148               <varlistentry>
1149                 <term><option>Net</option> <replaceable>ipaddr</replaceable>
1150                 <replaceable>netmask</replaceable>|<replaceable>prefix</replaceable></term>
1151
1152                 <listitem>
1153                   <para>You can specify a net range of IP addresses which
1154                   <productname>olsrd</productname> will allow TCP connections
1155                   from. Besides the IP address, you need to specify a netmask
1156                   for IPv4 and a prefix for IPv6. You may add multiple
1157                   networks.</para>
1158                 </listitem>
1159               </varlistentry>
1160             </variablelist>
1161           </listitem>
1162         </varlistentry>
1163
1164         <varlistentry>
1165           <term><option>Hna4 { <replaceable>sub-options</replaceable>
1166           }</option></term>
1167
1168           <listitem>
1169             <para>Hosts in a routed network can announce connectivity to
1170             external networks or hosts using HNA messages. This option block
1171             is used to set the IPv4 networks or hosts to be announced. Sub
1172             options are:</para>
1173
1174             <variablelist>
1175               <varlistentry>
1176                 <term><replaceable>IPv4-address</replaceable>
1177                 <replaceable>IPv4-netmask</replaceable></term>
1178
1179                 <listitem>
1180                   <para>Specifies an IPv4 network or host to be announced via
1181                   HNA messages. Multiple entries can be added. To announce
1182                   Internet connectivity, add
1183                   <replaceable>0.0.0.0</replaceable>
1184                   <replaceable>0.0.0.0</replaceable>. To announce a single
1185                   host, add <replaceable>ipaddr</replaceable>
1186                   <replaceable>255.255.255.255</replaceable>.</para>
1187                 </listitem>
1188               </varlistentry>
1189             </variablelist>
1190           </listitem>
1191         </varlistentry>
1192
1193         <varlistentry>
1194           <term><option>Hna6 { <replaceable>sub-options</replaceable>
1195           }</option></term>
1196
1197           <listitem>
1198             <para>Hosts in a routed network can announce connectivity to
1199             external networks or hosts using HNA messages. This option block
1200             is used to set the IPv6 networks or hosts to be announced. Sub
1201             options are:</para>
1202
1203             <variablelist>
1204               <varlistentry>
1205                 <term><replaceable>IPv6-address</replaceable> 0-128</term>
1206
1207                 <listitem>
1208                   <para>Specifies an IPv6 network or host to be announced via
1209                   HNA messages. Multiple entries can be added. To announce
1210                   Internet connectivity, add <replaceable>::</replaceable>
1211                   <replaceable>0</replaceable> . To announce a single host,
1212                   add <replaceable>ipaddr</replaceable>
1213                   <replaceable>128</replaceable>.</para>
1214                 </listitem>
1215               </varlistentry>
1216             </variablelist>
1217           </listitem>
1218         </varlistentry>
1219
1220         <varlistentry>
1221           <term><option>LoadPlugin <replaceable>plugin-filename</replaceable>
1222           { <replaceable>sub-options</replaceable> }</option></term>
1223
1224           <listitem>
1225             <para>Specifies a plugin that <productname>olsrd</productname>
1226             should load at startup. You need to specify the filename for the
1227             shared object file (<filename>*.so</filename> on Linux and
1228             <filename>*.dll</filename> on Windows). Read the
1229             <filename>README</filename> in the plugin's source directory or
1230             refer the <xref endterm="olsrd_conf_5_plugins-title"
1231             linkend="olsrd_conf_5_plugins" /> section below. This option block
1232             can be repeated to add multiple plugins. Sub options are:</para>
1233
1234             <variablelist>
1235               <varlistentry>
1236                 <term><option>PlParam</option> <replaceable>key</replaceable>
1237                 <replaceable>value</replaceable></term>
1238
1239                 <listitem>
1240                   <para>Sends a pair of parameters to the plugin at
1241                   initialization. The parameter's
1242                   <replaceable>key</replaceable> is case insensitive. Refer to
1243                   the <xref endterm="olsrd_conf_5_plugins-title"
1244                   linkend="olsrd_conf_5_plugins" /> section below or consult
1245                   individual plugin documentation for possible
1246                   parameters.</para>
1247                 </listitem>
1248               </varlistentry>
1249             </variablelist>
1250           </listitem>
1251         </varlistentry>
1252
1253         <varlistentry>
1254           <term><option>Interface <replaceable>interface1</replaceable>
1255           <replaceable>interface2...</replaceable> {
1256           <replaceable>sub-options</replaceable> }</option></term>
1257
1258           <listitem>
1259             <para>This option block specifies one or more network interfaces
1260             on which <productname>olsrd</productname> should run. At least one
1261             network interface block must be specified for
1262             <productname>olsrd</productname> to run. Various parameters can be
1263             specified on individual interfaces or groups of interfaces. This
1264             option block can be repeated to add multiple interface
1265             configurations. Sub options are:</para>
1266
1267             <variablelist>
1268               <varlistentry>
1269                 <term><option>AutoDetectChanges</option>
1270                 <replaceable>yes</replaceable>|<replaceable>no</replaceable></term>
1271
1272                 <listitem>
1273                   <para><productname>olsrd</productname> can auto detect
1274                   changes in interface configurations by polling on the
1275                   interval set by <option>NicChgsPollInt</option>. This is
1276                   enabled by default but can be turned off per interface to
1277                   save CPU cycles.</para>
1278                 </listitem>
1279               </varlistentry>
1280
1281               <varlistentry>
1282                 <term><option>Ip4Broadcast</option>
1283                 <replaceable>IPv4-address</replaceable></term>
1284
1285                 <listitem>
1286                   <para>Forces the given IPv4 broadcast address to be used as
1287                   destination address for all outgoing OLSR traffic on the
1288                   interface. If your mesh uses several IP address ranges, the
1289                   global broadcast address
1290                   <replaceable>255.255.255.255</replaceable> can be used. If
1291                   you use a point-to-point link (e.g. a tun-type VPN tunnel),
1292                   you may configure the neighbours IP address. If this option
1293                   is unset, the broadcast address of the interface will be
1294                   used. In this case, the broadcast address will be updated
1295                   during run-time if a change is detected.</para>
1296                 </listitem>
1297               </varlistentry>
1298
1299               <varlistentry>
1300                 <term><option>Ip6AddrType</option>
1301                 <replaceable>site-local</replaceable>|<replaceable>unique-local</replaceable>|<replaceable>global</replaceable></term>
1302
1303                 <listitem>
1304                   <para>This option sets the IPv6 address type to be used for
1305                   interface address detection. Defaults to
1306                   <replaceable>site-local</replaceable>.</para>
1307                 </listitem>
1308               </varlistentry>
1309
1310               <varlistentry>
1311                 <term><option>Ip6MulticastSite</option>
1312                 <replaceable>IPv6-address</replaceable></term>
1313
1314                 <listitem>
1315                   <para>If <option>Ip6AddrType</option> is set to
1316                   <replaceable>site-local</replaceable>, this setting forces
1317                   the given IPv6 broadcast address to be used as destination
1318                   address for all outgoing OLSR traffic on the interface.
1319                   .</para>
1320                 </listitem>
1321               </varlistentry>
1322
1323               <varlistentry>
1324                 <term><option>Ip6MulticastGlobal</option>
1325                 <replaceable>IPv6-address</replaceable></term>
1326
1327                 <listitem>
1328                   <para>If <option>Ip6AddrType</option> is set to
1329                   <replaceable>global</replaceable>, this setting forces the
1330                   given IPv6 broadcast address to be used as destination
1331                   address for all outgoing OLSR traffic on the interface.
1332                   .</para>
1333                 </listitem>
1334               </varlistentry>
1335
1336               <varlistentry>
1337                 <term><option>HelloInterval</option>
1338                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1339
1340                 <listitem>
1341                   <para>Sets the interval on which HELLO (RFC-mode) or
1342                   LQ_HELLO (LQ/ETX-mode) messages will be generated and
1343                   transmitted on the interface. Note, that HELLO messages are
1344                   used to detect neighbours and determine symmetric
1345                   (bi-directional) links. These messages also include the
1346                   current neighbour information and always have a TTL of 1
1347                   which prevents any forwarding.</para>
1348                 </listitem>
1349               </varlistentry>
1350
1351               <varlistentry>
1352                 <term><option>HelloValidityTime</option>
1353                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1354
1355                 <listitem>
1356                   <para>Sets the validity time to be announced in HELLO or
1357                   LQ_HELLO messages transmitted on the interface. This value
1358                   must be larger than <option>HelloInterval</option>.</para>
1359                 </listitem>
1360               </varlistentry>
1361
1362               <varlistentry>
1363                 <term><option>TcInterval</option>
1364                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1365
1366                 <listitem>
1367                   <para>Sets the interval on which TC (RFC-mode) or LQ_TC
1368                   (LQ/ETX-mode) messages will be generated and transmitted on
1369                   the interface. Note, that TC (Topology Control) messages are
1370                   used to spread topology information. These messages also
1371                   include the current neighbour information and normally have
1372                   a TTL larger than 1 to flood them through the mesh network.
1373                   TC or LQ_TC messages may be forwarded delayed to support
1374                   packet aggregation. If the
1375                   <option>LinkQualityFishEye</option> option is enabled, the
1376                   TTL for these messages is varied to faster distribute
1377                   topology information in the near neighbourhood.</para>
1378                 </listitem>
1379               </varlistentry>
1380
1381               <varlistentry>
1382                 <term><option>TcValidityTime</option>
1383                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1384
1385                 <listitem>
1386                   <para>Sets the validity time to be announced in TC or LQ_TC
1387                   messages transmitted on the interface. This value must be
1388                   larger than <option>TcInterval</option>.</para>
1389                 </listitem>
1390               </varlistentry>
1391
1392               <varlistentry>
1393                 <term><option>MidInterval</option>
1394                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1395
1396                 <listitem>
1397                   <para>Sets the interval on which MID messages will be
1398                   generated and transmitted on the interface. Note, that MID
1399                   messages spread alias information and will be emitted only
1400                   by nodes with more than one <productname>olsrd</productname>
1401                   interface.</para>
1402                 </listitem>
1403               </varlistentry>
1404
1405               <varlistentry>
1406                 <term><option>MidValidityTime</option>
1407                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1408
1409                 <listitem>
1410                   <para>Sets the validity time to be announced in MID messages
1411                   transmitted on the interface. This value must be larger than
1412                   <option>MidInterval</option>.</para>
1413                 </listitem>
1414               </varlistentry>
1415
1416               <varlistentry>
1417                 <term><option>HnaInterval</option>
1418                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1419
1420                 <listitem>
1421                   <para>Sets the interval on which HNA messages will be
1422                   generated and transmitted on the interface. Note, that HNA
1423                   messages spread gateway information and will be emitted only
1424                   by nodes with configured <option>Hna4</option> or
1425                   <option>Hna6</option> options.</para>
1426                 </listitem>
1427               </varlistentry>
1428
1429               <varlistentry>
1430                 <term><option>HnaValidityTime</option>
1431                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1432
1433                 <listitem>
1434                   <para>Sets the validity time to be announced in HNA messages
1435                   transmitted on the interface. This value must be larger than
1436                   <option>HnaInterval</option>.</para>
1437                 </listitem>
1438               </varlistentry>
1439
1440               <varlistentry>
1441                 <term><option>Weight</option>
1442                 <replaceable>0</replaceable>-<replaceable>[maxint]</replaceable></term>
1443
1444                 <listitem>
1445                   <para>When multiple links exist between hosts, the
1446                   <emphasis>weight</emphasis> of the interface is used to
1447                   determine the link to route by. Normally the
1448                   <emphasis>weight</emphasis> is automatically calculated by
1449                   <productname>olsrd</productname> based on the
1450                   characteristics of the interface, but here you can specify a
1451                   fixed value. <productname>olsrd</productname> will choose
1452                   links with the lowest <emphasis>weight</emphasis>
1453                   value.</para>
1454                 </listitem>
1455               </varlistentry>
1456
1457               <varlistentry>
1458                 <term><option>LinkQualityMult</option>
1459                 <replaceable>default</replaceable>|<replaceable>neighbour-ipaddr</replaceable>
1460                 <replaceable>0.1</replaceable>-<replaceable>1.0</replaceable></term>
1461
1462                 <listitem>
1463                   <para>When using <productname>olsrd</productname> in
1464                   LQ/ETX-mode, the neighbour link cost is calculated based on
1465                   packet loss or hello message loss (see
1466                   <option>LinkQualityAlgorithm</option> option). Because the
1467                   applied measurement may not reflect the real-live connection
1468                   quality and link speed, this setting allows you to manually
1469                   fine-tune the measurement results. You can add one or more
1470                   <option>LinkQualityMult</option> options and correlate the
1471                   IP address of a neighbour with a multiplication factor. This
1472                   setting only allows you to determine bad links, e.g. a
1473                   factor of <replaceable>0.5</replaceable> basically says:
1474                   <quote>this link is only half as good as the packet loss may
1475                   indicate</quote>. For this reason, the
1476                   <replaceable>default</replaceable> keyword can be used to
1477                   lower all ETX/LQ values with a lower factor. You then define
1478                   better links by adding further entries with known IP
1479                   addresses and a higher factor.</para>
1480
1481                   <para><emphasis role="strong">Note</emphasis>: While
1482                   switching routes generally is not harmful, people tend to
1483                   fiddle with the <option>LinkQualityMult</option> setting
1484                   only because their automatically selected Internet gateway
1485                   flaps. This is a bad habit, because it disturbs the ETX/LQ
1486                   measurement and leads to sub-optimal routes for others. Try
1487                   using the <option>NatThreshold</option> option instead.
1488                   Another option is manual gateway selection either by
1489                   automatic tunneling or by using a VPN technique.</para>
1490                 </listitem>
1491               </varlistentry>
1492             </variablelist>
1493           </listitem>
1494         </varlistentry>
1495       </variablelist>
1496     </refsect1>
1497
1498     <refsect1 id="olsrd_conf_5_plugins">
1499       <title id="olsrd_conf_5_plugins-title">Plugins</title>
1500
1501       <para>The functionality of the <productname>olsrd</productname> daemon
1502       is extendable by plugins. Plugins are shared object files
1503       (<filename>*.so</filename> on Linux or <filename>*.dll</filename> on
1504       Windows) to be loaded from <productname>olsrd</productname> during
1505       startup. To load a plugin, add the appropriate
1506       <option>LoadPlugin</option> option to the config file (see <xref
1507       endterm="olsrd_conf_5_optionblocks-title"
1508       linkend="olsrd_conf_5_optionblocks" /> above). A plugin accepts zero or
1509       more parameters, which can be added by <option>PlParam</option>
1510       <replaceable>key</replaceable> <replaceable>value</replaceable>
1511       statements to the <option>LoadPlugin</option> option block. The
1512       following plugin are included with the current
1513       <productname>olsrd</productname> installation:</para>
1514
1515       <variablelist>
1516         <varlistentry>
1517           <term><option>LoadPlugin arprefresh.so.0.1 {
1518           <replaceable>...</replaceable> }</option></term>
1519
1520           <listitem>
1521             <para>This plugin refreshes the local ARP cache from received OLSR
1522             messages. This optimizes the ARP lookups otherwise required if
1523             unicast traffic is send on a previously unused link chain. The
1524             correct function requires Linux kernel 2.6. The plugin accepts no
1525             parameters.</para>
1526           </listitem>
1527         </varlistentry>
1528
1529         <varlistentry>
1530           <term><option>LoadPlugin olsrd_bmf.so.1.5.3 {
1531           <replaceable>...</replaceable> }</option></term>
1532
1533           <listitem>
1534             <para>This plugin floods IP-multicast and optional IP-broadcast
1535             traffic via the MPR chain. The multicast or broadcast traffic is
1536             grabbed from a non-OLSR interface, forwarded through the mesh and
1537             exits to another non-OLSR interface. Note, that this plugin
1538             requires multi-threading support. Also note, that this plugin has
1539             a separate source repository on <ulink
1540             url="http://olsr-bmf.sourceforge.net/">http://olsr-bmf.sourceforge.net/</ulink>
1541             . The plugin accepts the following parameters.</para>
1542
1543             <variablelist>
1544               <varlistentry>
1545                 <term><option>PlParam</option> NonOlsrIf
1546                 <replaceable>interface</replaceable></term>
1547
1548                 <listitem>
1549                   <para>As a special feature, it is possible to also forward
1550                   from and to non-OLSR interfaces. If you have network
1551                   interfaces on which <productname>olsrd</productname> is not
1552                   running, but you do want to forward multicast and
1553                   local-broadcast IP packets, specify up to 32
1554                   <option>NonOlsrIf</option> sub-options.</para>
1555                 </listitem>
1556               </varlistentry>
1557
1558               <varlistentry>
1559                 <term><option>PlParam</option> DoLocalBroadcast
1560                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
1561
1562                 <listitem>
1563                   <para>Enable or disable the flooding of local broadcast
1564                   packets (e.g. packets with IP destination 192.168.1.255).
1565                   Defaults to <replaceable>yes</replaceable>.</para>
1566                 </listitem>
1567               </varlistentry>
1568
1569               <varlistentry>
1570                 <term><option>PlParam</option> BmfInterface
1571                 <replaceable>interface</replaceable></term>
1572
1573                 <listitem>
1574                   <para>Specifies the name of the BMF network interface.
1575                   Defaults to <replaceable>bmf0</replaceable>.</para>
1576                 </listitem>
1577               </varlistentry>
1578
1579               <varlistentry>
1580                 <term><option>PlParam</option> BmfInterfaceIp
1581                 <replaceable>ipaddr/prefix</replaceable></term>
1582
1583                 <listitem>
1584                   <para>Specifies the IP address and netmask for the BMF
1585                   network interface. By default, the IP address of the first
1586                   OLSR interface is copied. The default prefix is
1587                   <replaceable>32</replaceable>.</para>
1588                 </listitem>
1589               </varlistentry>
1590
1591               <varlistentry>
1592                 <term><option>PlParam</option> CapturePacketsOnOlsrInterfaces
1593                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
1594
1595                 <listitem>
1596                   <para>Enables or disables capturing packets on the
1597                   OLSR-enabled interfaces (in promiscuous mode). The multicast
1598                   (and, if configured, local broadcast) packets sent on the
1599                   non-OLSR network interfaces and on the BMF network interface
1600                   will always be flooded over the OLSR network. If this
1601                   parameter is <replaceable>yes</replaceable>, also the
1602                   packets sent on the OLSR-enabled network interfaces will be
1603                   flooded over the OLSR network. Note, that his parameter
1604                   should be set consistently on all hosts throughout the
1605                   network. If not, hosts may receive multicast packets in
1606                   duplicate. Defaults to <replaceable>no</replaceable>.</para>
1607                 </listitem>
1608               </varlistentry>
1609
1610               <varlistentry>
1611                 <term><option>PlParam</option> BmfMechanism
1612                 <replaceable>Broadcast</replaceable>|<replaceable>UnicastPromiscuous</replaceable></term>
1613
1614                 <listitem>
1615                   <para>Determines the forwarding mechanism to use. In the
1616                   <replaceable>UnicastPromiscuous</replaceable> mode, packets
1617                   are forwarded (unicast) to the best candidate neighbor;
1618                   other neighbors listen promiscuously. IP-local broadcast is
1619                   not used. This saves air time on 802.11 WLAN networks, on
1620                   which unicast packets are usually sent at a much higher bit
1621                   rate than broadcast packets (which are sent at a basic bit
1622                   rate). Defaults to
1623                   <replaceable>Broadcast</replaceable>.</para>
1624                 </listitem>
1625               </varlistentry>
1626
1627               <varlistentry>
1628                 <term><option>PlParam</option> FanOutLimit
1629                 <replaceable>1</replaceable>-<replaceable>10</replaceable></term>
1630
1631                 <listitem>
1632                   <para>If the number of neighbors to forward to is less than
1633                   or equal to the <option>FanOutLimit</option>, then packets
1634                   to be relayed will be sent via unicast. If the number is
1635                   greater than the <option>FanOutLimit</option>, the packet
1636                   goes out as broadcast. Not used if
1637                   <option>BmfMechanism</option> is set to
1638                   <replaceable>UnicastPromiscuous</replaceable>. Defaults to
1639                   <replaceable>2</replaceable>.</para>
1640                 </listitem>
1641               </varlistentry>
1642
1643               <varlistentry>
1644                 <term><option>PlParam</option> BroadcastRetransmitCount
1645                 <replaceable>1</replaceable>-<replaceable>10</replaceable></term>
1646
1647                 <listitem>
1648                   <para>Determines the number of times BMF will transmit the
1649                   same packet whenever it decides to use broadcast to forward
1650                   a packet. Not used if <option>BmfMechanism</option> is set
1651                   to <replaceable>UnicastPromiscuous</replaceable>. Defaults
1652                   to <replaceable>1</replaceable>.</para>
1653                 </listitem>
1654               </varlistentry>
1655             </variablelist>
1656           </listitem>
1657         </varlistentry>
1658
1659         <varlistentry>
1660           <term><option>LoadPlugin olsrd_dot_draw.so.0.3 {
1661           <replaceable>...</replaceable> }</option></term>
1662
1663           <listitem>
1664             <para>This plugin can be used to query topology graphs via a
1665             network connection. To visualize the queried information, you need
1666             the <productname>GraphViz</productname> package from: <ulink
1667             url="http://www.graphviz.org/">http://www.graphviz.org/</ulink>.
1668             The plugin accepts the following parameters.</para>
1669
1670             <variablelist>
1671               <varlistentry>
1672                 <term><option>PlParam</option> port
1673                 <replaceable>1</replaceable>-<replaceable>65535</replaceable></term>
1674
1675                 <listitem>
1676                   <para>Determines the port number to be queried. Defaults to
1677                   <replaceable>2004</replaceable>.</para>
1678                 </listitem>
1679               </varlistentry>
1680
1681               <varlistentry>
1682                 <term><option>PlParam</option> accept
1683                 <replaceable>ipaddr</replaceable></term>
1684
1685                 <listitem>
1686                   <para>Determines a single IP address from which a connection
1687                   is accepted. Defaults to
1688                   <replaceable>127.0.0.1</replaceable>.</para>
1689                 </listitem>
1690               </varlistentry>
1691             </variablelist>
1692           </listitem>
1693         </varlistentry>
1694
1695         <varlistentry>
1696           <term><option>LoadPlugin olsrd_dyn_gw.so.0.4 {
1697           <replaceable>...</replaceable> }</option></term>
1698
1699           <listitem>
1700             <para>This plugin announces <quote>HNA { 0.0.0.0 0.0.0.0 }</quote>
1701             if it detects a functional static default route. The plugin
1702             constantly tests the default route using ICMP
1703             (<command>ping</command>). Note, that this plugin requires
1704             multi-threading support. Note also, that you need a static default
1705             route on the node. The plugin accepts the following
1706             parameters.</para>
1707
1708             <variablelist>
1709               <varlistentry>
1710                 <term><option>PlParam</option> interval
1711                 <replaceable>1</replaceable>-<replaceable>3600</replaceable></term>
1712
1713                 <listitem>
1714                   <para>Determines the time between ping tests. Defaults to
1715                   <replaceable>5</replaceable>.</para>
1716                 </listitem>
1717               </varlistentry>
1718
1719               <varlistentry>
1720                 <term><option>PlParam</option> ping
1721                 <replaceable>ipaddr</replaceable></term>
1722
1723                 <listitem>
1724                   <para>Adds a ping destination address. If one or more IPv4
1725                   addresses are configured, the plugin performs a ping test on
1726                   these addresses in descending order. If a ping test is
1727                   successful, subsequent addresses won't be pinged No
1728                   default.</para>
1729                 </listitem>
1730               </varlistentry>
1731
1732               <varlistentry>
1733                 <term><option>PlParam</option> hna "<replaceable>ipaddr
1734                 netmask-or-prefix</replaceable>"</term>
1735
1736                 <listitem>
1737                   <para>Specifies an optional HNA entry to be announced if the
1738                   ping test succeeds. Note, that the <option>PlParam</option>
1739                   sequence matters: to link a specific HNA entry to a ping
1740                   test, add the desired <replaceable>hna</replaceable>
1741                   parameter followed by one or more
1742                   <replaceable>ping</replaceable> parameters. Defaults to
1743                   <replaceable>0.0.0.0 0.0.0.0</replaceable>.</para>
1744                 </listitem>
1745               </varlistentry>
1746             </variablelist>
1747           </listitem>
1748         </varlistentry>
1749
1750         <varlistentry>
1751           <term><option>LoadPlugin olsrd_dyn_gw_plain.so.0.4 {
1752           <replaceable>...</replaceable> }</option></term>
1753
1754           <listitem>
1755             <para>This plugin announces <quote>HNA { 0.0.0.0 0.0.0.0 }</quote>
1756             if it detects a static default route. To maintain the default
1757             route, you need an external program such as a cron job. The plugin
1758             accepts no parameters.</para>
1759           </listitem>
1760         </varlistentry>
1761
1762         <varlistentry>
1763           <term><option>LoadPlugin olsrd_httpinfo.so.0.1 {
1764           <replaceable>...</replaceable> }</option></term>
1765
1766           <listitem>
1767             <para>This plugin can be used to query internal information via a
1768             web browser. The plugin implements a tiny HTTP server and
1769             publishes information on several pages. The plugin accepts the
1770             following parameters.</para>
1771
1772             <variablelist>
1773               <varlistentry>
1774                 <term><option>PlParam</option> port
1775                 <replaceable>1</replaceable>-<replaceable>65535</replaceable></term>
1776
1777                 <listitem>
1778                   <para>Determines the port number to be queried. No default,
1779                   <replaceable>8080</replaceable> recommended.</para>
1780                 </listitem>
1781               </varlistentry>
1782
1783               <varlistentry>
1784                 <term><option>PlParam</option> host
1785                 <replaceable>ipaddr</replaceable></term>
1786
1787                 <term><option>PlParam</option> host4
1788                 <replaceable>ipaddr</replaceable></term>
1789
1790                 <listitem>
1791                   <para>Adds a single IPv4 address to the list of allowed
1792                   source addresses. No default.</para>
1793                 </listitem>
1794               </varlistentry>
1795
1796               <varlistentry>
1797                 <term><option>PlParam</option> net "<replaceable>ipaddr
1798                 netmask</replaceable>"</term>
1799
1800                 <term><option>PlParam</option> net4 "<replaceable>ipaddr
1801                 netmask</replaceable>"</term>
1802
1803                 <listitem>
1804                   <para>Adds an IPv4 network range to the list of allowed
1805                   source addresses. No default.</para>
1806                 </listitem>
1807               </varlistentry>
1808
1809               <varlistentry>
1810                 <term><option>PlParam</option> host6
1811                 <replaceable>IPv6-address</replaceable></term>
1812
1813                 <listitem>
1814                   <para>Adds a single IPv6 address to the list of allowed
1815                   source addresses. No default.</para>
1816                 </listitem>
1817               </varlistentry>
1818
1819               <varlistentry>
1820                 <term><option>PlParam</option> net6 "<replaceable>IPv6-address
1821                 0-128</replaceable>"</term>
1822
1823                 <listitem>
1824                   <para>Adds an IPv6 network range to the list of allowed
1825                   source addresses. No default.</para>
1826                 </listitem>
1827               </varlistentry>
1828
1829               <varlistentry>
1830                 <term><option>PlParam</option> resolve
1831                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
1832
1833                 <listitem>
1834                   <para>Determines if the plugin tries to resolve IP addresses
1835                   to names when generating output. Note, that if you are using
1836                   private IP addresses in your mesh, you also need to load
1837                   <option>olsrd_nameservice.so.0.3</option> and link the local
1838                   <filename>/etc/hosts</filename> file to the
1839                   <option>hosts-file</option> generated by this plugin.
1840                   Otherwise this option slows down the plugins operation.
1841                   Defaults to <replaceable>no</replaceable>.</para>
1842                 </listitem>
1843               </varlistentry>
1844             </variablelist>
1845           </listitem>
1846         </varlistentry>
1847
1848         <varlistentry>
1849           <term><option>LoadPlugin olsrd_lq_etx_ff.so.0.1 {
1850           <replaceable>...</replaceable> }</option></term>
1851
1852           <listitem>
1853             <para>This plugin realized the LQ/ETX detection algorithm based on
1854             OLSR packet loss. This algorithm is compatible to the LQ
1855             calculation used by previous versions of
1856             <productname>olsrd</productname>, so this algorithm is also the
1857             compiled-in default. Note, that <productname>olsrd</productname>
1858             needs to send large signaling packet for this to work optimal,
1859             which is only true if you have a larger mesh (&gt;50 nodes). The
1860             plugin accepts no parameters.</para>
1861           </listitem>
1862         </varlistentry>
1863
1864         <varlistentry>
1865           <term><option>LoadPlugin olsrd_lq_etx_float.so.0.1 {
1866           <replaceable>...</replaceable> }</option></term>
1867
1868           <listitem>
1869             <para>This plugin calculates the link quality based on HELLO and
1870             LQ_HELLO message loss. While calculating, it uses floating point
1871             math. Note, that HELLO messages trigger a send-buffer-flush, so
1872             basically HELLOs are sent in small packets. Because the packet
1873             loss for small packets is much lower than for large packets, these
1874             algorithms may not discover optimal routes. The plugin accepts the
1875             following parameters.</para>
1876
1877             <variablelist>
1878               <varlistentry>
1879                 <term><option>PlParam</option> LinkQualityAging
1880                 <replaceable>0.01</replaceable>-<replaceable>1.0</replaceable></term>
1881
1882                 <listitem>
1883                   <para>This setting controls the LQ/ETX change speed for the
1884                   plugin. A higher value will result in faster LQ/ETX changes.
1885                   Defaults to <replaceable>0.1</replaceable>.</para>
1886                 </listitem>
1887               </varlistentry>
1888             </variablelist>
1889           </listitem>
1890         </varlistentry>
1891
1892         <varlistentry>
1893           <term><option>LoadPlugin olsrd_lq_etx_fpm.so.0.1 {
1894           <replaceable>...</replaceable> }</option></term>
1895
1896           <listitem>
1897             <para>This plugin calculates the link quality based on HELLO and
1898             LQ_HELLO message loss. While calculating, it uses integer-based
1899             fixed point math (FPM). Note, that HELLO messages trigger a
1900             send-buffer-flush, so basically HELLOs are sent in small packets.
1901             Because the packet loss for small packets is much lower than for
1902             large packets, these algorithms may not discover optimal routes.
1903             The plugin accepts the following parameters.</para>
1904
1905             <variablelist>
1906               <varlistentry>
1907                 <term><option>PlParam</option> LinkQualityAging
1908                 <replaceable>0.01</replaceable>-<replaceable>1.0</replaceable></term>
1909
1910                 <listitem>
1911                   <para>This setting controls the LQ/ETX change speed for the
1912                   plugin. A higher value will result in faster LQ/ETX changes.
1913                   Defaults to <replaceable>0.1</replaceable>.</para>
1914                 </listitem>
1915               </varlistentry>
1916             </variablelist>
1917           </listitem>
1918         </varlistentry>
1919
1920         <varlistentry>
1921           <term><option>LoadPlugin olsrd_lq_etx_rfc.so.0.1 {
1922           <replaceable>...</replaceable> }</option></term>
1923
1924           <listitem>
1925             <para>This plugin realizes the hop-optimized metric required by
1926             RFC 3626. You can load this plugin if you require standard-conform
1927             operation.</para>
1928
1929             <variablelist>
1930               <varlistentry>
1931                 <term><option>PlParam</option> UseHysteresis
1932                 <replaceable>yes</replaceable>|<replaceable>no</replaceable></term>
1933
1934                 <listitem>
1935                   <para>If set to <replaceable>yes,</replaceable> hysteresis
1936                   will be used as explained in section 14 of RFC 3626. The
1937                   setting determines if hysteresis is used. Defaults to
1938                   <replaceable>no</replaceable>.</para>
1939                 </listitem>
1940               </varlistentry>
1941
1942               <varlistentry>
1943                 <term><option>PlParam</option> HystScaling
1944                 <replaceable>0.01</replaceable>-<replaceable>0.99</replaceable></term>
1945
1946                 <listitem>
1947                   <para>Sets the scaling value used by the hysteresis
1948                   algorithm. This must be a positive floating point value
1949                   smaller than <replaceable>1.0</replaceable>. Consult RFC
1950                   3626 for details. Defaults to
1951                   <replaceable>0.5</replaceable>.</para>
1952                 </listitem>
1953               </varlistentry>
1954
1955               <varlistentry>
1956                 <term><option>PlParam</option> HystThrHigh
1957                 <replaceable>0.0</replaceable>-<replaceable>1.0</replaceable></term>
1958
1959                 <listitem>
1960                   <para>This option sets the upper threshold for accepting a
1961                   link in hysteresis calculation. The value must be higher
1962                   than the one set as the lower threshold. Defaults to
1963                   <replaceable>0.8</replaceable>.</para>
1964                 </listitem>
1965               </varlistentry>
1966
1967               <varlistentry>
1968                 <term><option>PlParam</option> HystThrLow
1969                 <replaceable>0.0</replaceable>-<replaceable>1.0</replaceable></term>
1970
1971                 <listitem>
1972                   <para>This option sets the lower threshold for setting a
1973                   link to asymmetric using hysteresis. The value must be lower
1974                   than the one set as the upper threshold. Defaults to
1975                   <replaceable>0.3</replaceable>.</para>
1976                 </listitem>
1977               </varlistentry>
1978             </variablelist>
1979           </listitem>
1980         </varlistentry>
1981
1982         <varlistentry>
1983           <term><option>LoadPlugin olsrd_mini.so.0.1 {
1984           <replaceable>...</replaceable> }</option></term>
1985
1986           <listitem>
1987             <para>This plugin is an example to be copied if you want to
1988             program a new plugin. The plugin accepts the following
1989             parameters.</para>
1990
1991             <variablelist>
1992               <varlistentry>
1993                 <term><option>PlParam</option> test
1994                 "<replaceable>some-text</replaceable>"</term>
1995
1996                 <listitem>
1997                   <para>Prints out some text during plugin initialization. No
1998                   default.</para>
1999                 </listitem>
2000               </varlistentry>
2001             </variablelist>
2002           </listitem>
2003         </varlistentry>
2004
2005         <varlistentry>
2006           <term><option>LoadPlugin olsrd_nameservice.so.0.3 {
2007           <replaceable>...</replaceable> }</option></term>
2008
2009           <listitem>
2010             <para>This plugin floods node information through the mesh
2011             piggy-backed on the OLSR protocol. It also collects information
2012             received by other nodes and stores that information in different
2013             text files on a regularly basis. The plugin accepts the following
2014             parameters.</para>
2015
2016             <variablelist>
2017               <title>General</title>
2018
2019               <varlistentry>
2020                 <term><option>PlParam</option> interval
2021                 <replaceable>1</replaceable>-<replaceable>3968</replaceable></term>
2022
2023                 <listitem>
2024                   <para>Determines the interval for sending NAME messages in
2025                   seconds. Defaults to <replaceable>120</replaceable> (2
2026                   minutes).</para>
2027                 </listitem>
2028               </varlistentry>
2029
2030               <varlistentry>
2031                 <term><option>PlParam</option> timeout
2032                 <replaceable>1.0</replaceable>-<replaceable>3968.0</replaceable></term>
2033
2034                 <listitem>
2035                   <para>Determines the validity time for received NAME
2036                   messages in seconds. Defaults to
2037                   <replaceable>1800.0</replaceable> (30 minutes)</para>
2038                 </listitem>
2039               </varlistentry>
2040             </variablelist>
2041
2042             <variablelist>
2043               <title>Host Names</title>
2044
2045               <varlistentry>
2046                 <term><option>PlParam</option> name
2047                 <replaceable>hostname</replaceable></term>
2048
2049                 <listitem>
2050                   <para>Configures a host name for the
2051                   <productname>olsrd</productname> node. This name together
2052                   with the main IP address of <productname>olsrd</productname>
2053                   is flooded though the mesh. You can specify this parameter
2054                   more than once to flood different names. No default.</para>
2055                 </listitem>
2056               </varlistentry>
2057
2058               <varlistentry>
2059                 <term><option>PlParam</option> suffix
2060                 <replaceable>dotname</replaceable></term>
2061
2062                 <listitem>
2063                   <para>Configures a suffix which is appended to all received
2064                   names. No default, but <replaceable>.olsr</replaceable>
2065                   (with a dot) is recommended to prevent DNS name
2066                   spoofing.</para>
2067                 </listitem>
2068               </varlistentry>
2069
2070               <varlistentry>
2071                 <term><option>PlParam</option> hosts-file
2072                 <replaceable>filename</replaceable></term>
2073
2074                 <listitem>
2075                   <para>The plugin writes received IP addresses and names to a
2076                   resolver compatible file which is updated on a regularly
2077                   basis. To overwrite the local hosts file, specify
2078                   <filename>/etc/hosts</filename> (Linux, BSD) or
2079                   <filename>c:\\windows\\system32\\drivers\\etc\\hosts</filename>
2080                   (Windows). Defaults to
2081                   <filename>/var/run/hosts_olsr</filename> (Linux, BSD) or
2082                   <filename>c:\windows\hosts_olsr</filename> (Windows).</para>
2083                 </listitem>
2084               </varlistentry>
2085
2086               <varlistentry>
2087                 <term><option>PlParam</option> add-hosts
2088                 <replaceable>filename</replaceable></term>
2089
2090                 <listitem>
2091                   <para>Configures a file which contents are appended when
2092                   writing the <option>hosts-file</option>. If
2093                   <productname>olsrd</productname> is configured to overwrite
2094                   your /etc/hosts file, you may rename your current /etc/hosts
2095                   file and configure this parameter to preserve any static
2096                   entries. No default.</para>
2097                 </listitem>
2098               </varlistentry>
2099
2100               <varlistentry>
2101                 <term><option>PlParam</option> name-change-script
2102                 <replaceable>filename</replaceable></term>
2103
2104                 <listitem>
2105                   <para>Configures a shell script which is executed after
2106                   updating the <option>hosts-file</option>. Can be used to
2107                   update a website or database. No default.</para>
2108                 </listitem>
2109               </varlistentry>
2110
2111               <varlistentry>
2112                 <term><option>PlParam</option> sighup-pid-file
2113                 <replaceable>filename</replaceable></term>
2114
2115                 <listitem>
2116                   <para>Sends a SIGHUP to the process specified by the pidfile
2117                   (usually <filename>/var/run/dnsmasq.pid</filename>) when the
2118                   host name table changes. This is useful for letting
2119                   <productname>dnsmasq</productname> or
2120                   <productname>bind</productname> know they have to reload
2121                   their hosts file. Linux or BSD only, no default.</para>
2122                 </listitem>
2123               </varlistentry>
2124
2125               <varlistentry>
2126                 <term><option>PlParam</option>
2127                 <replaceable>[ipaddr]</replaceable>
2128                 <replaceable>hostname</replaceable></term>
2129
2130                 <listitem>
2131                   <para>Adds a host name to be announced for the specified IP
2132                   address. Note, that this parameter is not commonly used,
2133                   specify the <option>name</option> parameter instead (see
2134                   above). The IP address has to be either from one of the
2135                   <productname>olsrd</productname> interfaces or within a
2136                   configured HNA network. This parameter can be specified
2137                   multiple times. No default.</para>
2138                 </listitem>
2139               </varlistentry>
2140             </variablelist>
2141
2142             <variablelist>
2143               <title>Services</title>
2144
2145               <varlistentry>
2146                 <term><option>PlParam</option> service
2147                 "<replaceable>announcement</replaceable>"</term>
2148
2149                 <listitem>
2150                   <para>Floods the configured service announcement through the
2151                   mesh. The announcement must include 3 fields separated with
2152                   a pipe character:
2153                   <replaceable>URL</replaceable>|<replaceable>Protocol</replaceable>|<replaceable>Description</replaceable>.
2154                   The <replaceable>URL</replaceable> field needs to start with
2155                   a protocol id, determines an IP or host.suffix combination
2156                   and adds a port number. Examples:
2157                   <quote>http://10.0.0.1:80</quote> or
2158                   <quote>ftp://myname.olsr:20</quote>.
2159                   <productname>olsrd</productname> also checks, if the address
2160                   is a local IP address, is included with any configured HNA
2161                   range, or is equal to a configured <option>name</option> and
2162                   <option>suffix</option> parameter. The
2163                   <replaceable>Protocol</replaceable> field indicates either
2164                   <replaceable>tcp</replaceable> or
2165                   <replaceable>udp</replaceable>. Use any non-empty text for
2166                   the <replaceable>Description</replaceable> field. You can
2167                   specify this parameter more than once to flood different
2168                   services. No default.</para>
2169                 </listitem>
2170               </varlistentry>
2171
2172               <varlistentry>
2173                 <term><option>PlParam</option> services-file
2174                 <replaceable>filename</replaceable></term>
2175
2176                 <listitem>
2177                   <para>The plugin writes received service announcements to a
2178                   file which is updated on a regularly basis. Defaults to
2179                   <filename>/var/run/services_olsr</filename> (Linux, BSD) or
2180                   <filename>c:\windows\services_olsr</filename>
2181                   (Windows).</para>
2182                 </listitem>
2183               </varlistentry>
2184
2185               <varlistentry>
2186                 <term><option>PlParam</option> services-change-script
2187                 <replaceable>filename</replaceable></term>
2188
2189                 <listitem>
2190                   <para>Configures a shell script which is executed after
2191                   updating the <option>services-file</option>. No
2192                   default.</para>
2193                 </listitem>
2194               </varlistentry>
2195             </variablelist>
2196
2197             <variablelist>
2198               <title>MAC Addresses</title>
2199
2200               <varlistentry>
2201                 <term><option>PlParam</option> mac
2202                 <replaceable>xx:xx:xx:xx:xx:xx[,0-255]</replaceable></term>
2203
2204                 <listitem>
2205                   <para>Floods the configured MAC address through the mesh.
2206                   This MAC address may be used to fine control captive portal
2207                   solutions based on MAC adresses. The optional decimal number
2208                   designates a class. You can specify this parameter more than
2209                   once to flood different MAC addresses. No default.</para>
2210                 </listitem>
2211               </varlistentry>
2212
2213               <varlistentry>
2214                 <term><option>PlParam</option> macs-file
2215                 <replaceable>filename</replaceable></term>
2216
2217                 <listitem>
2218                   <para>The plugin writes received MAC adresses to a file
2219                   which is updated on a regularly basis. Defaults to
2220                   <filename>/var/run/macs_olsr</filename> (Linux, BSD) or
2221                   <filename>c:\windows\macs_olsr</filename> (Windows).</para>
2222                 </listitem>
2223               </varlistentry>
2224
2225               <varlistentry>
2226                 <term><option>PlParam</option> macs-change-script
2227                 <replaceable>filename</replaceable></term>
2228
2229                 <listitem>
2230                   <para>Configures a shell script which is executed after
2231                   updating the <option>macs-file</option>. No default.</para>
2232                 </listitem>
2233               </varlistentry>
2234             </variablelist>
2235
2236             <variablelist>
2237               <title>DNS Forwarders</title>
2238
2239               <varlistentry>
2240                 <term><option>PlParam</option> dns-server
2241                 <replaceable>ipaddr</replaceable></term>
2242
2243                 <listitem>
2244                   <para>Announces the configured IP address which should
2245                   indicate a DNS server or DNS forwarder. If you configure
2246                   <replaceable>0.0.0.0</replaceable>, the main IP address of
2247                   <productname>olsrd</productname> will be replaced. Other
2248                   running <productname>olsrd</productname> instances will
2249                   receive a list of announced DNS server IP addresses, select
2250                   the currently best reachable IP address, and write the
2251                   selected IP address to the <option>resolv-file</option>
2252                   file.</para>
2253                 </listitem>
2254               </varlistentry>
2255
2256               <varlistentry>
2257                 <term><option>PlParam</option> resolv-file
2258                 <replaceable>filename</replaceable></term>
2259
2260                 <listitem>
2261                   <para>Defaults to
2262                   <filename>/var/run/resolvconf_olsr</filename> (Linux, BSD)
2263                   or <filename>c:\windows\resolvconf_olsr</filename>
2264                   (Windows).</para>
2265                 </listitem>
2266               </varlistentry>
2267             </variablelist>
2268
2269             <variablelist>
2270               <title>GPS Positions</title>
2271
2272               <varlistentry>
2273                 <term><option>PlParam</option> lat
2274                 <replaceable>latitude</replaceable></term>
2275
2276                 <listitem>
2277                   <para>Configures a decimal float value (latitude) for this
2278                   node to be flooded in the mesh. No default.</para>
2279                 </listitem>
2280               </varlistentry>
2281
2282               <varlistentry>
2283                 <term><option>PlParam</option> lon
2284                 <replaceable>longitude</replaceable></term>
2285
2286                 <listitem>
2287                   <para>Configures a decimal float value (longitude) for this
2288                   node to be flooded in the mesh. No default.</para>
2289                 </listitem>
2290               </varlistentry>
2291
2292               <varlistentry>
2293                 <term><option>PlParam</option> latlon-file
2294                 <replaceable>filename</replaceable></term>
2295
2296                 <listitem>
2297                   <para>The plugin writes received positions to a file which
2298                   is updated on a regularly basis. The file format provides
2299                   javascript-compatible function calls ready for inclusion to
2300                   a web page. The file is written only, if the
2301                   <option>lat</option> and <option>lon</option> parameters are
2302                   set. Defaults to <filename>/var/run/latlon.js</filename>
2303                   (Linux, BSD) or <filename>c:\windows\latlon.js</filename>
2304                   (Windows).</para>
2305                 </listitem>
2306               </varlistentry>
2307
2308               <varlistentry>
2309                 <term><option>PlParam</option> latlon-infile
2310                 <replaceable>filename</replaceable></term>
2311
2312                 <listitem>
2313                   <para>Configures a file to read positions from. This
2314                   parameter is meant to be used by a moving GPS receiver,
2315                   which may write comma separated decimal latitude and
2316                   longitude to this file. This will overwrite the
2317                   <option>lat</option> and <option>lon</option> parameters
2318                   during runtime. No default.</para>
2319                 </listitem>
2320               </varlistentry>
2321             </variablelist>
2322           </listitem>
2323         </varlistentry>
2324
2325         <varlistentry>
2326           <term><option>LoadPlugin olsrd_quagga.so.0.2.2 {
2327           <replaceable>...</replaceable> }</option></term>
2328
2329           <listitem>
2330             <para>This plugin allows you to import or export
2331             <productname>olsrd</productname> routing information from or to
2332             the <productname>quagga</productname> routing daemon (see <ulink
2333             url="http://www.quagga.net/">http://www.quagga.net/</ulink>). You
2334             need a patched and running <productname>quagga</productname>
2335             routing daemon to load this plugin successfully. The plugin
2336             accepts the following parameters.</para>
2337
2338             <variablelist>
2339               <varlistentry>
2340                 <term><option>PlParam</option> redistribute
2341                 <replaceable>system</replaceable>|<replaceable>kernel</replaceable>|<replaceable>connect</replaceable>|<replaceable>static</replaceable>|<replaceable>rip</replaceable>|<replaceable>ripng</replaceable>|<replaceable>ospf</replaceable>|<replaceable>ospf6</replaceable>|<replaceable>isis</replaceable>|<replaceable>bgp</replaceable>|<replaceable>hsls</replaceable></term>
2342
2343                 <listitem>
2344                   <para>Notifies <productname>Zebra</productname> to add a
2345                   specific protocol for redistribution. You may add this
2346                   parameter more than once.</para>
2347                 </listitem>
2348               </varlistentry>
2349
2350               <varlistentry>
2351                 <term><option>PlParam</option> ExportRoutes
2352                 <replaceable>only/both</replaceable></term>
2353
2354                 <listitem>
2355                   <para>Determines, if <productname>olsrd</productname> should
2356                   <replaceable>only</replaceable> export routes to
2357                   <productname>quagga</productname> or should export routes to
2358                   <replaceable>both</replaceable>
2359                   <productname>quagga</productname> and kernel. If this
2360                   parameter is unset, no routes are exported to
2361                   <productname>quagga</productname>.</para>
2362                 </listitem>
2363               </varlistentry>
2364
2365               <varlistentry>
2366                 <term><option>PlParam</option> Distance
2367                 <replaceable>0</replaceable>-<replaceable>255</replaceable></term>
2368
2369                 <listitem>
2370                   <para>Configures the administrative distance for routes
2371                   exported to <productname>Zebra</productname>. Defaults to
2372                   <replaceable>0</replaceable>.</para>
2373                 </listitem>
2374               </varlistentry>
2375
2376               <varlistentry>
2377                 <term><option>PlParam</option> LocalPref
2378                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
2379
2380                 <listitem>
2381                   <para>Sets the SELECTED flag on the routes exported to
2382                   <productname>Zebra</productname> which means these routes
2383                   are preferred in any case. Defaults to
2384                   <replaceable>no</replaceable>.</para>
2385                 </listitem>
2386               </varlistentry>
2387             </variablelist>
2388           </listitem>
2389         </varlistentry>
2390
2391         <varlistentry>
2392           <term><option>LoadPlugin olsrd_secure.so.0.5 {
2393           <replaceable>...</replaceable> }</option></term>
2394
2395           <listitem>
2396             <para>This plugin uses a secret pre shared key for signature
2397             generation and verification of incoming OLSR messages. All nodes
2398             that participate in an OLSR routing domain need to use the same
2399             key. The key as a size of 128-bits and is read in from a key file
2400             which should contain 16 bytes of binary data. The plugin accepts
2401             the following parameters.</para>
2402
2403             <variablelist>
2404               <varlistentry>
2405                 <term><option>PlParam</option> keyfile
2406                 <replaceable>filename</replaceable></term>
2407
2408                 <listitem>
2409                   <para>Configure a filename to read the pre shared key from.
2410                   Defaults to
2411                   <filename>/etc/olsrd.d/olsrd_secure_key</filename>.</para>
2412                 </listitem>
2413               </varlistentry>
2414             </variablelist>
2415           </listitem>
2416         </varlistentry>
2417
2418         <varlistentry>
2419           <term><option>LoadPlugin olsrd_txtinfo.so.0.1 {
2420           <replaceable>...</replaceable> }</option></term>
2421
2422           <listitem>
2423             <para>This plugin can be used to query internal information via
2424             the <guilabel>wget</guilabel> command. This plugin is a de-bloated
2425             and scriptable version of the httpinfo-Plugin. Example usage:
2426             <command>wget -q -O - http://localhost:2006/neighbours</command>
2427             to display the current neighbour table. The plugin accepts the
2428             following parameters.</para>
2429
2430             <variablelist>
2431               <varlistentry>
2432                 <term><option>PlParam</option> port
2433                 <replaceable>1</replaceable>-<replaceable>65535</replaceable></term>
2434
2435                 <listitem>
2436                   <para>Determines the port number to be queried. Defaults to
2437                   <replaceable>2006</replaceable>.</para>
2438                 </listitem>
2439               </varlistentry>
2440
2441               <varlistentry>
2442                 <term><option>PlParam</option> accept
2443                 <replaceable>ipaddr</replaceable></term>
2444
2445                 <listitem>
2446                   <para>Adds a single IP address to the list of allowed source
2447                   addresses. Defaults to <replaceable>127.0.0.1</replaceable>
2448                   for IPv4 or <replaceable>::1</replaceable> for IPv6.</para>
2449                 </listitem>
2450               </varlistentry>
2451             </variablelist>
2452           </listitem>
2453         </varlistentry>
2454
2455         <varlistentry>
2456           <term><option>LoadPlugin olsrd_watchdog.so.0.1 {
2457           <replaceable>...</replaceable> }</option></term>
2458
2459           <listitem>
2460             <para>This plugin writes the current time to a file on a regularly
2461             basis. This can be used to detect a freezed instance of
2462             <productname>olsrd</productname> by an external script or cron
2463             job. The plugin accepts the following parameters.</para>
2464
2465             <variablelist>
2466               <varlistentry>
2467                 <term><option>PlParam</option> file
2468                 <replaceable>filename</replaceable></term>
2469
2470                 <listitem>
2471                   <para>Determines the file to be written. Defaults to
2472                   <filename>/tmp/olsr.watchdog</filename>.</para>
2473                 </listitem>
2474               </varlistentry>
2475
2476               <varlistentry>
2477                 <term><option>PlParam</option> interval
2478                 <replaceable>1</replaceable>-<replaceable>3600</replaceable></term>
2479
2480                 <listitem>
2481                   <para>Determines the update interval in seconds. Defaults to
2482                   <replaceable>5</replaceable>.</para>
2483                 </listitem>
2484               </varlistentry>
2485             </variablelist>
2486           </listitem>
2487         </varlistentry>
2488       </variablelist>
2489     </refsect1>
2490
2491     <refsect1>
2492       <title>Misc</title>
2493
2494       <para>The homepage of <productname>olsrd</productname> is <ulink
2495       url="http://www.olsr.org">http://www.olsr.org</ulink></para>
2496     </refsect1>
2497
2498     <refsect1>
2499       <title>Files</title>
2500
2501       <para><filename>/etc/olsrd.conf</filename></para>
2502     </refsect1>
2503
2504     <refsect1>
2505       <title>See Also</title>
2506
2507       <simplelist type="inline">
2508         <member><xref endterm="olsrd_8-title" linkend="olsrd_8" /><xref
2509         endterm="olsrd_metrics_3-title" linkend="olsrd_metrics_3" /></member>
2510       </simplelist>
2511     </refsect1>
2512   </refentry>
2513
2514   <refentry id="olsrd_metrics_3">
2515     <indexterm>
2516       <primary><productname>olsrd-metrics</productname></primary>
2517     </indexterm>
2518
2519     <refentryinfo>
2520       <titleabbrev><productname>olsrd</productname> Metrics
2521       Plugin</titleabbrev>
2522
2523       <authorgroup>
2524         <author>
2525           <firstname>Leon Aaron</firstname>
2526
2527           <surname>Kaplan</surname>
2528
2529           <email>aaron@lo-res.org</email>
2530         </author>
2531
2532         <author>
2533           <firstname>Henning</firstname>
2534
2535           <surname>Rogge</surname>
2536
2537           <email>rogge@fgan.de</email>
2538         </author>
2539       </authorgroup>
2540     </refentryinfo>
2541
2542     <refmeta>
2543       <refentrytitle id="olsrd_metrics_3-title">olsrd-metrics
2544       plugin</refentrytitle>
2545
2546       <manvolnum>3</manvolnum>
2547     </refmeta>
2548
2549     <refnamediv>
2550       <refname>olsrd-metrics</refname>
2551
2552       <refpurpose>How to write your own metrics plugin</refpurpose>
2553     </refnamediv>
2554
2555     <refsect1>
2556       <title>Description</title>
2557
2558       <para>The idea behind the <filename
2559       class="directory">lib/lq_*</filename> is that you can write your own
2560       Link Quality (LQ) metric mostly independent of the main
2561       <productname>olsrd</productname> code.</para>
2562
2563       <para>What is a metric? A metric is a notion of "distance" between nodes
2564       in the mesh. Mobile ad hoc network (MANET) research identified the area
2565       of finding proper metrics for a MANET as one of the most important
2566       routing decisions. A metric basically determines the path that packets
2567       will take. The Shortest Path First (SPF, also sometimes called Dijkstra
2568       Algorithm) will chose the shortest sum of all possible paths. So what
2569       paths do we want to chose in WLAN MANET networks?</para>
2570
2571       <para>In general we want to have a little collisions as possible since
2572       802.11a/b/g is a broadcast medium by nature. When you compare the very
2573       old Ethernet systems (coax cable, http://en.wikipedia.org/wiki/10BASE2)
2574       you can observe that at a certain percentage of cable utilization (as
2575       low as 40%), you would get many collisions (since the coax cable is a
2576       broadcast medium just as WLAN!) and the total throughput would collapse
2577       to nearly zero.</para>
2578
2579       <para>Another choice for metrics might be signal strength.</para>
2580
2581       <para>Currently <productname>olsrd</productname> (as of Oct-2008)
2582       implements the following metric:</para>
2583
2584       <itemizedlist>
2585         <listitem>
2586           <para>RFC 3626 conforming hop count (each link has the metric value
2587           "1")</para>
2588         </listitem>
2589
2590         <listitem>
2591           <para>ETX_default_ff (ETX from MIT roofnet, with FunkFeuer.at
2592           extensions)</para>
2593         </listitem>
2594
2595         <listitem>
2596           <para>ETX_default_float (ETX with floating point arithmetic)</para>
2597         </listitem>
2598
2599         <listitem>
2600           <para>ETX_default_fpm (ETX with fixed point maths (integer). Much
2601           faster on small embedded devices!</para>
2602         </listitem>
2603       </itemizedlist>
2604     </refsect1>
2605
2606     <refsect1>
2607       <title>Getting Started</title>
2608
2609       <para>Start by reading <filename>src/lq_plugin.c</filename> and
2610       <filename>lq_plugin.h</filename>. Note, that struct
2611       <type>lq_handler</type>: is a pseudo C++ structure ;-) there is a
2612       pointer table to functions so that the plugin system knows which
2613       functions it should jump to.</para>
2614
2615       <programlisting>struct lq_handler {
2616  ...
2617   /*
2618    * number of bytes we need per hello in the hello DB for this specific 
2619    * metric. This has nothing to do what is being sent over the net. This 
2620    * is only so that you can use the structure itself to store your 
2621    * metric data
2622    */
2623   size_t hello_lq_size;
2624   size_t tc_lq_size;
2625 };</programlisting>
2626
2627       <para>Almost all functions accept a void pointer. This now points to the
2628       beginning of the custom memory area that you allocated with the
2629       tc_lq_size or hello_lq_size above.</para>
2630
2631       <para>Now...: if you want to write your own metric then you must define
2632       your own struct lq_handler and pass that variable to:</para>
2633
2634       <programlisting>void register_lq_handler(struct lq_handler *handler, const char *name);</programlisting>
2635
2636       <para>for example:</para>
2637
2638       <programlisting>struct lq_handler my_lq_metric;
2639
2640 ... // init my_lq_metric fully (every function must be assigned)
2641
2642 register_lq_handler(&amp;my_lq_metric, "my_lq_metric");</programlisting>
2643
2644       <para>For another example, take a look at
2645       <filename>lq_plugin_default_float.[ch]</filename> There it is done like
2646       this:</para>
2647
2648       <programlisting>/* Default lq plugin settings */
2649 struct lq_handler lq_etxff_handler = {
2650   &amp;lq_etxff_initialize,
2651   &amp;lq_etxff_deinitialize,
2652
2653   &amp;lq_etxff_calc_link_entry_cost,
2654   &amp;lq_etxff_calc_lq_hello_neighbor_cost,
2655   &amp;lq_etxff_calc_tc_mpr_addr_cost,
2656   &amp;lq_etxff_calc_tc_edge_entry_cost,
2657
2658   &amp;lq_etxff_is_relevant_costchange,
2659
2660   &amp;lq_etxff_packet_loss_handler,
2661
2662   &amp;lq_etxff_memorize_foreign_hello,
2663   &amp;lq_etxff_copy_link_entry_lq_into_tc_mpr_addr,
2664   &amp;lq_etxff_copy_link_entry_lq_into_tc_edge_entry,
2665   &amp;lq_etxff_copy_link_lq_into_neighbor,
2666
2667   &amp;lq_etxff_clear_link_entry,
2668   NULL, /* not necessary */
2669   NULL, /* not necessary */
2670   NULL, /* not necessary */
2671
2672   &amp;lq_etxff_serialize_hello_lq,
2673   &amp;lq_etxff_serialize_tc_lq,
2674   &amp;lq_etxff_deserialize_hello_lq,
2675   &amp;lq_etxff_deserialize_tc_lq,
2676
2677   &amp;lq_etxff_print_link_entry_lq,
2678   &amp;lq_etxff_print_tc_edge_entry_lq,
2679   &amp;lq_etxff_print_cost,
2680
2681   sizeof(struct lq_etxff_tc_edge),
2682   sizeof(struct lq_etxff_tc_mpr_addr),
2683   sizeof(struct lq_etxff_lq_hello_neighbor),
2684   sizeof(struct lq_etxff_link_entry),
2685
2686   LQ_HELLO_MESSAGE,
2687   LQ_TC_MESSAGE
2688 };</programlisting>
2689     </refsect1>
2690
2691     <refsect1>
2692       <title>Function Reference</title>
2693
2694       <para>The other entries here are pointers to functions which are defined
2695       in the .h file. Now lets have a look at the functions.</para>
2696
2697       <variablelist>
2698         <varlistentry>
2699           <term>void (*initialize)(void);</term>
2700
2701           <listitem>
2702             <para>This callback is triggered shortly after loading the plugin
2703             into <productname>olsrd</productname>. Note, that all
2704             <option>PlParam</option> values from the configuration file are
2705             alredy evaluted at this time.</para>
2706
2707             <para>The <function>initialize</function> function may start some
2708             timers (via <function>olsr_alloc_cookie</function> ) and may
2709             register hooks to be triggered when a message is received (via
2710             <function>olsr_packetparser_add_function</function>).</para>
2711           </listitem>
2712         </varlistentry>
2713
2714         <varlistentry>
2715           <term>void (*deinitialize)(void);</term>
2716
2717           <listitem>
2718             <para>This callback is triggered shortly before unloading the
2719             plugin from <productname>olsrd</productname>. Note, that it is
2720             generally a good idea to free up hooks, timers and memory aquired
2721             during initialization or runtime.</para>
2722           </listitem>
2723         </varlistentry>
2724
2725         <varlistentry>
2726           <term>olsr_linkcost (*calc_link_entry_cost) (struct link_entry
2727           *);</term>
2728
2729           <listitem>
2730             <para>This callback is currently unused.</para>
2731           </listitem>
2732         </varlistentry>
2733
2734         <varlistentry>
2735           <term>olsr_linkcost (*calc_lq_hello_neighbor_cost) (struct
2736           lq_hello_neighbor *);</term>
2737
2738           <listitem>
2739             <para>This callback is triggered whenever a HELLO message is
2740             received and the link cost for the corresponding neighbour needs
2741             to be calculated.</para>
2742
2743             <para>You will get a pointer to your part of the hello database
2744             and your plugin is supposed to generate a hello cost in the
2745             standard format from the internal representation: the core format
2746             is a 32 bit unsigned integer . This then is used for adding up the
2747             costs in the Dijkstra calculation. So be sure that you do not use
2748             values greater than 2^24 . Otherwise for very long routes (256
2749             hops) this will then add up in the internal representation so that
2750             there will be integer overflows. So stay below 2^24(*). The base
2751             of the cost is your business. For example, to represent fixed
2752             point arithmetic you might multiply your (float) hello costs by
2753             256 and treat the least significant byte as the digits behind the
2754             point.</para>
2755
2756             <para>(*) or actually even better: us the constant
2757             LINK_COST_BROKEN from <filename>lq_plugin.h</filename></para>
2758           </listitem>
2759         </varlistentry>
2760
2761         <varlistentry>
2762           <term>olsr_linkcost (*calc_tc_mpr_addr_cost) (struct tc_mpr_addr
2763           *);</term>
2764
2765           <listitem>
2766             <para>This callback is currently unused.</para>
2767           </listitem>
2768         </varlistentry>
2769
2770         <varlistentry>
2771           <term>olsr_linkcost (*calc_tc_edge_entry_cost) (struct tc_edge_entry
2772           *);</term>
2773
2774           <listitem>
2775             <para>This callback will be called whenever the link cost for a TC
2776             edge entry needs to be calculated. Same as for
2777             <function>calc_lq_hello_neighbor_cost</function> but just for TC
2778             edge entires.</para>
2779           </listitem>
2780         </varlistentry>
2781
2782         <varlistentry>
2783           <term>bool (*is_relevant_costchange) (olsr_linkcost c1,
2784           olsr_linkcost c2);</term>
2785
2786           <listitem>
2787             <para>This callback is triggered after the main loop whenever the
2788             core has to decide if a new Dijkstra needs to be calculated. This
2789             happens, for example if the link cost for a TC edge entry was
2790             updated using <function>calc_tc_edge_entry_cost</function>.</para>
2791
2792             <para>If a link quality does only change slightly return
2793             <replaceable>false</replaceable>, so there will be no
2794             recalculation of the Dijkstra algorithm which costs a lot of CPU.
2795             Since only the plugin knows the range of the link quality values,
2796             only the plugin can decide if the cost change is relevant
2797             enough.</para>
2798           </listitem>
2799         </varlistentry>
2800
2801         <varlistentry>
2802           <term>olsr_linkcost (*packet_loss_handler) (struct link_entry *,
2803           bool);</term>
2804
2805           <listitem>
2806             <para>This callback is triggered every time a HELLO message for a
2807             certain link_entry * is lost (timeout) or received. This way the
2808             plugin can update the cost for the link entry.</para>
2809           </listitem>
2810         </varlistentry>
2811
2812         <varlistentry>
2813           <term>void (*memorize_foreign_hello) (struct link_entry *, struct
2814           lq_hello_neighbor *);</term>
2815
2816           <listitem>
2817             <para>This callback is triggerd to copy the link quality
2818             information from a received HELLO message into a link
2819             entry.</para>
2820           </listitem>
2821         </varlistentry>
2822
2823         <varlistentry>
2824           <term>void (*copy_link_entry_lq_into_tc_mpr_addr) (struct
2825           tc_mpr_addr *, struct link_entry *);</term>
2826
2827           <listitem>
2828             <para>This callback copies the link quality information from a
2829             link_entry to a tc_mpr_addr.</para>
2830           </listitem>
2831         </varlistentry>
2832
2833         <varlistentry>
2834           <term>void (*copy_link_entry_lq_into_tc_edge_entry) (struct
2835           tc_edge_entry *, struct link_entry *);</term>
2836
2837           <listitem>
2838             <para>This callback copies the link quality information from a
2839             link entry to a tc_edge_entry. This happens, if a HELLO message
2840             was received. Since the data structures have a different
2841             representation, this function is used to convert the
2842             representations.</para>
2843           </listitem>
2844         </varlistentry>
2845
2846         <varlistentry>
2847           <term>void (*copy_link_lq_into_neighbor) (struct lq_hello_neighbor
2848           *, struct link_entry *);</term>
2849
2850           <listitem>
2851             <para>This callback copies the link quality information from a
2852             link_entry to a lq_hello_neighbor.</para>
2853           </listitem>
2854         </varlistentry>
2855
2856         <varlistentry>
2857           <term>void (*clear_link_entry) (struct link_entry *);</term>
2858
2859           <listitem>
2860             <para>...</para>
2861           </listitem>
2862         </varlistentry>
2863
2864         <varlistentry>
2865           <term>void (*clear_lq_hello_neighbor) (struct lq_hello_neighbor
2866           *);</term>
2867
2868           <listitem>
2869             <para>...</para>
2870           </listitem>
2871         </varlistentry>
2872
2873         <varlistentry>
2874           <term>void (*clear_tc_mpr_addr) (struct tc_mpr_addr *);</term>
2875
2876           <listitem>
2877             <para>...</para>
2878           </listitem>
2879         </varlistentry>
2880
2881         <varlistentry>
2882           <term>void (*clear_tc_edge_entry) (struct tc_edge_entry *);</term>
2883
2884           <listitem>
2885             <para>...</para>
2886           </listitem>
2887         </varlistentry>
2888
2889         <varlistentry>
2890           <term>int (*serialize_hello_lq) (unsigned char *, struct
2891           lq_hello_neighbor *);</term>
2892
2893           <listitem>
2894             <para>This callback is triggerd whenever a LQ message needs to be
2895             deserialized The callback reads the message information of a
2896             binary packet and writes into an neighbour buffer.</para>
2897           </listitem>
2898         </varlistentry>
2899
2900         <varlistentry>
2901           <term>int (*serialize_tc_lq) (unsigned char *, struct tc_mpr_addr
2902           *);</term>
2903
2904           <listitem>
2905             <para>This callback is triggerd whenever a TC message needs to be
2906             deserialized The callback reads the message information of a
2907             binary packet and writes into an MPR buffer.</para>
2908           </listitem>
2909         </varlistentry>
2910
2911         <varlistentry>
2912           <term>char *(*print_link_entry_lq) (struct link_entry *, char ,
2913           struct lqtextbuffer *);</term>
2914
2915           <listitem>
2916             <para>This callback is triggered whenever any other part of the
2917             code wants to convert your internal metric representation of
2918             HELLO-determined links into a printable version. The callback may
2919             be called at any time.</para>
2920
2921             <para><parameter>ptr</parameter> is a void pointer to the link
2922             quality data in the Hello DB. <parameter>seperator</parameter> is
2923             a character which is printed whenever there are multiple values
2924             (for example <quote>,</quote> or <quote>/</quote>).
2925             <parameter>buffer</parameter> is the buffer you want to
2926             <function>sprintf</function> into. Please do not forget to zero
2927             terminate the return value. The callback returns the buffer in
2928             case of errors. Please return <literal>"error"</literal> as const
2929             string, because <function>print_hello_lq</function> will often
2930             directly be put into a <function>printf("%s")</function>.</para>
2931           </listitem>
2932         </varlistentry>
2933
2934         <varlistentry>
2935           <term>char *(*print_tc_edge_entry_lq) (struct tc_edge_entry *, char
2936           , struct lqtextbuffer *);</term>
2937
2938           <listitem>
2939             <para>Same as <function>print_link_entry_lq</function>, but for an
2940             entry from the TC database.</para>
2941           </listitem>
2942         </varlistentry>
2943
2944         <varlistentry>
2945           <term>char *(*print_cost) (olsr_linkcost cost, struct lqtextbuffer
2946           *);</term>
2947
2948           <listitem>
2949             <para>Same as <function>print_link_entry_lq</function>, but for an
2950             arbitrary link cost element.</para>
2951           </listitem>
2952         </varlistentry>
2953
2954         <varlistentry>
2955           <term>size_t size_tc_edge;</term>
2956
2957           <listitem>
2958             <para>Set to a value larger that zero to reserve extra memory in
2959             the hello database.</para>
2960           </listitem>
2961         </varlistentry>
2962
2963         <varlistentry>
2964           <term>size_t size_tc_mpr_addr;</term>
2965
2966           <listitem>
2967             <para>Set to a value larger that zero to reserve extra memory in
2968             the mpr database.</para>
2969           </listitem>
2970         </varlistentry>
2971
2972         <varlistentry>
2973           <term>size_t size_lq_hello_neighbor;</term>
2974
2975           <listitem>
2976             <para>Set to a value larger that zero to reserve extra memory in
2977             the lq database.</para>
2978           </listitem>
2979         </varlistentry>
2980
2981         <varlistentry>
2982           <term>size_t size_link_entry;</term>
2983
2984           <listitem>
2985             <para>Set to a value larger that zero to reserve extra memory in
2986             the link database.</para>
2987           </listitem>
2988         </varlistentry>
2989
2990         <varlistentry>
2991           <term>uint8_t messageid_hello;</term>
2992
2993           <listitem>
2994             <para>Determines the binary value for the OLSR message type used
2995             for HELLO messages.</para>
2996           </listitem>
2997         </varlistentry>
2998
2999         <varlistentry>
3000           <term>uint8_t messageid_tc;</term>
3001
3002           <listitem>
3003             <para>Determines the binary value for the OLSR message type used
3004             for TC messages.</para>
3005           </listitem>
3006         </varlistentry>
3007       </variablelist>
3008     </refsect1>
3009
3010     <refsect1>
3011       <title>See Also</title>
3012
3013       <simplelist type="inline">
3014         <member><xref endterm="olsrd_8-title" linkend="olsrd_8" /> <xref
3015         endterm="olsrd_conf_5-title" linkend="olsrd_conf_5" /></member>
3016       </simplelist>
3017     </refsect1>
3018   </refentry>
3019 </article>