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