* ISO8859-* -> UTF_8
[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 adresses it is associated with (HNAs) and if 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
45 PlParam "suffix" ".olsr"
46         local suffix which is appended to all received names.
47         (default: "")
48
49 PlParam "add-hosts" "/path/to/file"
50         copy contents of this additional hosts file to output file.
51         this is practical if you alreay use your /etc/hosts file.
52
53 PlParam "dns-server" "IP.ADDR"
54         anounce that this IP has a full (upstream) DNS server. if 
55         IP.ADDR is not specified (""), the main address is used.
56         nodes which don't know a nameserver will automatically use
57         this nameserver.
58
59 PlParam "resolv-file" "/path/to/resolv.conf"
60         path to resolv.conf file (usually /etc/resolv.conf)
61         if set, the 3 nearest (best ETX) upstream nameservers annonced 
62         by other nodes in the network are written to this file
63
64 PlParam "interval" "SEC"
65         interval for sending NAME messages in seconds.
66         (default: 120 - 2 minutes)
67
68 PlParam "timeout" "SEC"
69         validity time for received NAME messages in seconds.
70         (default: 3600 - 1 hour)
71
72 PlParam "lat" "12.123"
73         Float: Decimal latitude for this node to be flooded in the mesh
74
75 PlParam "lon" "12.123"
76         Float: Decimal longitude for this node to be flooded in the mesh
77
78 PlParam "latlon-file" "/var/run/latlon.js"
79         Filename to write Javascript statements to. Default is "latlon.js"
80         (either /var/run or windows directory). This file is written, if
81         the "lat" and "lon" parameters are set. It has this format:
82
83         /* One or more mid-aliases of multihomed nodes */
84         Mid('fromip','toip');
85
86         /* One special Node() entry for this node
87          * defhna means: This node announces hna 0.0.0.0/0
88          * defroute means: The current neighbour IP for 0.0.0.0/0
89          */
90         Self('mainip',lat,lon,defhna?1:0,'defroute','name');
91
92         /* One or more node entires for other nodes */
93         Node('mainip',lat,lon,this-node-defhna?1:0,'defroute','name');
94
95         /* One or more links between nodes */
96         Link('fromip','toip',lq,nlq,etx);
97
98 PlParam "latlon-infile" "name-of-input.txt"
99         Filename to read lat/lon positions from. Meant to be used
100         by a walking GPS receiver. Just write comma separated decimal
101         latitude and longitude to this file. Will overwrite the
102         "lat" and "lon" parameters during runtime.
103
104 ---------------------------------------------------------------------
105 SAMPLE CONFIG
106 ---------------------------------------------------------------------
107
108 add in /etc/olsrd.conf:
109
110 LoadPlugin "olsrd_nameservice.so.0.2"
111 {
112         PlParam "name" "thisismyname"
113         PlParam "hosts-file" "/etc/hosts"
114         PlParam "resolv-file" "/etc/resolv.conf"
115 }
116
117
118 ---------------------------------------------------------------------
119 USING THE NAME INFORMATION
120 ---------------------------------------------------------------------
121
122 to use the name information distributed by the plugin actually for
123 name resolution you can do one of the following.
124
125 UNIX VARIANTS:
126
127 * overwrite /etc/hosts
128         be sure you have nothing in /etc/hosts which you still need and
129         configure the plugin with PlParam "host-file" "/etc/hosts"
130
131 * link /etc/hosts
132         ln -s /var/run/hosts_olsr /etc/hosts
133
134 * use dnsmasq
135         if you want to make the names available via ordinary DNS
136         you can use dnsmasq to read the hosts file and serve it to
137         users. add "addn-hosts=/var/run/hosts_olsr" to dnsmasq.conf 
138         and restart dnsmasq
139
140 WINDOWS:
141
142 * overwrite C:\WINDOWS\system32\drivers\etc\hosts
143         be sure you have nothing in the file which you still need 
144         and configure the plugin with
145         PlParam "filename" "C:\WINDOWS\system32\drivers\etc\hosts"
146
147
148 ---------------------------------------------------------------------
149 TODO
150 ---------------------------------------------------------------------
151   
152   * implement a small DNS server into the plugin?
153   * or make dynamic DNS updates for bind?
154
155 ---------------------------------------------------------------------
156 EOF / 30.06.2007