secure: install extra (documention) files
[olsrd.git] / lib / dyn_gw / README_DYN_GW
1 DYNAMIC INTERNET GATEWAY PLUGIN FOR olsr.org olsrd
2 by Andreas Tonnesen(andreto@olsr.org)
3 Additions by Jens Nachitgall and others
4
5 ABOUT
6
7 Plugin is IPv4 only and it only runs on Linux with the libpthread
8 library installed!
9
10 This is a plugin that checks if the local node has a Internet-
11 connection. A Internet-connetion is identified by a "default gw" with a
12 hopcount of 0. That is a route to 0.0.0.0/0 with metric 0.  By default
13 the check is done every 5 secs. You can change the check interval by
14 providing an value for "PingInterval" in the plugin's section of olsrd.conf.
15
16 If one or more IPv4 addresses are given as values for "Ping" in the
17 section or dyn_gw in olsrd.conf, then a test is done to validate if
18 there is really an internet connection (and not just an entry in the
19 routing table). If any of the arbitrary many given IPv4 addresses can be
20 pinged, the validation was successful. The addresses are pinged in the
21 order given in the olsrd.conf (i.e. the first given address is pinged
22 first, the the 2nd, and so on). For this to work a command like
23 "ping -c 1 -q <PING-ADDRESS>" must be possible on the system OLSRd runs
24 on. The validation is based on the return value of this ping command.
25
26 Since OLSR uses hopcount/metric on all routes this plugin will
27 not respond to Internet gateways added by OLSRd.
28
29 When a Internet gateway is discovered - this node will start
30 announcing 0.0.0.0/0 connectivity by HNA messages flooded into
31 the OLSR network. If the route is removed the HNA messages
32 will not be transmitted. This check is totally dynamic and
33 Internet connectivity might come and go.
34
35 This plugin can also process more specific routes by specifying groups of HNAs
36 (Host and Network Association) and ping hosts.
37
38 This plugin will work very good with a automatic network cable
39 detection daemon such as  netplug:
40 http://freshmeat.net/projects/key-netplug/
41
42 This plugin is a good example of using plugins for other stuff
43 than packet transmission.
44
45 HOW TO USE (version 0.5)
46
47 LoadPlugin "olsrd_dyn_gw.so.0.5"
48 {
49     # The plugin check interval in milliseconds.
50     # PlParam     "checkinterval"      "1000"
51
52     # The ping check interval in seconds when any pinged host specified.
53     # PlParam     "interval"           "5"
54     # PlParam     "pinginterval"       "5"
55
56     # The ping command to use when any pinged host specified.
57     # PlParam     "pingcmd"            "ping -c 1 -q %s"
58
59     # If one or more IPv4 addresses are given, do a ping on these in
60     # descending order to validate that there is not only an entry in
61     # routing table, but also a real network connection. If any of
62     # these addresses could be pinged successfully, the test was
63     # succesful, i.e. if the ping on the 1st address was successful,the
64     # 2nd won't be pinged.
65     #
66     # The Ping list applies to the group of HNAs specified above or to the
67     # default internet gateway when no HNA is specified.
68     #
69     # Running the plugin without parameters acts as the 'old' dyn_gw_plain.
70
71     # The following ping entries for the internet gateway
72     # PlParam     "ping"               "141.1.1.1"
73     # PlParam     "ping"               "194.25.2.129"
74
75     # First group of HNAs with related ping host
76     # PlParam     "hna"                "192.168.80.0   255.255.255.0"
77     # PlParam     "hna"                "192.168.81.0   255.255.255.0"
78     # PlParam     "ping"               "192.168.81.12"
79
80     # Second HNA group with multiple related ping hosts.
81     # Specifying multiple ping hosts provides redundancy.
82     # PlParam     "hna"                "192.168.100.0  255.255.255.0"
83     # PlParam     "hna"                "192.168.101.0  255.255.255.0"
84     # PlParam     "hna"                "192.168.102.0  255.255.255.0"
85     # PlParam     "ping"               "192.168.100.10"
86     # PlParam     "ping"               "192.168.101.10"
87
88     # Third HNA group without ping check
89     # PlParam     "hna"                "192.168.200.0  255.255.255.0"
90     # PlParam     "hna"                "192.168.201.0  255.255.255.0"
91     # PlParam     "hna"                "192.168.202.0  255.255.255.0"
92
93     # Set custom ping command - %s will be replaced with the IP address to ping
94     # PlParam     "pingcmd"            "ping -c 1 -q -I vpn %s"
95 }
96
97 --------------------------------------------------------------------------------
98 Change log:
99
100 18.02.2010
101   Caspar van Zon / C2SC
102 - Changed HNA checking.
103   The 'Ping' PlParam processing has been modified so that it is not only valid 
104         for the previous HNA entry but all entries proceeding the ping parameter until 
105         either the beginning of the list or the previous ping parameter.
106         If there is no previous HNA entry then HNA '0.0.0.0 0.0.0.0' for the internet
107         gateway is inserted instead.
108 - Two new interval parameters 'PingInterval' and 'CheckInterval' have been
109   introduced. 'PingInterval' is the new name for the 'Interval' parameter, the
110   old name has been maintained as well for compatibility. The 'CheckInterval' is
111   new and specifies the check interval for the OLSR event loop in milliseconds.
112 - When no ping hosts are specified at all the thread for the ping check will not
113   be started, eliminating the thread totally is left for future improvement.
114 - Code and variable names have been cleaned up in various places to improve both
115   readability and maintainability.
116 - Due to significant changes in the code base and the modified functionality the
117   version of the package has been increased to version 0.5
118 - Running the plugin without parameters acts like dyn_gw_plain so the 
119   dyn_gw_plain plugin can be made obsolete.
120         
121 21.12.2004
122   bjoern Riemer
123 - added universal hna checking
124   the plParams are parsed in spechial order, first the HNA parameter syntax: "net mask"
125   the following Ping parameter are only used for the previus HNA entry.
126   if there is no previus HNA entry then HNA "0.0.0.0 0.0.0.0" for internet GW is assumed
127
128 30.11.2004
129
130   updates by Jens:
131
132 - Upgraded to confirm with v2 plugin interface
133 - removed IPC stuff
134 - Removed much unnessecarry stuff
135 - Added an optional validation based on the ping command, which caused
136   some internal restructuring, e.g. the dependency of a threading
137   library)
138 - the config file accepts an "Interval", meaning how often the check is
139   done
140