info: java: update workspace
[olsrd.git] / lib / nameservice / README_NAMESERVICE
1 ---------------------------------------------------------------------
2 NAMESERVICE PLUGIN FOR OLSRD
3 by Bruno Randolf <bruno.randolf@4g-systems.biz>
4 ---------------------------------------------------------------------
5
6 A simple DNS replacement for OLSR networks.
7
8 This plugin distributes host name (DNS) information over OLSR. Every
9 node which runs the olsr daemon can announce it's own name, names for
10 other IP addresses it is associated with (HNAs) and whether it is running
11 a "real" nameserver which can resolve other (internet) names (upstream
12 DNS server).
13
14 The nodes in the network collect this information and write the host
15 names to a file (possibly /etc/hosts), and the 3 nearest upstream
16 nameservers to another file (possibly /etc/resolv.conf).
17
18 These files can be used to resolve hostnames on the local system and/or
19 be read by a DNS server like "dnsmasq", to make the names available
20 via the ordinary DNS protocol to other clients as well.
21
22 The default location of the hosts file is
23 - "/var/run/hosts_olsr" on unixes
24 - "C:\WINDOWS\hosts_olsr" on windows
25
26
27 ---------------------------------------------------------------------
28 PLUGIN PARAMETERS (PlParam)
29 ---------------------------------------------------------------------
30
31 PlParam "name" "my-name.mesh"
32         the name of this OLSR node (main address).
33         can be specified multiple times for different names.
34
35 PlParam "IP.ADDR" "another-name.mesh"
36         a name for a specified IP address.
37         the IP address has to be either from one of the olsr 
38         interfaces or within a HNA network we announce.
39         can be specified multiple times.
40
41 PlParam "hosts-file" "/path/to/hosts_file"
42         which file to write to (usually /etc/hosts).
43         (default: /var/run/hosts_olsr)
44         Also see option "filewrite-interval".
45
46 PlParam "suffix" ".olsr"
47         local suffix which is appended to all received names.
48         (default: "")
49
50 PlParam "add-hosts" "/path/to/file"
51         copy contents of this additional hosts file to output file.
52         this is practical if you alreay use your /etc/hosts file.
53         Also see option "filewrite-interval", how often the file
54         is read.
55
56 PlParam "dns-server" "IP.ADDR"
57         anounce that this IP has a full (upstream) DNS server. if 
58         IP.ADDR is not specified (""), the main address is used.
59         nodes which don't know a nameserver will automatically use
60         this nameserver.
61
62 PlParam "resolv-file" "/path/to/resolv.conf"
63         path to resolv.conf file (usually /etc/resolv.conf)
64         if set, the 3 nearest (best ETX) upstream nameservers annonced 
65         by other nodes in the network are written to this file
66         Also see option "filewrite-interval".
67
68 PlParam "interval" "SEC"
69         interval for sending NAME messages in seconds.
70         (default: 120 - 2 minutes)
71
72 PlParam "timeout" "SEC"
73         validity time for transmitted NAME messages in seconds.
74         (default: 1800 - 30 minutes)
75
76 PlParam "lat" "12.123"
77         Float: Decimal latitude for this node to be flooded in the mesh
78
79 PlParam "lon" "12.123"
80         Float: Decimal longitude for this node to be flooded in the mesh
81
82 PlParam "latlon-file" "/var/run/latlon.js"
83         Filename to write Javascript statements to. Default is "latlon.js"
84         (either /var/run or windows directory). This file is written, if
85         the "lat" and "lon" parameters are set. It has this format:
86
87         /* One or more mid-aliases of multihomed nodes */
88         Mid('fromip','toip');
89
90         /* One special Node() entry for this node
91          * defhna means: This node announces hna 0.0.0.0/0
92          * defroute means: The current neighbour IP for 0.0.0.0/0
93          */
94         Self('mainip',lat,lon,defhna?1:0,'defroute','name');
95
96         /* One or more node entires for other nodes */
97         Node('mainip',lat,lon,this-node-defhna?1:0,'defroute','name');
98
99         /* One or more links between nodes */
100         Link('fromip','toip',lq,nlq,etx);
101
102         Also see option "filewrite-interval".
103
104 PlParam "latlon-infile" "name-of-input.txt"
105         Filename to read lat/lon positions from. Meant to be used
106         by a walking GPS receiver. Just write comma separated decimal
107         latitude and longitude to this file. Will overwrite the
108         "lat" and "lon" parameters during runtime.
109
110 PlParam "sighup-pid-file" "/path/to/pidfile.pid"
111         (*nix systems only) Sends a HUP signal to the process specified
112         by the pidfile (usually /var/run/dnsmasq.pid) when the host name
113         table changes. This is useful for letting dnsmasq or bind know
114         they have to reload their hosts file.
115         Also see option "filewrite-interval".
116
117 PlParam "name-change-script" "/path/to/script"
118         Script to execute when there is a change in the hosts names
119         table. Useful for executing a script that uses the hosts file
120         to keep a website or a database updated.
121         Also see option "filewrite-interval".
122
123 PlParam "service" "http://me.olsr:80|tcp|my little homepage"
124         Add a new service announcement to be spreaded in the mesh.
125
126 PlParam "services-file" "/path/to/services_file"
127         File to write (default: /var/run/services_olsr)
128         Also see option "filewrite-interval".
129
130 PlParam "services-change-script" "/path/to/script"
131         Similar to the previous parameter. Script to execute when there
132         is a change in the services list propagated by the nameserver
133         plugin. Useful for executing a script that uses the services file
134         to keep a website or a database updated.
135         Also see option "filewrite-interval".
136
137 PlParam "mac" "xx:xx:xx:xx:xx:xx[,0-255]"
138         Add a new MAC addr to be spreaded in the mesh. This MAC addr
139         may be used to fine control nerve-wreck-page solutions based
140         on MAC addresses. The optional dec. number designates a class.
141
142 PlParam "macs-file" "/path/to/macs_file"
143         File to write (default: /var/run/macs_olsr)
144         Also see option "filewrite-interval".
145
146 PlParam "macs-change-script" "/path/to/script"
147         Similar to the previous parameter. Script to execute when there
148         is a change in the macs list propagated by the nameserver
149         plugin. Useful for executing a script that uses the services file
150         to keep a website or a database updated.
151         Also see option "filewrite-interval".
152
153 PlParam "filewrite-interval" "SEC"
154         Interval for writing the status-files to disk, defined in seconds.
155         (default: 5 seconds)
156
157 ---------------------------------------------------------------------
158 SAMPLE CONFIG
159 ---------------------------------------------------------------------
160
161 add in /etc/olsrd/olsrd.conf:
162
163 LoadPlugin "olsrd_nameservice.so.0.4"
164 {
165         PlParam "name" "thisismyname"
166         PlParam "hosts-file" "/etc/hosts"
167         PlParam "resolv-file" "/etc/resolv.conf"
168 }
169
170
171 ---------------------------------------------------------------------
172 USING THE NAME INFORMATION
173 ---------------------------------------------------------------------
174
175 to use the name information distributed by the plugin actually for
176 name resolution you can do one of the following.
177
178 UNIX VARIANTS:
179
180 * overwrite /etc/hosts
181         be sure you have nothing in /etc/hosts which you still need and
182         configure the plugin with PlParam "host-file" "/etc/hosts"
183
184 * link /etc/hosts
185         ln -s /var/run/hosts_olsr /etc/hosts
186
187 * use dnsmasq
188         if you want to make the names available via ordinary DNS
189         you can use dnsmasq to read the hosts file and serve it to
190         users. add "addn-hosts=/var/run/hosts_olsr" to dnsmasq.conf 
191         and:
192                PlParam "sighup-pid-file" "/var/run/dnsmasq.pid"
193
194         to your nameservice plugin configuration.
195
196         This is especially useful for infrastructure mesh networks that
197         can't afford to run olsrd on all the clients but wish to provide
198         DNS to them. This is solved by running dnsmasq and olsrd with
199         this setup on "edge" nodes that provide connectivity.
200
201 WINDOWS:
202
203 * overwrite C:\WINDOWS\system32\drivers\etc\hosts
204         be sure you have nothing in the file which you still need 
205         and configure the plugin with
206         PlParam "hosts-file" "C:\WINDOWS\system32\drivers\etc\hosts"
207
208 ---------------------------------------------------------------------
209 TODO
210 ---------------------------------------------------------------------
211   
212   * implement a small DNS server into the plugin?
213   * or make dynamic DNS updates for bind?
214
215 ---------------------------------------------------------------------
216 EOF / 12.01.2017