README file for dyndns-lite

dyndns-list is a cgi script that is supposed to run on your web server.
It accepts http or https requests containing at least a host name and a 
password, plus an ip address to set. The hostname thereby serves as the
user name for the authentication using the supplied password in a very
simple user ( == hostname) and password database.
Once the request is authenticated, the cgi script will use the nsupdate
utility that comes with the bind nameserver to enter the identified
records into the configured (dynamic) zone of the nameserver.

The package also comes with a client script that gathers the needed
information from the system, but expects at least the hostname, password
and the URL to the cgi on your server as arguments on the commandline.
Use the "--help" option with the client script to see what else there is.

A setup helper script may assist your set-up. It is not very well tested.

License: GPLv2
Author: Roman Drahtmueller <draht at schaltsekun.de>

==============================================================================
Send a request by:

curl -k -d "ip=a.b.c.d
host=foo
pass=bar
ipv6=2001::a:b:c:d::
" https://your.server/cgi-bin/dyn.cgi

or, even simpler:
https://your.server/cgi-bin/dyn.cgi?host=foo?pass=bar

add the ip address and the ipv6 address using the field names like with
the http POST example above.

==============================================================================
Set up the server:

* configure your nameserver to have a dynamic zone, and make sure that the
  named process has sufficient privileges to write to the zone file directory.
* set up the shared secret that authenticates the operation of the nsupdate
  command against the nameserveer.
* set up your http server in such way that it executes the cgi using a path
  that you wish.
* test it using the client script.
  Example: 
  dyndns-lite-client -h maxwell -p equations -c https://foo.org/cgi-bin/dyn.cgi

  The DNS records are being updated almost instantly, so you should be able 
  to see the names very quickly.
  The records have a lifetime of 10 seconds, meaning that every recurser
  will finally request your configured nameserver at least once in 10s. 

==============================================================================
Bugs and notes:

* If you use https, then curl probably won't validate the server certificate
  of your server. You should check this independently, if this is important
  to you.
* Only ipv6 addresses starting with "2" are sent to the server by the client
  script. This is assumed to be practical, but may not be what you want.
* The parameters of the request are carefully checked to make sure that all
  input to the script is validated. Executing a shell script as a cgi from
  a web server is not without significant risk. If you change it, please
  better know what you are doing.
  If a parameter isn't within the expected range (a whitelist), then the
  parameter is ignored. Some occasions cause the cgi to just silently drop 
  the request, because that makes sense.
* The client script is likely to fail if you have more than one default
  gateway configured. This is somewhat exotic anyway.
* The client script isolates ipv6 addresses that are not scheduled to 
  expire. Just in case you were wondering about the jump through the loops...
  

the files in the package:
==============================================================================

/srv/www/cgi-bin/dyn.cgi

  The cgi script.
  notes:
  * configurables near the top, nothing really useful to change further down.
  * adds one, two or three entries to the nameserver for one request:
    - the A record for the host itself ("foo" in the following examples)
    - the A record "foo-v" that points at the address from which the update
      request came (-v as in "visible").
      Note that if the request came from an ipv6 address, the update attempt
      with that address for an (ipv4) A record will cause an error.
    - the AAAA record for the ipv6 address that came with the request, or 
      none, if no ipv6 address came with the update request.

/usr/bin/dyndns-lite-client

  client script.
  notes:
  * You don't need it, if you set up your request to your server all by 
    yourself. But it's quite handy.
  * If ipv6 addresses are re-newed, the old addresses remain but get tagged as
    "deprecated" by the kernel. Which is what it says, and the reason for some
    jumps through the loops in the script

/usr/bin/dyndns-lite-setup.sh

  helper script to set up the server. This is not very well tested.
  Have a look at the bottom of the cgi script to see how you can test the
  setup of the nsupdate command and its authentication to the server.
  Normally, this should take only a few seconds, but your mileage might vary.

/var/lib/dyndns-lite/dyndns-lite.auth

  username and password combinations. The user name equals the host name.

/etc/NetworkManager/dispatcher.d/dyndns-lite

  this script is executed as root by NetworkManager as soon as a new 
  connection has been initiated. You will need to enter your data there.


