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 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 transmitted NAME messages in seconds.
  70         (default: 1800 - 30 minutes)
  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 PlParam "sighup-pid-file" "/path/to/pidfile.pid"
 105         (*nix systems only) Sends a HUP signal to the process specified
 106         by the pidfile (usually /var/run/dnsmasq.pid) when the host name
 107         table changes. This is useful for letting dnsmasq or bind know
 108         they have to reload their hosts file.
 109
 110 PlParam "name-change-script" "/path/to/script"
 111         Script to execute when there is a change in the hosts names
 112         table. Useful for executing a script that uses the hosts file
 113         to keep a website or a database updated.
 114
 115 PlParam "service" "http://me.olsr:80|tcp|my little homepage"
 116         Add a new service announcement to be spreaded in the mesh.
 117
 118 PlParam "services-file" "/path/to/services_file"
 119         File to write (default: /var/run/services_olsr)
 120
 121 PlParam "services-change-script" "/path/to/script"
 122         Similar to the previous parameter. Script to execute when there
 123         is a change in the services list propagated by the nameserver
 124         plugin. Useful for executing a script that uses the services file
 125         to keep a website or a database updated.
 126
 127 PlParam "mac" "xx:xx:xx:xx:xx:xx[,0-255]"
 128         Add a new MAC addr to be spreaded in the mesh. This MAC addr
 129         may be used to fine control nerve-wreck-page solutions based
 130         on MAC addresses. The optional dec. number designates a class.
 131
 132 PlParam "macs-file" "/path/to/macs_file"
 133         File to write (default: /var/run/macs_olsr)
 134
 135 PlParam "macs-change-script" "/path/to/script"
 136         Similar to the previous parameter. Script to execute when there
 137         is a change in the macs list propagated by the nameserver
 138         plugin. Useful for executing a script that uses the services file
 139         to keep a website or a database updated.
 140
 141 ---------------------------------------------------------------------
 142 SAMPLE CONFIG
 143 ---------------------------------------------------------------------
 144
 145 add in /etc/olsrd/olsrd.conf:
 146
 147 LoadPlugin "olsrd_nameservice.so.0.2"
 148 {
 149         PlParam "name" "thisismyname"
 150         PlParam "hosts-file" "/etc/hosts"
 151         PlParam "resolv-file" "/etc/resolv.conf"
 152 }
 153
 154
 155 ---------------------------------------------------------------------
 156 USING THE NAME INFORMATION
 157 ---------------------------------------------------------------------
 158
 159 to use the name information distributed by the plugin actually for
 160 name resolution you can do one of the following.
 161
 162 UNIX VARIANTS:
 163
 164 * overwrite /etc/hosts
 165         be sure you have nothing in /etc/hosts which you still need and
 166         configure the plugin with PlParam "host-file" "/etc/hosts"
 167
 168 * link /etc/hosts
 169         ln -s /var/run/hosts_olsr /etc/hosts
 170
 171 * use dnsmasq
 172         if you want to make the names available via ordinary DNS
 173         you can use dnsmasq to read the hosts file and serve it to
 174         users. add "addn-hosts=/var/run/hosts_olsr" to dnsmasq.conf
 175         and:
 176                PlParam "sighup-pid-file" "/var/run/dnsmasq.pid"
 177
 178         to your nameservice plugin configuration.
 179
 180         This is especially useful for infrastructure mesh networks that
 181         can't afford to run olsrd on all the clients but wish to provide
 182         DNS to them. This is solved by running dnsmasq and olsrd with
 183         this setup on "edge" nodes that provide connectivity.
 184
 185 WINDOWS:
 186
 187 * overwrite C:\WINDOWS\system32\drivers\etc\hosts
 188         be sure you have nothing in the file which you still need
 189         and configure the plugin with
 190         PlParam "hosts-file" "C:\WINDOWS\system32\drivers\etc\hosts"
 191
 192 ---------------------------------------------------------------------
 193 TODO
 194 ---------------------------------------------------------------------
 195
 196   * implement a small DNS server into the plugin?
 197   * or make dynamic DNS updates for bind?
 198
 199 ---------------------------------------------------------------------
 200 EOF / 30.06.2007