doc: added README-metrics.txt as new man page
[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>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. Defaults to
1008             <replaceable>3</replaceable>.</para>
1009           </listitem>
1010         </varlistentry>
1011
1012         <varlistentry>
1013           <term><option>RtTableDefault</option>
1014           <replaceable>0</replaceable>|<replaceable>1</replaceable>-<replaceable>254</replaceable></term>
1015
1016           <listitem>
1017             <para>Defines the routing table for inserting a new default route.
1018             Defaults to <replaceable>0</replaceable> (use
1019             <option>RtTable</option>)</para>
1020           </listitem>
1021         </varlistentry>
1022
1023         <varlistentry>
1024           <term><option>RtTable</option>
1025           <replaceable>1</replaceable>-<replaceable>254</replaceable></term>
1026
1027           <listitem>
1028             <para>With Linux and BSD, more than one routing table exist in the
1029             system. Together with a rules set that determines which table
1030             handles what packets, these system functions are called
1031             <quote>iproute2</quote> or <quote>Policy Routing</quote>. You may
1032             want to read the <ulink url="http://lartc.org/">Linux Advanced
1033             Routing &amp; Traffic Control</ulink> for details. Defaults to
1034             <replaceable>254</replaceable> (or <quote>main</quote>, see
1035             <filename>/etc/iproute2/rt_tables</filename>)</para>
1036           </listitem>
1037         </varlistentry>
1038
1039         <varlistentry>
1040           <term><option>TcRedundancy</option>
1041           <replaceable>0</replaceable>|<replaceable>1</replaceable>|<replaceable>2</replaceable></term>
1042
1043           <listitem>
1044             <para>This value controls the TC redundancy used by the local node
1045             in TC message generation. To enable a more robust understanding of
1046             the topology, nodes can be set to announce more than just their
1047             MPR selector set in TC messages. If set to
1048             <replaceable>0</replaceable>, the advertised link set of the node
1049             is limited to the MPR selectors. If set to
1050             <replaceable>1</replaceable>, the advertised link set of the node
1051             is the union of its MPR set and its MPR selector set. If set to
1052             <replaceable>2</replaceable>, the advertised link set of the node
1053             is the full symmetric neighbor set of the node. Defaults to
1054             <replaceable>0</replaceable>.</para>
1055           </listitem>
1056         </varlistentry>
1057
1058         <varlistentry>
1059           <term><option>TosValue</option>
1060           <replaceable>0</replaceable>-<replaceable>16</replaceable></term>
1061
1062           <listitem>
1063             <para>This value controls the type of service value to set in the
1064             IP header of OLSR control traffic. Defaults to
1065             <replaceable>16</replaceable>.</para>
1066           </listitem>
1067         </varlistentry>
1068
1069         <varlistentry>
1070           <term><option>Willingness</option>
1071           <replaceable>0</replaceable>-<replaceable>7</replaceable></term>
1072
1073           <listitem>
1074             <para>Nodes participating in an OLSR routed network will announce
1075             their willingness to act as relays for OLSR control traffic for
1076             their neighbors (MPR). This option specifies a fixed willingness
1077             value to be announced by the local node.
1078             <replaceable>4</replaceable> is a neutral option here, while
1079             <replaceable>0</replaceable> specifies that this node will never
1080             act as a relay, and <replaceable>7</replaceable> specifies that
1081             this node will always act as such a relay. If this option is unset
1082             in the configuration file, then <productname>olsrd</productname>
1083             will try to retrieve information about the system power and
1084             dynamically update willingness according to this info. If no such
1085             info can be retrieved willingness is set to
1086             <replaceable>4</replaceable>.</para>
1087           </listitem>
1088         </varlistentry>
1089       </variablelist>
1090     </refsect1>
1091
1092     <refsect1 id="olsrd_conf_5_optionblocks">
1093       <title id="olsrd_conf_5_optionblocks-title">Option Blocks</title>
1094
1095       <para>Option blocks are configuration options that holds a body of
1096       sub-options encapsulated in curled braces <quote>{...}</quote>. Note,
1097       that you need to separate the keyword and the starting brace with one or
1098       more whitespace characters (spaces, tabs, or newlines). Also separate
1099       sub-options as well as the closing brace with additional whitespace
1100       characters. Valid options are:</para>
1101
1102       <variablelist>
1103         <varlistentry>
1104           <term><option>IpcConnect { <replaceable>sub-options</replaceable>
1105           }</option></term>
1106
1107           <listitem>
1108             <para><productname>olsrd</productname> can allow processes to make
1109             a TCP connection to itself on which data regarding the topology
1110             will be transmitted. This is typically used by GUI applications to
1111             provide a user-friendly front-end to
1112             <productname>olsrd</productname>. This option block controls the
1113             IPC access. Sub options are:</para>
1114
1115             <variablelist>
1116               <varlistentry>
1117                 <term><option>MaxConnections</option>
1118                 <replaceable>0</replaceable>-<replaceable>5</replaceable></term>
1119
1120                 <listitem>
1121                   <para>This option specifies how many connections that can
1122                   exist simultaneously. Multiple connections have not been
1123                   tested, and probably do not work! This option should only be
1124                   used to control whether or not processes can connect to
1125                   <productname>olsrd</productname> by setting it either to
1126                   <replaceable>0</replaceable>, which will tell
1127                   <productname>olsrd</productname> not to allow any
1128                   connections, or by setting it to a positive value. Defaults
1129                   to <replaceable>0</replaceable>.</para>
1130                 </listitem>
1131               </varlistentry>
1132
1133               <varlistentry>
1134                 <term><option>Host</option>
1135                 <replaceable>ipaddr</replaceable></term>
1136
1137                 <listitem>
1138                   <para>This option specifies a single host that is allowed to
1139                   connect to <productname>olsrd</productname>. By default only
1140                   the loopback address (127.0.0.1) is allowed to access. If
1141                   you want to be able to connect from another host, you should
1142                   add that IP address. You may add multiple hosts.</para>
1143                 </listitem>
1144               </varlistentry>
1145
1146               <varlistentry>
1147                 <term><option>Net</option> <replaceable>ipaddr</replaceable>
1148                 <replaceable>netmask</replaceable>|<replaceable>prefix</replaceable></term>
1149
1150                 <listitem>
1151                   <para>You can specify a net range of IP addresses which
1152                   <productname>olsrd</productname> will allow TCP connections
1153                   from. Besides the IP address, you need to specify a netmask
1154                   for IPv4 and a prefix for IPv6. You may add multiple
1155                   networks.</para>
1156                 </listitem>
1157               </varlistentry>
1158             </variablelist>
1159           </listitem>
1160         </varlistentry>
1161
1162         <varlistentry>
1163           <term><option>Hna4 { <replaceable>sub-options</replaceable>
1164           }</option></term>
1165
1166           <listitem>
1167             <para>Hosts in a routed network can announce connectivity to
1168             external networks or hosts using HNA messages. This option block
1169             is used to set the IPv4 networks or hosts to be announced. Sub
1170             options are:</para>
1171
1172             <variablelist>
1173               <varlistentry>
1174                 <term><replaceable>IPv4-address</replaceable>
1175                 <replaceable>IPv4-netmask</replaceable></term>
1176
1177                 <listitem>
1178                   <para>Specifies an IPv4 network or host to be announced via
1179                   HNA messages. Multiple entries can be added. To announce
1180                   Internet connectivity, add
1181                   <replaceable>0.0.0.0</replaceable>
1182                   <replaceable>0.0.0.0</replaceable>. To announce a single
1183                   host, add <replaceable>ipaddr</replaceable>
1184                   <replaceable>255.255.255.255</replaceable>.</para>
1185                 </listitem>
1186               </varlistentry>
1187             </variablelist>
1188           </listitem>
1189         </varlistentry>
1190
1191         <varlistentry>
1192           <term><option>Hna6 { <replaceable>sub-options</replaceable>
1193           }</option></term>
1194
1195           <listitem>
1196             <para>Hosts in a routed network can announce connectivity to
1197             external networks or hosts using HNA messages. This option block
1198             is used to set the IPv6 networks or hosts to be announced. Sub
1199             options are:</para>
1200
1201             <variablelist>
1202               <varlistentry>
1203                 <term><replaceable>IPv6-address</replaceable> 0-128</term>
1204
1205                 <listitem>
1206                   <para>Specifies an IPv6 network or host to be announced via
1207                   HNA messages. Multiple entries can be added. To announce
1208                   Internet connectivity, add <replaceable>::</replaceable>
1209                   <replaceable>0</replaceable> . To announce a single host,
1210                   add <replaceable>ipaddr</replaceable>
1211                   <replaceable>128</replaceable>.</para>
1212                 </listitem>
1213               </varlistentry>
1214             </variablelist>
1215           </listitem>
1216         </varlistentry>
1217
1218         <varlistentry>
1219           <term><option>LoadPlugin <replaceable>plugin-filename</replaceable>
1220           { <replaceable>sub-options</replaceable> }</option></term>
1221
1222           <listitem>
1223             <para>Specifies a plugin that <productname>olsrd</productname>
1224             should load at startup. You need to specify the filename for the
1225             shared object file (<filename>*.so</filename> on Linux and
1226             <filename>*.dll</filename> on Windows). Read the
1227             <filename>README</filename> in the plugin's source directory or
1228             refer the <xref endterm="olsrd_conf_5_plugins-title"
1229             linkend="olsrd_conf_5_plugins" /> section below. This option block
1230             can be repeated to add multiple plugins. Sub options are:</para>
1231
1232             <variablelist>
1233               <varlistentry>
1234                 <term><option>PlParam</option> <replaceable>key</replaceable>
1235                 <replaceable>value</replaceable></term>
1236
1237                 <listitem>
1238                   <para>Sends a pair of parameters to the plugin at
1239                   initialization. The parameter's
1240                   <replaceable>key</replaceable> is case insensitive. Refer to
1241                   the <xref endterm="olsrd_conf_5_plugins-title"
1242                   linkend="olsrd_conf_5_plugins" /> section below or consult
1243                   individual plugin documentation for possible
1244                   parameters.</para>
1245                 </listitem>
1246               </varlistentry>
1247             </variablelist>
1248           </listitem>
1249         </varlistentry>
1250
1251         <varlistentry>
1252           <term><option>Interface <replaceable>interface1</replaceable>
1253           <replaceable>interface2...</replaceable> {
1254           <replaceable>sub-options</replaceable> }</option></term>
1255
1256           <listitem>
1257             <para>This option block specifies one or more network interfaces
1258             on which <productname>olsrd</productname> should run. At least one
1259             network interface block must be specified for
1260             <productname>olsrd</productname> to run. Various parameters can be
1261             specified on individual interfaces or groups of interfaces. This
1262             option block can be repeated to add multiple interface
1263             configurations. Sub options are:</para>
1264
1265             <variablelist>
1266               <varlistentry>
1267                 <term><option>AutoDetectChanges</option>
1268                 <replaceable>yes</replaceable>|<replaceable>no</replaceable></term>
1269
1270                 <listitem>
1271                   <para><productname>olsrd</productname> can auto detect
1272                   changes in interface configurations by polling on the
1273                   interval set by <option>NicChgsPollInt</option>. This is
1274                   enabled by default but can be turned off per interface to
1275                   save CPU cycles.</para>
1276                 </listitem>
1277               </varlistentry>
1278
1279               <varlistentry>
1280                 <term><option>Ip4Broadcast</option>
1281                 <replaceable>IPv4-address</replaceable></term>
1282
1283                 <listitem>
1284                   <para>Forces the given IPv4 broadcast address to be used as
1285                   destination address for all outgoing OLSR traffic on the
1286                   interface. If your mesh uses several IP address ranges, the
1287                   global broadcast address
1288                   <replaceable>255.255.255.255</replaceable> can be used. If
1289                   you use a point-to-point link (e.g. a tun-type VPN tunnel),
1290                   you may configure the neighbours IP address. If this option
1291                   is unset, the broadcast address of the interface will be
1292                   used. In this case, the broadcast address will be updated
1293                   during run-time if a change is detected.</para>
1294                 </listitem>
1295               </varlistentry>
1296
1297               <varlistentry>
1298                 <term><option>Ip6AddrType</option>
1299                 <replaceable>site-local</replaceable>|<replaceable>unique-local</replaceable>|<replaceable>global</replaceable></term>
1300
1301                 <listitem>
1302                   <para>This option sets the IPv6 address type to be used for
1303                   interface address detection. Defaults to
1304                   <replaceable>site-local</replaceable>.</para>
1305                 </listitem>
1306               </varlistentry>
1307
1308               <varlistentry>
1309                 <term><option>Ip6MulticastSite</option>
1310                 <replaceable>IPv6-address</replaceable></term>
1311
1312                 <listitem>
1313                   <para>If <option>Ip6AddrType</option> is set to
1314                   <replaceable>site-local</replaceable>, this setting forces
1315                   the given IPv6 broadcast address to be used as destination
1316                   address for all outgoing OLSR traffic on the interface.
1317                   .</para>
1318                 </listitem>
1319               </varlistentry>
1320
1321               <varlistentry>
1322                 <term><option>Ip6MulticastGlobal</option>
1323                 <replaceable>IPv6-address</replaceable></term>
1324
1325                 <listitem>
1326                   <para>If <option>Ip6AddrType</option> is set to
1327                   <replaceable>global</replaceable>, this setting forces the
1328                   given IPv6 broadcast address to be used as destination
1329                   address for all outgoing OLSR traffic on the interface.
1330                   .</para>
1331                 </listitem>
1332               </varlistentry>
1333
1334               <varlistentry>
1335                 <term><option>HelloInterval</option>
1336                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1337
1338                 <listitem>
1339                   <para>Sets the interval on which HELLO (RFC-mode) or
1340                   LQ_HELLO (LQ/ETX-mode) messages will be generated and
1341                   transmitted on the interface. Note, that HELLO messages are
1342                   used to detect neighbours and determine symmetric
1343                   (bi-directional) links. These messages also include the
1344                   current neighbour information and always have a TTL of 1
1345                   which prevents any forwarding.</para>
1346                 </listitem>
1347               </varlistentry>
1348
1349               <varlistentry>
1350                 <term><option>HelloValidityTime</option>
1351                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1352
1353                 <listitem>
1354                   <para>Sets the validity time to be announced in HELLO or
1355                   LQ_HELLO messages transmitted on the interface. This value
1356                   must be larger than <option>HelloInterval</option>.</para>
1357                 </listitem>
1358               </varlistentry>
1359
1360               <varlistentry>
1361                 <term><option>TcInterval</option>
1362                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1363
1364                 <listitem>
1365                   <para>Sets the interval on which TC (RFC-mode) or LQ_TC
1366                   (LQ/ETX-mode) messages will be generated and transmitted on
1367                   the interface. Note, that TC (Topology Control) messages are
1368                   used to spread topology information. These messages also
1369                   include the current neighbour information and normally have
1370                   a TTL larger than 1 to flood them through the mesh network.
1371                   TC or LQ_TC messages may be forwarded delayed to support
1372                   packet aggregation. If the
1373                   <option>LinkQualityFishEye</option> option is enabled, the
1374                   TTL for these messages is varied to faster distribute
1375                   topology information in the near neighbourhood.</para>
1376                 </listitem>
1377               </varlistentry>
1378
1379               <varlistentry>
1380                 <term><option>TcValidityTime</option>
1381                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1382
1383                 <listitem>
1384                   <para>Sets the validity time to be announced in TC or LQ_TC
1385                   messages transmitted on the interface. This value must be
1386                   larger than <option>TcInterval</option>.</para>
1387                 </listitem>
1388               </varlistentry>
1389
1390               <varlistentry>
1391                 <term><option>MidInterval</option>
1392                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1393
1394                 <listitem>
1395                   <para>Sets the interval on which MID messages will be
1396                   generated and transmitted on the interface. Note, that MID
1397                   messages spread alias information and will be emitted only
1398                   by nodes with more than one <productname>olsrd</productname>
1399                   interface.</para>
1400                 </listitem>
1401               </varlistentry>
1402
1403               <varlistentry>
1404                 <term><option>MidValidityTime</option>
1405                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1406
1407                 <listitem>
1408                   <para>Sets the validity time to be announced in MID messages
1409                   transmitted on the interface. This value must be larger than
1410                   <option>MidInterval</option>.</para>
1411                 </listitem>
1412               </varlistentry>
1413
1414               <varlistentry>
1415                 <term><option>HnaInterval</option>
1416                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1417
1418                 <listitem>
1419                   <para>Sets the interval on which HNA messages will be
1420                   generated and transmitted on the interface. Note, that HNA
1421                   messages spread gateway information and will be emitted only
1422                   by nodes with configured <option>Hna4</option> or
1423                   <option>Hna6</option> options.</para>
1424                 </listitem>
1425               </varlistentry>
1426
1427               <varlistentry>
1428                 <term><option>HnaValidityTime</option>
1429                 <replaceable>0.0</replaceable>-<replaceable>3968.0</replaceable></term>
1430
1431                 <listitem>
1432                   <para>Sets the validity time to be announced in HNA messages
1433                   transmitted on the interface. This value must be larger than
1434                   <option>HnaInterval</option>.</para>
1435                 </listitem>
1436               </varlistentry>
1437
1438               <varlistentry>
1439                 <term><option>Weight</option>
1440                 <replaceable>0</replaceable>-<replaceable>[maxint]</replaceable></term>
1441
1442                 <listitem>
1443                   <para>When multiple links exist between hosts, the
1444                   <emphasis>weight</emphasis> of the interface is used to
1445                   determine the link to route by. Normally the
1446                   <emphasis>weight</emphasis> is automatically calculated by
1447                   <productname>olsrd</productname> based on the
1448                   characteristics of the interface, but here you can specify a
1449                   fixed value. <productname>olsrd</productname> will choose
1450                   links with the lowest <emphasis>weight</emphasis>
1451                   value.</para>
1452                 </listitem>
1453               </varlistentry>
1454
1455               <varlistentry>
1456                 <term><option>LinkQualityMult</option>
1457                 <replaceable>default</replaceable>|<replaceable>neighbour-ipaddr</replaceable>
1458                 <replaceable>0.1</replaceable>-<replaceable>1.0</replaceable></term>
1459
1460                 <listitem>
1461                   <para>When using <productname>olsrd</productname> in
1462                   LQ/ETX-mode, the neighbour link cost is calculated based on
1463                   packet loss or hello message loss (see
1464                   <option>LinkQualityAlgorithm</option> option). Because the
1465                   applied measurement may not reflect the real-live connection
1466                   quality and link speed, this setting allows you to manually
1467                   fine-tune the measurement results. You can add one or more
1468                   <option>LinkQualityMult</option> options and correlate the
1469                   IP address of a neighbour with a multiplication factor. This
1470                   setting only allows you to determine bad links, e.g. a
1471                   factor of <replaceable>0.5</replaceable> basically says:
1472                   <quote>this link is only half as good as the packet loss may
1473                   indicate</quote>. For this reason, the
1474                   <replaceable>default</replaceable> keyword can be used to
1475                   lower all ETX/LQ values with a lower factor. You then define
1476                   better links by adding further entries with known IP
1477                   addresses and a higher factor.</para>
1478
1479                   <para><emphasis role="strong">Note</emphasis>: While
1480                   switching routes generally is not harmful, people tend to
1481                   fiddle with the <option>LinkQualityMult</option> setting
1482                   only because their automatically selected Internet gateway
1483                   flaps. This is a bad habit, because it disturbs the ETX/LQ
1484                   measurement and leads to sub-optimal routes for others. Try
1485                   using the <option>NatThreshold</option> option instead.
1486                   Another option is manual gateway selection either by
1487                   automatic tunneling or by using a VPN technique.</para>
1488                 </listitem>
1489               </varlistentry>
1490             </variablelist>
1491           </listitem>
1492         </varlistentry>
1493       </variablelist>
1494     </refsect1>
1495
1496     <refsect1 id="olsrd_conf_5_plugins">
1497       <title id="olsrd_conf_5_plugins-title">Plugins</title>
1498
1499       <para>The functionality of the <productname>olsrd</productname> daemon
1500       is extendable by plugins. Plugins are shared object files
1501       (<filename>*.so</filename> on Linux or <filename>*.dll</filename> on
1502       Windows) to be loaded from <productname>olsrd</productname> during
1503       startup. To load a plugin, add the appropriate
1504       <option>LoadPlugin</option> option to the config file (see <xref
1505       endterm="olsrd_conf_5_optionblocks-title"
1506       linkend="olsrd_conf_5_optionblocks" /> above). A plugin accepts zero or
1507       more parameters, which can be added by <option>PlParam</option>
1508       <replaceable>key</replaceable> <replaceable>value</replaceable>
1509       statements to the <option>LoadPlugin</option> option block. The
1510       following plugin are included with the current
1511       <productname>olsrd</productname> installation:</para>
1512
1513       <variablelist>
1514         <varlistentry>
1515           <term><option>LoadPlugin arprefresh.so.0.1 {
1516           <replaceable>...</replaceable> }</option></term>
1517
1518           <listitem>
1519             <para>This plugin refreshes the local ARP cache from received OLSR
1520             messages. This optimizes the ARP lookups otherwise required if
1521             unicast traffic is send on a previously unused link chain. The
1522             correct function requires Linux kernel 2.6. The plugin accepts no
1523             parameters.</para>
1524           </listitem>
1525         </varlistentry>
1526
1527         <varlistentry>
1528           <term><option>LoadPlugin olsrd_bmf.so.1.5.3 {
1529           <replaceable>...</replaceable> }</option></term>
1530
1531           <listitem>
1532             <para>This plugin floods IP-multicast and optional IP-broadcast
1533             traffic via the MPR chain. The multicast or broadcast traffic is
1534             grabbed from a non-OLSR interface, forwarded through the mesh and
1535             exits to another non-OLSR interface. Note, that this plugin
1536             requires multi-threading support. Also note, that this plugin has
1537             a separate source repository on <ulink
1538             url="http://olsr-bmf.sourceforge.net/">http://olsr-bmf.sourceforge.net/</ulink>
1539             . The plugin accepts the following parameters.</para>
1540
1541             <variablelist>
1542               <varlistentry>
1543                 <term><option>PlParam</option> NonOlsrIf
1544                 <replaceable>interface</replaceable></term>
1545
1546                 <listitem>
1547                   <para>As a special feature, it is possible to also forward
1548                   from and to non-OLSR interfaces. If you have network
1549                   interfaces on which <productname>olsrd</productname> is not
1550                   running, but you do want to forward multicast and
1551                   local-broadcast IP packets, specify up to 32
1552                   <option>NonOlsrIf</option> sub-options.</para>
1553                 </listitem>
1554               </varlistentry>
1555
1556               <varlistentry>
1557                 <term><option>PlParam</option> DoLocalBroadcast
1558                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
1559
1560                 <listitem>
1561                   <para>Enable or disable the flooding of local broadcast
1562                   packets (e.g. packets with IP destination 192.168.1.255).
1563                   Defaults to <replaceable>yes</replaceable>.</para>
1564                 </listitem>
1565               </varlistentry>
1566
1567               <varlistentry>
1568                 <term><option>PlParam</option> BmfInterface
1569                 <replaceable>interface</replaceable></term>
1570
1571                 <listitem>
1572                   <para>Specifies the name of the BMF network interface.
1573                   Defaults to <replaceable>bmf0</replaceable>.</para>
1574                 </listitem>
1575               </varlistentry>
1576
1577               <varlistentry>
1578                 <term><option>PlParam</option> BmfInterfaceIp
1579                 <replaceable>ipaddr/prefix</replaceable></term>
1580
1581                 <listitem>
1582                   <para>Specifies the IP address and netmask for the BMF
1583                   network interface. By default, the IP address of the first
1584                   OLSR interface is copied. The default prefix is
1585                   <replaceable>32</replaceable>.</para>
1586                 </listitem>
1587               </varlistentry>
1588
1589               <varlistentry>
1590                 <term><option>PlParam</option> CapturePacketsOnOlsrInterfaces
1591                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
1592
1593                 <listitem>
1594                   <para>Enables or disables capturing packets on the
1595                   OLSR-enabled interfaces (in promiscuous mode). The multicast
1596                   (and, if configured, local broadcast) packets sent on the
1597                   non-OLSR network interfaces and on the BMF network interface
1598                   will always be flooded over the OLSR network. If this
1599                   parameter is <replaceable>yes</replaceable>, also the
1600                   packets sent on the OLSR-enabled network interfaces will be
1601                   flooded over the OLSR network. Note, that his parameter
1602                   should be set consistently on all hosts throughout the
1603                   network. If not, hosts may receive multicast packets in
1604                   duplicate. Defaults to <replaceable>no</replaceable>.</para>
1605                 </listitem>
1606               </varlistentry>
1607
1608               <varlistentry>
1609                 <term><option>PlParam</option> BmfMechanism
1610                 <replaceable>Broadcast</replaceable>|<replaceable>UnicastPromiscuous</replaceable></term>
1611
1612                 <listitem>
1613                   <para>Determines the forwarding mechanism to use. In the
1614                   <replaceable>UnicastPromiscuous</replaceable> mode, packets
1615                   are forwarded (unicast) to the best candidate neighbor;
1616                   other neighbors listen promiscuously. IP-local broadcast is
1617                   not used. This saves air time on 802.11 WLAN networks, on
1618                   which unicast packets are usually sent at a much higher bit
1619                   rate than broadcast packets (which are sent at a basic bit
1620                   rate). Defaults to
1621                   <replaceable>Broadcast</replaceable>.</para>
1622                 </listitem>
1623               </varlistentry>
1624
1625               <varlistentry>
1626                 <term><option>PlParam</option> FanOutLimit
1627                 <replaceable>1</replaceable>-<replaceable>10</replaceable></term>
1628
1629                 <listitem>
1630                   <para>If the number of neighbors to forward to is less than
1631                   or equal to the <option>FanOutLimit</option>, then packets
1632                   to be relayed will be sent via unicast. If the number is
1633                   greater than the <option>FanOutLimit</option>, the packet
1634                   goes out as broadcast. Not used if
1635                   <option>BmfMechanism</option> is set to
1636                   <replaceable>UnicastPromiscuous</replaceable>. Defaults to
1637                   <replaceable>2</replaceable>.</para>
1638                 </listitem>
1639               </varlistentry>
1640
1641               <varlistentry>
1642                 <term><option>PlParam</option> BroadcastRetransmitCount
1643                 <replaceable>1</replaceable>-<replaceable>10</replaceable></term>
1644
1645                 <listitem>
1646                   <para>Determines the number of times BMF will transmit the
1647                   same packet whenever it decides to use broadcast to forward
1648                   a packet. Not used if <option>BmfMechanism</option> is set
1649                   to <replaceable>UnicastPromiscuous</replaceable>. Defaults
1650                   to <replaceable>1</replaceable>.</para>
1651                 </listitem>
1652               </varlistentry>
1653             </variablelist>
1654           </listitem>
1655         </varlistentry>
1656
1657         <varlistentry>
1658           <term><option>LoadPlugin olsrd_dot_draw.so.0.3 {
1659           <replaceable>...</replaceable> }</option></term>
1660
1661           <listitem>
1662             <para>This plugin can be used to query topology graphs via a
1663             network connection. To visualize the queried information, you need
1664             the <productname>GraphViz</productname> package from: <ulink
1665             url="http://www.graphviz.org/">http://www.graphviz.org/</ulink>.
1666             The plugin accepts the following parameters.</para>
1667
1668             <variablelist>
1669               <varlistentry>
1670                 <term><option>PlParam</option> port
1671                 <replaceable>1</replaceable>-<replaceable>65535</replaceable></term>
1672
1673                 <listitem>
1674                   <para>Determines the port number to be queried. Defaults to
1675                   <replaceable>2004</replaceable>.</para>
1676                 </listitem>
1677               </varlistentry>
1678
1679               <varlistentry>
1680                 <term><option>PlParam</option> accept
1681                 <replaceable>ipaddr</replaceable></term>
1682
1683                 <listitem>
1684                   <para>Determines a single IP address from which a connection
1685                   is accepted. Defaults to
1686                   <replaceable>127.0.0.1</replaceable>.</para>
1687                 </listitem>
1688               </varlistentry>
1689             </variablelist>
1690           </listitem>
1691         </varlistentry>
1692
1693         <varlistentry>
1694           <term><option>LoadPlugin olsrd_dyn_gw.so.0.4 {
1695           <replaceable>...</replaceable> }</option></term>
1696
1697           <listitem>
1698             <para>This plugin announces <quote>HNA { 0.0.0.0 0.0.0.0 }</quote>
1699             if it detects a functional static default route. The plugin
1700             constantly tests the default route using ICMP
1701             (<command>ping</command>). Note, that this plugin requires
1702             multi-threading support. Note also, that you need a static default
1703             route on the node. The plugin accepts the following
1704             parameters.</para>
1705
1706             <variablelist>
1707               <varlistentry>
1708                 <term><option>PlParam</option> interval
1709                 <replaceable>1</replaceable>-<replaceable>3600</replaceable></term>
1710
1711                 <listitem>
1712                   <para>Determines the time between ping tests. Defaults to
1713                   <replaceable>5</replaceable>.</para>
1714                 </listitem>
1715               </varlistentry>
1716
1717               <varlistentry>
1718                 <term><option>PlParam</option> ping
1719                 <replaceable>ipaddr</replaceable></term>
1720
1721                 <listitem>
1722                   <para>Adds a ping destination address. If one or more IPv4
1723                   addresses are configured, the plugin performs a ping test on
1724                   these addresses in descending order. If a ping test is
1725                   successful, subsequent addresses won't be pinged No
1726                   default.</para>
1727                 </listitem>
1728               </varlistentry>
1729
1730               <varlistentry>
1731                 <term><option>PlParam</option> hna "<replaceable>ipaddr
1732                 netmask-or-prefix</replaceable>"</term>
1733
1734                 <listitem>
1735                   <para>Specifies an optional HNA entry to be announced if the
1736                   ping test succeeds. Note, that the <option>PlParam</option>
1737                   sequence matters: to link a specific HNA entry to a ping
1738                   test, add the desired <replaceable>hna</replaceable>
1739                   parameter followed by one or more
1740                   <replaceable>ping</replaceable> parameters. Defaults to
1741                   <replaceable>0.0.0.0 0.0.0.0</replaceable>.</para>
1742                 </listitem>
1743               </varlistentry>
1744             </variablelist>
1745           </listitem>
1746         </varlistentry>
1747
1748         <varlistentry>
1749           <term><option>LoadPlugin olsrd_dyn_gw_plain.so.0.4 {
1750           <replaceable>...</replaceable> }</option></term>
1751
1752           <listitem>
1753             <para>This plugin announces <quote>HNA { 0.0.0.0 0.0.0.0 }</quote>
1754             if it detects a static default route. To maintain the default
1755             route, you need an external program such as a cron job. The plugin
1756             accepts no parameters.</para>
1757           </listitem>
1758         </varlistentry>
1759
1760         <varlistentry>
1761           <term><option>LoadPlugin olsrd_httpinfo.so.0.1 {
1762           <replaceable>...</replaceable> }</option></term>
1763
1764           <listitem>
1765             <para>This plugin can be used to query internal information via a
1766             web browser. The plugin implements a tiny HTTP server and
1767             publishes information on several pages. The plugin accepts the
1768             following parameters.</para>
1769
1770             <variablelist>
1771               <varlistentry>
1772                 <term><option>PlParam</option> port
1773                 <replaceable>1</replaceable>-<replaceable>65535</replaceable></term>
1774
1775                 <listitem>
1776                   <para>Determines the port number to be queried. No default,
1777                   <replaceable>8080</replaceable> recommended.</para>
1778                 </listitem>
1779               </varlistentry>
1780
1781               <varlistentry>
1782                 <term><option>PlParam</option> host
1783                 <replaceable>ipaddr</replaceable></term>
1784
1785                 <term><option>PlParam</option> host4
1786                 <replaceable>ipaddr</replaceable></term>
1787
1788                 <listitem>
1789                   <para>Adds a single IPv4 address to the list of allowed
1790                   source addresses. No default.</para>
1791                 </listitem>
1792               </varlistentry>
1793
1794               <varlistentry>
1795                 <term><option>PlParam</option> net "<replaceable>ipaddr
1796                 netmask</replaceable>"</term>
1797
1798                 <term><option>PlParam</option> net4 "<replaceable>ipaddr
1799                 netmask</replaceable>"</term>
1800
1801                 <listitem>
1802                   <para>Adds an IPv4 network range to the list of allowed
1803                   source addresses. No default.</para>
1804                 </listitem>
1805               </varlistentry>
1806
1807               <varlistentry>
1808                 <term><option>PlParam</option> host6
1809                 <replaceable>IPv6-address</replaceable></term>
1810
1811                 <listitem>
1812                   <para>Adds a single IPv6 address to the list of allowed
1813                   source addresses. No default.</para>
1814                 </listitem>
1815               </varlistentry>
1816
1817               <varlistentry>
1818                 <term><option>PlParam</option> net6 "<replaceable>IPv6-address
1819                 0-128</replaceable>"</term>
1820
1821                 <listitem>
1822                   <para>Adds an IPv6 network range to the list of allowed
1823                   source addresses. No default.</para>
1824                 </listitem>
1825               </varlistentry>
1826
1827               <varlistentry>
1828                 <term><option>PlParam</option> resolve
1829                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
1830
1831                 <listitem>
1832                   <para>Determines if the plugin tries to resolve IP addresses
1833                   to names when generating output. Note, that if you are using
1834                   private IP addresses in your mesh, you also need to load
1835                   <option>olsrd_nameservice.so.0.3</option> and link the local
1836                   <filename>/etc/hosts</filename> file to the
1837                   <option>hosts-file</option> generated by this plugin.
1838                   Otherwise this option slows down the plugins operation.
1839                   Defaults to <replaceable>no</replaceable>.</para>
1840                 </listitem>
1841               </varlistentry>
1842             </variablelist>
1843           </listitem>
1844         </varlistentry>
1845
1846         <varlistentry>
1847           <term><option>LoadPlugin olsrd_lq_etx_ff.so.0.1 {
1848           <replaceable>...</replaceable> }</option></term>
1849
1850           <listitem>
1851             <para>This plugin realized the LQ/ETX detection algorithm based on
1852             OLSR packet loss. This algorithm is compatible to the LQ
1853             calculation used by previous versions of
1854             <productname>olsrd</productname>, so this algorithm is also the
1855             compiled-in default. Note, that <productname>olsrd</productname>
1856             needs to send large signaling packet for this to work optimal,
1857             which is only true if you have a larger mesh (&gt;50 nodes). The
1858             plugin accepts no parameters.</para>
1859           </listitem>
1860         </varlistentry>
1861
1862         <varlistentry>
1863           <term><option>LoadPlugin olsrd_lq_etx_float.so.0.1 {
1864           <replaceable>...</replaceable> }</option></term>
1865
1866           <listitem>
1867             <para>This plugin calculates the link quality based on HELLO and
1868             LQ_HELLO message loss. While calculating, it uses floating point
1869             math. Note, that HELLO messages trigger a send-buffer-flush, so
1870             basically HELLOs are sent in small packets. Because the packet
1871             loss for small packets is much lower than for large packets, these
1872             algorithms may not discover optimal routes. The plugin accepts the
1873             following parameters.</para>
1874
1875             <variablelist>
1876               <varlistentry>
1877                 <term><option>PlParam</option> LinkQualityAging
1878                 <replaceable>0.01</replaceable>-<replaceable>1.0</replaceable></term>
1879
1880                 <listitem>
1881                   <para>This setting controls the LQ/ETX change speed for the
1882                   plugin. A higher value will result in faster LQ/ETX changes.
1883                   Defaults to <replaceable>0.1</replaceable>.</para>
1884                 </listitem>
1885               </varlistentry>
1886             </variablelist>
1887           </listitem>
1888         </varlistentry>
1889
1890         <varlistentry>
1891           <term><option>LoadPlugin olsrd_lq_etx_fpm.so.0.1 {
1892           <replaceable>...</replaceable> }</option></term>
1893
1894           <listitem>
1895             <para>This plugin calculates the link quality based on HELLO and
1896             LQ_HELLO message loss. While calculating, it uses integer-based
1897             fixed point math (FPM). Note, that HELLO messages trigger a
1898             send-buffer-flush, so basically HELLOs are sent in small packets.
1899             Because the packet loss for small packets is much lower than for
1900             large packets, these algorithms may not discover optimal routes.
1901             The plugin accepts the following parameters.</para>
1902
1903             <variablelist>
1904               <varlistentry>
1905                 <term><option>PlParam</option> LinkQualityAging
1906                 <replaceable>0.01</replaceable>-<replaceable>1.0</replaceable></term>
1907
1908                 <listitem>
1909                   <para>This setting controls the LQ/ETX change speed for the
1910                   plugin. A higher value will result in faster LQ/ETX changes.
1911                   Defaults to <replaceable>0.1</replaceable>.</para>
1912                 </listitem>
1913               </varlistentry>
1914             </variablelist>
1915           </listitem>
1916         </varlistentry>
1917
1918         <varlistentry>
1919           <term><option>LoadPlugin olsrd_lq_etx_rfc.so.0.1 {
1920           <replaceable>...</replaceable> }</option></term>
1921
1922           <listitem>
1923             <para>This plugin realizes the hop-optimized metric required by
1924             RFC 3626. You can load this plugin if you require standard-conform
1925             operation.</para>
1926
1927             <variablelist>
1928               <varlistentry>
1929                 <term><option>PlParam</option> UseHysteresis
1930                 <replaceable>yes</replaceable>|<replaceable>no</replaceable></term>
1931
1932                 <listitem>
1933                   <para>If set to <replaceable>yes,</replaceable> hysteresis
1934                   will be used as explained in section 14 of RFC 3626. The
1935                   setting determines if hysteresis is used. Defaults to
1936                   <replaceable>no</replaceable>.</para>
1937                 </listitem>
1938               </varlistentry>
1939
1940               <varlistentry>
1941                 <term><option>PlParam</option> HystScaling
1942                 <replaceable>0.01</replaceable>-<replaceable>0.99</replaceable></term>
1943
1944                 <listitem>
1945                   <para>Sets the scaling value used by the hysteresis
1946                   algorithm. This must be a positive floating point value
1947                   smaller than <replaceable>1.0</replaceable>. Consult RFC
1948                   3626 for details. Defaults to
1949                   <replaceable>0.5</replaceable>.</para>
1950                 </listitem>
1951               </varlistentry>
1952
1953               <varlistentry>
1954                 <term><option>PlParam</option> HystThrHigh
1955                 <replaceable>0.0</replaceable>-<replaceable>1.0</replaceable></term>
1956
1957                 <listitem>
1958                   <para>This option sets the upper threshold for accepting a
1959                   link in hysteresis calculation. The value must be higher
1960                   than the one set as the lower threshold. Defaults to
1961                   <replaceable>0.8</replaceable>.</para>
1962                 </listitem>
1963               </varlistentry>
1964
1965               <varlistentry>
1966                 <term><option>PlParam</option> HystThrLow
1967                 <replaceable>0.0</replaceable>-<replaceable>1.0</replaceable></term>
1968
1969                 <listitem>
1970                   <para>This option sets the lower threshold for setting a
1971                   link to asymmetric using hysteresis. The value must be lower
1972                   than the one set as the upper threshold. Defaults to
1973                   <replaceable>0.3</replaceable>.</para>
1974                 </listitem>
1975               </varlistentry>
1976             </variablelist>
1977           </listitem>
1978         </varlistentry>
1979
1980         <varlistentry>
1981           <term><option>LoadPlugin olsrd_mini.so.0.1 {
1982           <replaceable>...</replaceable> }</option></term>
1983
1984           <listitem>
1985             <para>This plugin is an example to be copied if you want to
1986             program a new plugin. The plugin accepts the following
1987             parameters.</para>
1988
1989             <variablelist>
1990               <varlistentry>
1991                 <term><option>PlParam</option> test
1992                 "<replaceable>some-text</replaceable>"</term>
1993
1994                 <listitem>
1995                   <para>Prints out some text during plugin initialization. No
1996                   default.</para>
1997                 </listitem>
1998               </varlistentry>
1999             </variablelist>
2000           </listitem>
2001         </varlistentry>
2002
2003         <varlistentry>
2004           <term><option>LoadPlugin olsrd_nameservice.so.0.3 {
2005           <replaceable>...</replaceable> }</option></term>
2006
2007           <listitem>
2008             <para>This plugin floods node information through the mesh
2009             piggy-backed on the OLSR protocol. It also collects information
2010             received by other nodes and stores that information in different
2011             text files on a regularly basis. The plugin accepts the following
2012             parameters.</para>
2013
2014             <variablelist>
2015               <title>General</title>
2016
2017               <varlistentry>
2018                 <term><option>PlParam</option> interval
2019                 <replaceable>1</replaceable>-<replaceable>3968</replaceable></term>
2020
2021                 <listitem>
2022                   <para>Determines the interval for sending NAME messages in
2023                   seconds. Defaults to <replaceable>120</replaceable> (2
2024                   minutes).</para>
2025                 </listitem>
2026               </varlistentry>
2027
2028               <varlistentry>
2029                 <term><option>PlParam</option> timeout
2030                 <replaceable>1.0</replaceable>-<replaceable>3968.0</replaceable></term>
2031
2032                 <listitem>
2033                   <para>Determines the validity time for received NAME
2034                   messages in seconds. Defaults to
2035                   <replaceable>1800.0</replaceable> (30 minutes)</para>
2036                 </listitem>
2037               </varlistentry>
2038             </variablelist>
2039
2040             <variablelist>
2041               <title>Host Names</title>
2042
2043               <varlistentry>
2044                 <term><option>PlParam</option> name
2045                 <replaceable>hostname</replaceable></term>
2046
2047                 <listitem>
2048                   <para>Configures a host name for the
2049                   <productname>olsrd</productname> node. This name together
2050                   with the main IP address of <productname>olsrd</productname>
2051                   is flooded though the mesh. You can specify this parameter
2052                   more than once to flood different names. No default.</para>
2053                 </listitem>
2054               </varlistentry>
2055
2056               <varlistentry>
2057                 <term><option>PlParam</option> suffix
2058                 <replaceable>dotname</replaceable></term>
2059
2060                 <listitem>
2061                   <para>Configures a suffix which is appended to all received
2062                   names. No default, but <replaceable>.olsr</replaceable>
2063                   (with a dot) is recommended to prevent DNS name
2064                   spoofing.</para>
2065                 </listitem>
2066               </varlistentry>
2067
2068               <varlistentry>
2069                 <term><option>PlParam</option> hosts-file
2070                 <replaceable>filename</replaceable></term>
2071
2072                 <listitem>
2073                   <para>The plugin writes received IP addresses and names to a
2074                   resolver compatible file which is updated on a regularly
2075                   basis. To overwrite the local hosts file, specify
2076                   <filename>/etc/hosts</filename> (Linux, BSD) or
2077                   <filename>c:\\windows\\system32\\drivers\\etc\\hosts</filename>
2078                   (Windows). Defaults to
2079                   <filename>/var/run/hosts_olsr</filename> (Linux, BSD) or
2080                   <filename>c:\windows\hosts_olsr</filename> (Windows).</para>
2081                 </listitem>
2082               </varlistentry>
2083
2084               <varlistentry>
2085                 <term><option>PlParam</option> add-hosts
2086                 <replaceable>filename</replaceable></term>
2087
2088                 <listitem>
2089                   <para>Configures a file which contents are appended when
2090                   writing the <option>hosts-file</option>. If
2091                   <productname>olsrd</productname> is configured to overwrite
2092                   your /etc/hosts file, you may rename your current /etc/hosts
2093                   file and configure this parameter to preserve any static
2094                   entries. No default.</para>
2095                 </listitem>
2096               </varlistentry>
2097
2098               <varlistentry>
2099                 <term><option>PlParam</option> name-change-script
2100                 <replaceable>filename</replaceable></term>
2101
2102                 <listitem>
2103                   <para>Configures a shell script which is executed after
2104                   updating the <option>hosts-file</option>. Can be used to
2105                   update a website or database. No default.</para>
2106                 </listitem>
2107               </varlistentry>
2108
2109               <varlistentry>
2110                 <term><option>PlParam</option> sighup-pid-file
2111                 <replaceable>filename</replaceable></term>
2112
2113                 <listitem>
2114                   <para>Sends a SIGHUP to the process specified by the pidfile
2115                   (usually <filename>/var/run/dnsmasq.pid</filename>) when the
2116                   host name table changes. This is useful for letting
2117                   <productname>dnsmasq</productname> or
2118                   <productname>bind</productname> know they have to reload
2119                   their hosts file. Linux or BSD only, no default.</para>
2120                 </listitem>
2121               </varlistentry>
2122
2123               <varlistentry>
2124                 <term><option>PlParam</option>
2125                 <replaceable>[ipaddr]</replaceable>
2126                 <replaceable>hostname</replaceable></term>
2127
2128                 <listitem>
2129                   <para>Adds a host name to be announced for the specified IP
2130                   address. Note, that this parameter is not commonly used,
2131                   specify the <option>name</option> parameter instead (see
2132                   above). The IP address has to be either from one of the
2133                   <productname>olsrd</productname> interfaces or within a
2134                   configured HNA network. This parameter can be specified
2135                   multiple times. No default.</para>
2136                 </listitem>
2137               </varlistentry>
2138             </variablelist>
2139
2140             <variablelist>
2141               <title>Services</title>
2142
2143               <varlistentry>
2144                 <term><option>PlParam</option> service
2145                 "<replaceable>announcement</replaceable>"</term>
2146
2147                 <listitem>
2148                   <para>Floods the configured service announcement through the
2149                   mesh. The announcement must include 3 fields separated with
2150                   a pipe character:
2151                   <replaceable>URL</replaceable>|<replaceable>Protocol</replaceable>|<replaceable>Description</replaceable>.
2152                   The <replaceable>URL</replaceable> field needs to start with
2153                   a protocol id, determines an IP or host.suffix combination
2154                   and adds a port number. Examples:
2155                   <quote>http://10.0.0.1:80</quote> or
2156                   <quote>ftp://myname.olsr:20</quote>.
2157                   <productname>olsrd</productname> also checks, if the address
2158                   is a local IP address, is included with any configured HNA
2159                   range, or is equal to a configured <option>name</option> and
2160                   <option>suffix</option> parameter. The
2161                   <replaceable>Protocol</replaceable> field indicates either
2162                   <replaceable>tcp</replaceable> or
2163                   <replaceable>udp</replaceable>. Use any non-empty text for
2164                   the <replaceable>Description</replaceable> field. You can
2165                   specify this parameter more than once to flood different
2166                   services. No default.</para>
2167                 </listitem>
2168               </varlistentry>
2169
2170               <varlistentry>
2171                 <term><option>PlParam</option> services-file
2172                 <replaceable>filename</replaceable></term>
2173
2174                 <listitem>
2175                   <para>The plugin writes received service announcements to a
2176                   file which is updated on a regularly basis. Defaults to
2177                   <filename>/var/run/services_olsr</filename> (Linux, BSD) or
2178                   <filename>c:\windows\services_olsr</filename>
2179                   (Windows).</para>
2180                 </listitem>
2181               </varlistentry>
2182
2183               <varlistentry>
2184                 <term><option>PlParam</option> services-change-script
2185                 <replaceable>filename</replaceable></term>
2186
2187                 <listitem>
2188                   <para>Configures a shell script which is executed after
2189                   updating the <option>services-file</option>. No
2190                   default.</para>
2191                 </listitem>
2192               </varlistentry>
2193             </variablelist>
2194
2195             <variablelist>
2196               <title>MAC Addresses</title>
2197
2198               <varlistentry>
2199                 <term><option>PlParam</option> mac
2200                 <replaceable>xx:xx:xx:xx:xx:xx[,0-255]</replaceable></term>
2201
2202                 <listitem>
2203                   <para>Floods the configured MAC address through the mesh.
2204                   This MAC address may be used to fine control captive portal
2205                   solutions based on MAC adresses. The optional decimal number
2206                   designates a class. You can specify this parameter more than
2207                   once to flood different MAC addresses. No default.</para>
2208                 </listitem>
2209               </varlistentry>
2210
2211               <varlistentry>
2212                 <term><option>PlParam</option> macs-file
2213                 <replaceable>filename</replaceable></term>
2214
2215                 <listitem>
2216                   <para>The plugin writes received MAC adresses to a file
2217                   which is updated on a regularly basis. Defaults to
2218                   <filename>/var/run/macs_olsr</filename> (Linux, BSD) or
2219                   <filename>c:\windows\macs_olsr</filename> (Windows).</para>
2220                 </listitem>
2221               </varlistentry>
2222
2223               <varlistentry>
2224                 <term><option>PlParam</option> macs-change-script
2225                 <replaceable>filename</replaceable></term>
2226
2227                 <listitem>
2228                   <para>Configures a shell script which is executed after
2229                   updating the <option>macs-file</option>. No default.</para>
2230                 </listitem>
2231               </varlistentry>
2232             </variablelist>
2233
2234             <variablelist>
2235               <title>DNS Forwarders</title>
2236
2237               <varlistentry>
2238                 <term><option>PlParam</option> dns-server
2239                 <replaceable>ipaddr</replaceable></term>
2240
2241                 <listitem>
2242                   <para>Announces the configured IP address which should
2243                   indicate a DNS server or DNS forwarder. If you configure
2244                   <replaceable>0.0.0.0</replaceable>, the main IP address of
2245                   <productname>olsrd</productname> will be replaced. Other
2246                   running <productname>olsrd</productname> instances will
2247                   receive a list of announced DNS server IP addresses, select
2248                   the currently best reachable IP address, and write the
2249                   selected IP address to the <option>resolv-file</option>
2250                   file.</para>
2251                 </listitem>
2252               </varlistentry>
2253
2254               <varlistentry>
2255                 <term><option>PlParam</option> resolv-file
2256                 <replaceable>filename</replaceable></term>
2257
2258                 <listitem>
2259                   <para>Defaults to
2260                   <filename>/var/run/resolvconf_olsr</filename> (Linux, BSD)
2261                   or <filename>c:\windows\resolvconf_olsr</filename>
2262                   (Windows).</para>
2263                 </listitem>
2264               </varlistentry>
2265             </variablelist>
2266
2267             <variablelist>
2268               <title>GPS Positions</title>
2269
2270               <varlistentry>
2271                 <term><option>PlParam</option> lat
2272                 <replaceable>latitude</replaceable></term>
2273
2274                 <listitem>
2275                   <para>Configures a decimal float value (latitude) for this
2276                   node to be flooded in the mesh. No default.</para>
2277                 </listitem>
2278               </varlistentry>
2279
2280               <varlistentry>
2281                 <term><option>PlParam</option> lon
2282                 <replaceable>longitude</replaceable></term>
2283
2284                 <listitem>
2285                   <para>Configures a decimal float value (longitude) for this
2286                   node to be flooded in the mesh. No default.</para>
2287                 </listitem>
2288               </varlistentry>
2289
2290               <varlistentry>
2291                 <term><option>PlParam</option> latlon-file
2292                 <replaceable>filename</replaceable></term>
2293
2294                 <listitem>
2295                   <para>The plugin writes received positions to a file which
2296                   is updated on a regularly basis. The file format provides
2297                   javascript-compatible function calls ready for inclusion to
2298                   a web page. The file is written only, if the
2299                   <option>lat</option> and <option>lon</option> parameters are
2300                   set. Defaults to <filename>/var/run/latlon.js</filename>
2301                   (Linux, BSD) or <filename>c:\windows\latlon.js</filename>
2302                   (Windows).</para>
2303                 </listitem>
2304               </varlistentry>
2305
2306               <varlistentry>
2307                 <term><option>PlParam</option> latlon-infile
2308                 <replaceable>filename</replaceable></term>
2309
2310                 <listitem>
2311                   <para>Configures a file to read positions from. This
2312                   parameter is meant to be used by a moving GPS receiver,
2313                   which may write comma separated decimal latitude and
2314                   longitude to this file. This will overwrite the
2315                   <option>lat</option> and <option>lon</option> parameters
2316                   during runtime. No default.</para>
2317                 </listitem>
2318               </varlistentry>
2319             </variablelist>
2320           </listitem>
2321         </varlistentry>
2322
2323         <varlistentry>
2324           <term><option>LoadPlugin olsrd_quagga.so.0.2.2 {
2325           <replaceable>...</replaceable> }</option></term>
2326
2327           <listitem>
2328             <para>This plugin allows you to import or export
2329             <productname>olsrd</productname> routing information from or to
2330             the <productname>quagga</productname> routing daemon (see <ulink
2331             url="http://www.quagga.net/">http://www.quagga.net/</ulink>). You
2332             need a patched and running <productname>quagga</productname>
2333             routing daemon to load this plugin successfully. The plugin
2334             accepts the following parameters.</para>
2335
2336             <variablelist>
2337               <varlistentry>
2338                 <term><option>PlParam</option> redistribute
2339                 <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>
2340
2341                 <listitem>
2342                   <para>Notifies <productname>Zebra</productname> to add a
2343                   specific protocol for redistribution. You may add this
2344                   parameter more than once.</para>
2345                 </listitem>
2346               </varlistentry>
2347
2348               <varlistentry>
2349                 <term><option>PlParam</option> ExportRoutes
2350                 <replaceable>only/both</replaceable></term>
2351
2352                 <listitem>
2353                   <para>Determines, if <productname>olsrd</productname> should
2354                   <replaceable>only</replaceable> export routes to
2355                   <productname>quagga</productname> or should export routes to
2356                   <replaceable>both</replaceable>
2357                   <productname>quagga</productname> and kernel. If this
2358                   parameter is unset, no routes are exported to
2359                   <productname>quagga</productname>.</para>
2360                 </listitem>
2361               </varlistentry>
2362
2363               <varlistentry>
2364                 <term><option>PlParam</option> Distance
2365                 <replaceable>0</replaceable>-<replaceable>255</replaceable></term>
2366
2367                 <listitem>
2368                   <para>Configures the administrative distance for routes
2369                   exported to <productname>Zebra</productname>. Defaults to
2370                   <replaceable>0</replaceable>.</para>
2371                 </listitem>
2372               </varlistentry>
2373
2374               <varlistentry>
2375                 <term><option>PlParam</option> LocalPref
2376                 <replaceable>yes</replaceable>|<replaceable>true</replaceable>|<replaceable>no</replaceable>|<replaceable>false</replaceable></term>
2377
2378                 <listitem>
2379                   <para>Sets the SELECTED flag on the routes exported to
2380                   <productname>Zebra</productname> which means these routes
2381                   are preferred in any case. Defaults to
2382                   <replaceable>no</replaceable>.</para>
2383                 </listitem>
2384               </varlistentry>
2385             </variablelist>
2386           </listitem>
2387         </varlistentry>
2388
2389         <varlistentry>
2390           <term><option>LoadPlugin olsrd_secure.so.0.5 {
2391           <replaceable>...</replaceable> }</option></term>
2392
2393           <listitem>
2394             <para>This plugin uses a secret pre shared key for signature
2395             generation and verification of incoming OLSR messages. All nodes
2396             that participate in an OLSR routing domain need to use the same
2397             key. The key as a size of 128-bits and is read in from a key file
2398             which should contain 16 bytes of binary data. The plugin accepts
2399             the following parameters.</para>
2400
2401             <variablelist>
2402               <varlistentry>
2403                 <term><option>PlParam</option> keyfile
2404                 <replaceable>filename</replaceable></term>
2405
2406                 <listitem>
2407                   <para>Configure a filename to read the pre shared key from.
2408                   Defaults to
2409                   <filename>/etc/olsrd.d/olsrd_secure_key</filename>.</para>
2410                 </listitem>
2411               </varlistentry>
2412             </variablelist>
2413           </listitem>
2414         </varlistentry>
2415
2416         <varlistentry>
2417           <term><option>LoadPlugin olsrd_txtinfo.so.0.1 {
2418           <replaceable>...</replaceable> }</option></term>
2419
2420           <listitem>
2421             <para>This plugin can be used to query internal information via
2422             the <guilabel>wget</guilabel> command. This plugin is a de-bloated
2423             and scriptable version of the httpinfo-Plugin. Example usage:
2424             <command>wget -q -O - http://localhost:2006/neighbours</command>
2425             to display the current neighbour table. The plugin accepts the
2426             following parameters.</para>
2427
2428             <variablelist>
2429               <varlistentry>
2430                 <term><option>PlParam</option> port
2431                 <replaceable>1</replaceable>-<replaceable>65535</replaceable></term>
2432
2433                 <listitem>
2434                   <para>Determines the port number to be queried. Defaults to
2435                   <replaceable>2006</replaceable>.</para>
2436                 </listitem>
2437               </varlistentry>
2438
2439               <varlistentry>
2440                 <term><option>PlParam</option> accept
2441                 <replaceable>ipaddr</replaceable></term>
2442
2443                 <listitem>
2444                   <para>Adds a single IP address to the list of allowed source
2445                   addresses. Defaults to <replaceable>127.0.0.1</replaceable>
2446                   for IPv4 or <replaceable>::1</replaceable> for IPv6.</para>
2447                 </listitem>
2448               </varlistentry>
2449             </variablelist>
2450           </listitem>
2451         </varlistentry>
2452
2453         <varlistentry>
2454           <term><option>LoadPlugin olsrd_watchdog.so.0.1 {
2455           <replaceable>...</replaceable> }</option></term>
2456
2457           <listitem>
2458             <para>This plugin writes the current time to a file on a regularly
2459             basis. This can be used to detect a freezed instance of
2460             <productname>olsrd</productname> by an external script or cron
2461             job. The plugin accepts the following parameters.</para>
2462
2463             <variablelist>
2464               <varlistentry>
2465                 <term><option>PlParam</option> file
2466                 <replaceable>filename</replaceable></term>
2467
2468                 <listitem>
2469                   <para>Determines the file to be written. Defaults to
2470                   <filename>/tmp/olsr.watchdog</filename>.</para>
2471                 </listitem>
2472               </varlistentry>
2473
2474               <varlistentry>
2475                 <term><option>PlParam</option> interval
2476                 <replaceable>1</replaceable>-<replaceable>3600</replaceable></term>
2477
2478                 <listitem>
2479                   <para>Determines the update interval in seconds. Defaults to
2480                   <replaceable>5</replaceable>.</para>
2481                 </listitem>
2482               </varlistentry>
2483             </variablelist>
2484           </listitem>
2485         </varlistentry>
2486       </variablelist>
2487     </refsect1>
2488
2489     <refsect1>
2490       <title>Misc</title>
2491
2492       <para>The homepage of <productname>olsrd</productname> is <ulink
2493       url="http://www.olsr.org">http://www.olsr.org</ulink></para>
2494     </refsect1>
2495
2496     <refsect1>
2497       <title>Files</title>
2498
2499       <para><filename>/etc/olsrd.conf</filename></para>
2500     </refsect1>
2501
2502     <refsect1>
2503       <title>See Also</title>
2504
2505       <simplelist type="inline">
2506         <member><xref endterm="olsrd_8-title" linkend="olsrd_8" /><xref
2507         endterm="olsrd_metrics_3-title" linkend="olsrd_metrics_3" /></member>
2508       </simplelist>
2509     </refsect1>
2510   </refentry>
2511
2512   <refentry id="olsrd_metrics_3">
2513     <indexterm>
2514       <primary><productname>olsrd-metrics</productname></primary>
2515     </indexterm>
2516
2517     <refentryinfo>
2518       <titleabbrev><productname>olsrd</productname> Metrics
2519       Plugin</titleabbrev>
2520
2521       <authorgroup>
2522         <author>
2523           <firstname>Leon Aaron</firstname>
2524
2525           <surname>Kaplan</surname>
2526
2527           <email>aaron@lo-res.org</email>
2528         </author>
2529
2530         <author>
2531           <firstname>Henning</firstname>
2532
2533           <surname>Rogge</surname>
2534
2535           <email>rogge@fgan.de</email>
2536         </author>
2537       </authorgroup>
2538     </refentryinfo>
2539
2540     <refmeta>
2541       <refentrytitle id="olsrd_metrics_3-title">olsrd-metrics
2542       plugin</refentrytitle>
2543
2544       <manvolnum>3</manvolnum>
2545     </refmeta>
2546
2547     <refnamediv>
2548       <refname>olsrd-metrics</refname>
2549
2550       <refpurpose>How to write your own metrics plugin</refpurpose>
2551     </refnamediv>
2552
2553     <refsect1>
2554       <title>Description</title>
2555
2556       <para>The idea behind the <filename
2557       class="directory">lib/lq_*</filename> is that you can write your own
2558       Link Quality (LQ) metric mostly independent of the main
2559       <productname>olsrd</productname> code.</para>
2560
2561       <para>What is a metric? A metric is a notion of "distance" between nodes
2562       in the mesh. Mobile ad hoc network (MANET) research identified the area
2563       of finding proper metrics for a MANET as one of the most important
2564       routing decisions. A metric basically determines the path that packets
2565       will take. The Shortest Path First (SPF, also sometimes called Dijkstra
2566       Algorithm) will chose the shortest sum of all possible paths. So what
2567       paths do we want to chose in WLAN MANET networks?</para>
2568
2569       <para>In general we want to have a little collisions as possible since
2570       802.11a/b/g is a broadcast medium by nature. When you compare the very
2571       old Ethernet systems (coax cable, http://en.wikipedia.org/wiki/10BASE2)
2572       you can observe that at a certain percentage of cable utilization (as
2573       low as 40%), you would get many collisions (since the coax cable is a
2574       broadcast medium just as WLAN!) and the total throughput would collapse
2575       to nearly zero.</para>
2576
2577       <para>Another choice for metrics might be signal strength.</para>
2578
2579       <para>Currently <productname>olsrd</productname> (as of Oct-2008)
2580       implements the following metric:</para>
2581
2582       <itemizedlist>
2583         <listitem>
2584           <para>RFC 3626 conforming hop count (each link has the metric value
2585           "1")</para>
2586         </listitem>
2587
2588         <listitem>
2589           <para>ETX_default_ff (ETX from MIT roofnet, with FunkFeuer.at
2590           extensions)</para>
2591         </listitem>
2592
2593         <listitem>
2594           <para>ETX_default_float (ETX with floating point arithmetic)</para>
2595         </listitem>
2596
2597         <listitem>
2598           <para>ETX_default_fpm (ETX with fixed point maths (integer). Much
2599           faster on small embedded devices!</para>
2600         </listitem>
2601       </itemizedlist>
2602     </refsect1>
2603
2604     <refsect1>
2605       <title>Getting Started</title>
2606
2607       <para>Start by reading <filename>src/lq_plugin.c</filename> and
2608       <filename>lq_plugin.h</filename>. Note, that struct
2609       <type>lq_handler</type>: is a pseudo C++ structure ;-) there is a
2610       pointer table to functions so that the plugin system knows which
2611       functions it should jump to.</para>
2612
2613       <programlisting>struct lq_handler {
2614  ...
2615   /*
2616    * number of bytes we need per hello in the hello DB for this specific 
2617    * metric. This has nothing to do what is being sent over the net. This 
2618    * is only so that you can use the structure itself to store your 
2619    * metric data
2620    */
2621   size_t hello_lq_size;
2622   size_t tc_lq_size;
2623 };</programlisting>
2624
2625       <para>Almost all functions accept a void pointer. This now points to the
2626       beginning of the custom memory area that you allocated with the
2627       tc_lq_size or hello_lq_size above.</para>
2628
2629       <para>Now...: if you want to write your own metric then you must define
2630       your own struct lq_handler and pass that variable to:</para>
2631
2632       <programlisting>void register_lq_handler(struct lq_handler *handler, const char *name);</programlisting>
2633
2634       <para>for example:</para>
2635
2636       <programlisting>struct lq_handler my_lq_metric;
2637
2638 ... // init my_lq_metric fully (every function must be assigned)
2639
2640 register_lq_handler(&amp;my_lq_metric, "my_lq_metric");</programlisting>
2641
2642       <para>For another example, take a look at
2643       <filename>lq_plugin_default_float.[ch]</filename> There it is done like
2644       this:</para>
2645
2646       <programlisting>/* Default lq plugin settings */
2647 struct lq_handler lq_etx_float_handler = {
2648   &amp;default_lq_initialize_float,
2649   
2650   &amp;default_lq_calc_cost_float,
2651   &amp;default_lq_calc_cost_float,
2652   
2653   &amp;default_lq_is_relevant_costchange_float,
2654   
2655   &amp;default_lq_packet_loss_worker_float,
2656   &amp;default_lq_memorize_foreign_hello_float,
2657   &amp;default_lq_copy_link2tc_float,
2658   &amp;default_lq_clear_float,
2659   &amp;default_lq_clear_float,
2660
2661 ...
2662   sizeof(struct default_lq_float),
2663   sizeof(struct default_lq_float)
2664 };</programlisting>
2665
2666       <para>This means, we use the <literal>sizeof(struct
2667       default_lq_float)</literal> as extra memory space in the hello database
2668       and a sizeof(struct default_lq_fload) as extra space in the TC
2669       database.</para>
2670     </refsect1>
2671
2672     <refsect1>
2673       <title>Function Reference</title>
2674
2675       <para>The other entries here are pointers to functions which are defined
2676       in the .h file. Now lets have a look at the functions.</para>
2677
2678       <variablelist>
2679         <varlistentry>
2680           <term>void (*initialize)(void);</term>
2681
2682           <listitem>
2683             <para>This callback will be called when the <xref
2684             endterm="olsrd_conf_5-title" linkend="olsrd_conf_5" /> selects
2685             this routing metric plugin. For example:</para>
2686
2687             <programlisting>#LinkQualityAlgorithm "etx_ff"</programlisting>
2688
2689             <para>The initializing function for example starts some timers and
2690             it reserves a callback which is triggered for each packet. In
2691             general you can use any initialization code in this
2692             callback.</para>
2693           </listitem>
2694         </varlistentry>
2695
2696         <varlistentry>
2697           <term>olsr_linkcost(*calc_hello_cost) (const void *lq);</term>
2698
2699           <listitem>
2700             <para>This callback will be called whenever a packet is
2701             processed.</para>
2702
2703             <para>You will get a pointer to your part of the hello database
2704             and your plugin is supposed to generate a hello cost in the
2705             standard format from the internal representation: the core format
2706             is a 32 bit unsigned integer . This then is used for adding up the
2707             costs in the Dijkstra calculation. So be sure that you do not use
2708             values greater than 2^24 . Otherwise for very long routes (256
2709             hops) this will then add up in the internal representation so that
2710             there will be integer overflows. So stay below 2^24(*). The base
2711             of the cost is your business. For example, to represent fixed
2712             point arithmetic you might multiply your (float) hello costs by
2713             256 and treat the least significant byte as the digits behind the
2714             point.</para>
2715
2716             <para>(*) or actually even better: us the constant
2717             LINK_COST_BROKEN from <filename>lq_plugin.h</filename></para>
2718           </listitem>
2719         </varlistentry>
2720
2721         <varlistentry>
2722           <term>olsr_linkcost(*calc_tc_cost) (const void *lq);</term>
2723
2724           <listitem>
2725             <para>This callback will be called whenever a packet is
2726             processed.</para>
2727
2728             <para>Same as for <function>calc_hello_cost</function> but just
2729             for TC costs and not for hellos.</para>
2730           </listitem>
2731         </varlistentry>
2732
2733         <varlistentry>
2734           <term>bool(*is_relevant_costchange) (olsr_linkcost c1, olsr_linkcost
2735           c2);</term>
2736
2737           <listitem>
2738             <para>This callback is called after the main loop whenever the
2739             core has to decide if a new Dijkstra needs to be calculated. In
2740             principle for every packet.</para>
2741
2742             <para>If a link quality does only change slightly, there will be
2743             no recalculation of the Dijkstra algorithm which costs a lot of
2744             CPU. Since only the plugin knows the range of the link quality
2745             values, only the plugin can decide if the cost change is relevant
2746             enough.</para>
2747
2748             <para>Return values: true or false.</para>
2749           </listitem>
2750         </varlistentry>
2751
2752         <varlistentry>
2753           <term>olsr_linkcost(*packet_loss_handler) (struct link_entry *
2754           entry, void *lq, bool lost);</term>
2755
2756           <listitem>
2757             <para>...</para>
2758           </listitem>
2759         </varlistentry>
2760
2761         <varlistentry>
2762           <term>void (*memorize_foreign_hello) (void *local, void
2763           *foreign);</term>
2764
2765           <listitem>
2766             <para>...</para>
2767           </listitem>
2768         </varlistentry>
2769
2770         <varlistentry>
2771           <term>void (*copy_link_lq_into_tc) (void *target, void
2772           *source);</term>
2773
2774           <listitem>
2775             <para>This callback is called when Hello packet's LQ is copied
2776             over into a TC. Since this can have a different representation,
2777             this function can be used to convert representations.</para>
2778           </listitem>
2779         </varlistentry>
2780
2781         <varlistentry>
2782           <term>void (*clear_hello) (void *target);</term>
2783
2784           <listitem>
2785             <para>...</para>
2786           </listitem>
2787         </varlistentry>
2788
2789         <varlistentry>
2790           <term>void (*clear_tc) (void *target);</term>
2791
2792           <listitem>
2793             <para>...</para>
2794           </listitem>
2795         </varlistentry>
2796
2797         <varlistentry>
2798           <term>int (*serialize_hello_lq) (unsigned char *buff, void
2799           *lq);</term>
2800
2801           <listitem>
2802             <para>...</para>
2803           </listitem>
2804         </varlistentry>
2805
2806         <varlistentry>
2807           <term>int (*serialize_tc_lq) (unsigned char *buff, void *lq);</term>
2808
2809           <listitem>
2810             <para>...</para>
2811           </listitem>
2812         </varlistentry>
2813
2814         <varlistentry>
2815           <term>void (*deserialize_hello_lq) (const uint8_t ** curr, void
2816           *lq);</term>
2817
2818           <listitem>
2819             <para>...</para>
2820           </listitem>
2821         </varlistentry>
2822
2823         <varlistentry>
2824           <term>void (*deserialize_tc_lq) (const uint8_t ** curr, void
2825           *lq);</term>
2826
2827           <listitem>
2828             <para>This callback is called whenever a packet needs to be
2829             deserialized (for every packet and there for every neighbor in the
2830             TC).</para>
2831
2832             <para>This function reads the lq information of a binary packet
2833             into a TC.</para>
2834           </listitem>
2835         </varlistentry>
2836
2837         <varlistentry>
2838           <term>const char *(*print_hello_lq) (void *ptr, char separator,
2839           struct lqtextbuffer * buffer);</term>
2840
2841           <listitem>
2842             <para>This callback is called whenever any other part of the code
2843             wants to convert your internal metric representation of Hellos
2844             into a printable version. So it can be called at any time.</para>
2845
2846             <para><parameter>ptr</parameter> is a void pointer to the link
2847             quality data in the Hello DB. seperator is a character which is
2848             printed whenever there are multiple values (for example ',' or '/'
2849             buffer is the buffer you want to sprintf into. Please do not
2850             forget to \0 terminate!</para>
2851
2852             <para>Returns the buffer in case of errors. Please return
2853             <literal>"error"</literal> as string. Because
2854             <function>print_hello_lq</function> will often directly be put
2855             into a <function>printf()</function>.</para>
2856           </listitem>
2857         </varlistentry>
2858
2859         <varlistentry>
2860           <term>const char *(*print_tc_lq) (void *ptr, char separator, struct
2861           lqtextbuffer * buffer);</term>
2862
2863           <listitem>
2864             <para>Same as <function>print_hello_lq</function></para>
2865           </listitem>
2866         </varlistentry>
2867
2868         <varlistentry>
2869           <term>const char *(*print_cost) (olsr_linkcost cost, struct
2870           lqtextbuffer * buffer);</term>
2871
2872           <listitem>
2873             <para>Same as <function>print_hello_lq</function>, but for an
2874             arbitrary link cost.</para>
2875           </listitem>
2876         </varlistentry>
2877       </variablelist>
2878     </refsect1>
2879
2880     <refsect1>
2881       <title>See Also</title>
2882
2883       <simplelist type="inline">
2884         <member><xref endterm="olsrd_8-title" linkend="olsrd_8" /> <xref
2885         endterm="olsrd_conf_5-title" linkend="olsrd_conf_5" /></member>
2886       </simplelist>
2887     </refsect1>
2888   </refentry>
2889 </article>