README.rst

   1 dyn-nsupdate: Dynamically and securely update DNS zones via CGI
   2 ===============================================================
   3
   4 Introduction
   5 ------------
   6
   7 Welcome to dyn-nsupdate_, a collection of tools using BIND_, CGI_ and Python_ to
   8 provide DynDNS services. Both IPv4 and IPv6 are fully supported.
   9
  10 dyn-nsupdate consists of two pieces: The server part provides a way to update IP
  11 addresses in Bind's DNS zone via CGI, in a safe manner. The client part uses CGI
  12 to update some domain to the current address(es) of the machine it is running
  13 on. Alternatively, some routers can be configured to do this themselves. The
  14 FritzBox is known to be supported.
  15
  16 .. _dyn-nsupdate: https://www.ralfj.de/projects/dyn-nsupdate
  17 .. _BIND: https://www.isc.org/downloads/bind/
  18 .. _CGI: https://en.wikipedia.org/wiki/Common_Gateway_Interface
  19 .. _Python: https://www.python.org/
  20
  21 Server Setup
  22 ------------
  23
  24 In the following, replace ``dyn.example.com`` by whatever domain will be managed
  25 through DynDNS. I assume that BIND has already been set up for
  26 ``dyn.example.com`` as a dynamic zone that can be updated through ``nsupdate
  27 -l``. This can be achieved by setting ``update-policy local;`` in the zone
  28 configuration. Furthermore, I assume the directory ``/var/lib/bind/`` exists.
  29
  30 There are two pieces that have to be installed: A setuid wrapper which checks
  31 the passwords, and applies the updates; and some CGI scripts offered through a
  32 webserver.
  33
  34 Let's start with the setuid wrapper. To compile it, you will need cmake and
  35 boost, including the regex and program_options boost packages. Starting in the
  36 source directory, run::
  37
  38   cd nsupd-wrapper
  39   mkdir -p build
  40   cd build
  41   cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=/var/lib/bind/dyn-nsupdate.conf
  42   make
  43
  44 This should compile the binary ``dyn-nsupdate``. If you want to put the files in
  45 another directory, change the configuration file name accordingly. You can now
  46 install it and the sample configuration file, and set their permissions::
  47
  48   sudo install dyn-nsupdate /var/lib/bind/dyn-nsupdate -o bind -g bind -m +rx,u+ws
  49   sudo install ../../dyn-nsupdate.conf /var/lib/bind/dyn-nsupdate.conf -o bind -g bind -m u+rw
  50
  51 Finally, edit the config file. The format should be pretty self-explanatory. In
  52 particular, *change the password*!
  53
  54 Now, let's go on with the CGI scripts. They are using Python 2, so make sure you
  55 have that installed. There are two scripts: One is used for clients to detect
  56 their current external IP address, and one is used to do the actual update of
  57 the domain. The first script should be available on a domain that is available
  58 only through a single protocol, i.e., IPv4 only or IPv6 only. If you want to
  59 support both IPv4 and IPv6, I suggest you have three domains
  60 ``ipv4.ns.example.com``, ``ipv6.ns.example.com`` and ``ns.example.com`` where
  61 only the latter is available via both protocols (this is something you have to
  62 configure in your ``example.com`` zone). All can serve the same scripts (e.g.
  63 via a ``ServerAlias`` in the apache configuration). I also **strongly suggest**
  64 you make these domains *HTTPS-only*, as the client script will send a password!
  65
  66 Choose some directory (e.g., ``/srv/ns.example.com``) for the new domain, and
  67 copy the content of ``server-scripts`` there. Now configure your webserver
  68 appropriately for CGI scripts to be executed there. You can find a sample
  69 configuration for apache in ``apache-ns.example.com.conf``. If you used a
  70 non-default location for the ``dyn-nsupdate`` wrapper, you have to change the
  71 path in the ``update`` CGI script accordingly.
  72
  73 That's it! Your server is now configured. You can use ``curl`` to test your
  74 setup::
  75
  76   curl 'https://ns.example.com/update?domain=tests.dyn.example.com&password=some_secure_password&ip=127.0.0.1'
  77
  78
  79 Source, License
  80 ---------------
  81
  82 You can find the sources in the `git repository`_. They are provided under a
  83 2-clause BSD license.
  84
  85 .. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
  86
  87 Contact
  88 -------
  89
  90 If you found a bug, or want to leave a comment, please
  91 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_.