README.rst

   1 dyn-nsupdate: Self-made DynDNS
   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 with your own nameserver. Both IPv4 and IPv6 are fully
   9 supported.
  10
  11 dyn-nsupdate consists of two pieces: The server part provides a way to update IP
  12 addresses in Bind's DNS zones via CGI, in a safe manner. The client part uses CGI
  13 to update some domain to the current address(es) of the machine it is running
  14 on. Alternatively, some routers can be configured to do this themselves. The
  15 FritzBox is known to be supported.
  16
  17 .. _dyn-nsupdate: https://www.ralfj.de/projects/dyn-nsupdate
  18 .. _BIND: https://www.isc.org/downloads/bind/
  19 .. _CGI: https://en.wikipedia.org/wiki/Common_Gateway_Interface
  20 .. _Python: https://www.python.org/
  21
  22 Server Setup
  23 ------------
  24
  25 In the following, replace ``dyn.example.com`` by whatever domain will be managed
  26 through DynDNS. I assume that BIND has already been set up for
  27 ``dyn.example.com`` as a dynamic zone that can be updated through ``nsupdate
  28 -l``. This can be achieved by setting ``update-policy local;`` in the zone
  29 configuration. Furthermore, I assume the directory ``/var/lib/bind/`` exists.
  30
  31 There are two pieces that have to be installed: A setuid wrapper which checks
  32 the passwords, and applies the updates; and some CGI scripts offered through a
  33 webserver.
  34
  35 Let's start with the setuid wrapper. To compile it, you will need cmake and
  36 boost, including the regex and program_options boost packages. Starting in the
  37 source directory, run::
  38
  39   cd nsupd-wrapper
  40   mkdir -p build
  41   cd build
  42   cmake .. -DCMAKE_BUILD_TYPE=Release \
  43     -DDYNNSUPDATE_CONFIG_FILE=/var/lib/bind/dyn-nsupdate.conf
  44   make
  45
  46 This should compile the binary ``dyn-nsupdate``. If you want to put the files in
  47 another directory, change the configuration file name accordingly. You can now
  48 install it and the sample configuration file, and set their permissions::
  49
  50   sudo install dyn-nsupdate /var/lib/bind/dyn-nsupdate -o bind -g bind -m +rx,u+ws
  51   sudo install ../../dyn-nsupdate.conf.dist /var/lib/bind/dyn-nsupdate.conf -o bind -g bind -m u+rw
  52
  53 Finally, edit the config file. The format should be pretty self-explanatory. In
  54 particular, **change the password**!
  55
  56 Now, let's go on with the CGI scripts. They are using Python 2, so make sure you
  57 have that installed. There are two scripts: One is used for clients to detect
  58 their current external IP address, and one is used to do the actual update of
  59 the domain. The first script should be available on a domain that is available
  60 only through a single protocol, i.e., IPv4 only or IPv6 only. If you want to
  61 support both IPv4 and IPv6, I suggest you have three domains
  62 ``ipv4.ns.example.com``, ``ipv6.ns.example.com`` and ``ns.example.com`` where
  63 only the latter is available via both protocols (this is something you have to
  64 configure in your ``example.com`` zone). All can serve the same scripts (e.g.
  65 via a ``ServerAlias`` in the apache configuration). I also **strongly suggest**
  66 you make these domains *HTTPS-only*, as the client script will send a password!
  67
  68 Choose some directory (e.g., ``/srv/ns.example.com``) for the new domain, and
  69 copy the content of ``server-scripts`` there. Now configure your webserver
  70 appropriately for CGI scripts to be executed there. You can find a sample
  71 configuration for apache in ``apache-ns.example.com.conf``. If you used a
  72 non-default location for the ``dyn-nsupdate`` wrapper, you have to change the
  73 path in the ``update`` CGI script accordingly.
  74
  75 That's it! Your server is now configured. You can use ``curl`` to test your
  76 setup::
  77
  78   DOMAIN=test.dyn.example.com
  79   PW=some_secure_password
  80   curl 'https://ns.example.com/update?domain=$DOMAIN&password=$PW&ip=127.0.0.1'
  81
  82
  83 Client setup (using the script)
  84 -------------------------------
  85
  86 You can find the client script at ``client-scripts/dyn-ns-client``. It requires
  87 Python 3. Copy that script to the machine that should be available under the
  88 dynamic domain. Then change the configuration section at the top to match your
  89 setup. Note that the script can update a list of domain names, in case you need
  90 the machine to have several names (it is preferable to use a CNAME instead, this
  91 will reduce the number of updates performed in the zone). The ``serverIPv4`` and
  92 ``serverIPv6`` are only used if IPv4/IPv6 is enabled. These machines must be
  93 available with that protocol only, otherwise it is not possible to reliably
  94 detect the current external address.
  95
  96 To run the script regularly, simply set up a cronjob. You can do so by running
  97 ``crontab -e``, and add a line as follows::
  98
  99   */15 * * * * /home/user/dyn-ns-client
 100
 101 This sets the update interval to 15min. If your IP address changes daily, you
 102 may want to reduce this to 5min to have a smaller timeframe during which your
 103 server is not available.
 104
 105 Client setup (using a router)
 106 -----------------------------
 107
 108 Some routers are able to perform the update of the domain names themselves. The
 109 FritzBox is known to be supported. To configure it to tell your server about the
 110 current IP address, go to the DynDNS configuration section of the FritzBox and
 111 choose the "custom" DynDNS provider. Then enter the following settings:
 112
 113 - Update-URL: ``https://ns.example.com/update?domain=<domain>&password=<pass>&ip=<ipaddr>``
 114 - Domain Name: ``test.dyn.example.com``
 115 - User Name: ``just_something``
 116 - Password: ``some_secure_password``
 117
 118 Note that the user name is ignored.
 119
 120
 121
 122 Source, License
 123 ---------------
 124
 125 You can find the sources in the `git repository`_. They are provided under a
 126 2-clause BSD license.
 127
 128 .. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
 129
 130 Contact
 131 -------
 132
 133 If you found a bug, or want to leave a comment, please
 134 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_.