0aea1f9d3340938ce128295964a81dd8d32b7f64
[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 can be set here in milliseconds.
50     # The default is 1000 ms (1 second).
51     PlParam     "CheckInterval"  "5000"
52     
53     # The ping check interval in case there is any pinged host specified.
54     # The default is 5 seconds.
55     PlParam     "PingInterval"   "40"
56     
57     # If one or more IPv4 addresses are given, do a ping on these in
58     # descending order to validate that there is not only an entry in
59     # routing table, but also a real network connection. If any of
60     # these addresses could be pinged successfully, the test was
61     # succesful, i.e. if the ping on the 1st address was successful,the
62     # 2nd won't be pinged.
63     #
64     # The Ping list applies to the group of HNAs specified above or to the 
65                 # default internet gateway when no HNA is specified.
66                 #
67                 # Running the plugin without parameters acts as the 'old' dyn_gw_plain.
68     
69     #   The following ping entries for the internet gateway
70     PlParam "Ping"   "141.1.1.1"
71     PlParam "Ping"   "194.25.2.129"
72     
73     #   First group of HNAs with related ping host
74     PlParam     "HNA"      "192.168.80.0 255.255.255.0"
75     PlParam     "HNA"      "192.168.81.0 255.255.255.0"
76     PlParam     "Ping"   "192.168.81.12"
77     
78     #   Second HNA group with multiple related ping hosts.
79     #   Specifying multiple ping hosts provides redundancy.
80     PlParam "HNA"    "192.168.100.0 255.255.255.0"
81     PlParam "HNA"    "192.168.101.0 255.255.255.0"
82     PlParam "HNA"    "192.168.102.0 255.255.255.0"
83     PlParam "Ping"   "192.168.100.10"
84     PlParam "Ping"   "192.168.101.10"
85     
86     #   Third HNA group without ping check
87     PlParam "HNA"    "192.168.200.0 255.255.255.0"
88     PlParam "HNA"    "192.168.201.0 255.255.255.0"
89     PlParam "HNA"    "192.168.202.0 255.255.255.0"
90 }
91
92 --------------------------------------------------------------------------------
93 Change log:
94
95 18.02.2010
96   Caspar van Zon / C2SC
97 - Changed HNA checking.
98   The 'Ping' PlParam processing has been modified so that it is not only valid 
99         for the previous HNA entry but all entries proceeding the ping parameter until 
100         either the beginning of the list or the previous ping parameter.
101         If there is no previous HNA entry then HNA '0.0.0.0 0.0.0.0' for the internet
102         gateway is inserted instead.
103 - Two new interval parameters 'PingInterval' and 'CheckInterval' have been
104   introduced. 'PingInterval' is the new name for the 'Interval' parameter, the
105   old name has been maintained as well for compatibility. The 'CheckInterval' is
106   new and specifies the check interval for the OLSR event loop in milliseconds.
107 - When no ping hosts are specified at all the thread for the ping check will not
108   be started, eliminating the thread totally is left for future improvement.
109 - Code and variable names have been cleaned up in various places to improve both
110   readability and maintainability.
111 - Due to significant changes in the code base and the modified functionality the
112   version of the package has been increased to version 0.5
113 - Running the plugin without parameters acts like dyn_gw_plain so the 
114   dyn_gw_plain plugin can be made obsolete.
115         
116 21.12.2004
117   bjoern Riemer
118 - added universal hna checking
119   the plParams are parsed in spechial order, first the HNA parameter syntax: "net mask"
120   the following Ping parameter are only used for the previus HNA entry.
121   if there is no previus HNA entry then HNA "0.0.0.0 0.0.0.0" for internet GW is assumed
122
123 30.11.2004
124
125   updates by Jens:
126
127 - Upgraded to confirm with v2 plugin interface
128 - removed IPC stuff
129 - Removed much unnessecarry stuff
130 - Added an optional validation based on the ping command, which caused
131   some internal restructuring, e.g. the dependency of a threading
132   library)
133 - the config file accepts an "Interval", meaning how often the check is
134   done
135