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. Please read this guide carefully and make sure you understand the
  34 security implications of what you are doing. setuid wrappers are not toys!
  35
  36 Let's setting up the setuid wrapper. To compile it, you will need cmake and
  37 boost, including the regex and program_options boost packages. Starting in the
  38 source directory, run::
  39
  40   cd nsupd-wrapper
  41   mkdir -p build
  42   cd build
  43   DIR=/var/lib/bind
  44   cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=$DIR/dyn-nsupdate.conf
  45   make
  46
  47 This should compile the binary ``dyn-nsupdate``. Notice that the path to the
  48 configuration file will be hard-coded into the binary. If it were run-time
  49 configurable, then a user could call the script with her own configuration file,
  50 gaining access to all domains BIND lets you configure. If you want to put the
  51 files in another directory, change the configuration file name accordingly. Make
  52 sure the file (nor any of the directories it is in) can *not be written by
  53 non-root*. The setuid wrapper trusts that file. You can now install it and the
  54 sample configuration file, and set their permissions::
  55
  56   sudo install dyn-nsupdate $DIR/dyn-nsupdate -o bind -g bind -m +rx,u+ws
  57   sudo install ../../dyn-nsupdate.conf.dist $DIR/dyn-nsupdate.conf -o bind -g bind -m u+rw
  58
  59 Finally, edit the config file. The format should be pretty self-explanatory. In
  60 particular, **change the password**!
  61
  62 Now, let's go on with the CGI scripts. They are using Python 2, so make sure you
  63 have that installed. There are two scripts: One is used for clients to detect
  64 their current external IP address, and one is used to do the actual update of
  65 the domain. The first script should be available on a domain that is available
  66 only through a single protocol, i.e., IPv4 only or IPv6 only.  This is required
  67 to reliably detect the current address of the given protocol. If you want to
  68 support both IPv4 and IPv6, I suggest you have three domains
  69 ``ipv4.ns.example.com``, ``ipv6.ns.example.com`` and ``ns.example.com`` where
  70 only the latter is available via both protocols (this is something you have to
  71 configure in your ``example.com`` zone). All can serve the same scripts (e.g.
  72 via a ``ServerAlias`` in the apache configuration). I also **strongly suggest**
  73 you make these domains *HTTPS-only*, as the client script will send a password!
  74
  75 Choose some directory (e.g., ``/srv/ns.example.com``) for the new domain, and
  76 copy the content of ``server-scripts`` there. Now configure your webserver
  77 appropriately for CGI scripts to be executed there. You can find a sample
  78 configuration for apache in ``apache-ns.example.com.conf``. If you used a
  79 non-default location for the ``dyn-nsupdate`` wrapper, you have to change the
  80 path in the ``update`` CGI script accordingly.
  81
  82 That's it! Your server is now configured. You can use ``curl`` to test your
  83 setup::
  84
  85   DOMAIN=test.dyn.example.com
  86   PW=some_secure_password
  87   curl 'https://ns.example.com/update?domain=$DOMAIN&password=$PW&ip=127.0.0.1'
  88
  89
  90 Client setup (using the script)
  91 -------------------------------
  92
  93 You can find the client script at ``client-scripts/dyn-ns-client``. It requires
  94 Python 3. Copy that script to the machine that should be available under the
  95 dynamic domain. Also copy the sample configuration file ``dyn-ns-client.conf.dist`` to
  96 ``$HOME/.config/dyn-nsupdate/dyn-ns-client.conf.dist``. (You can choose another
  97 name, but then you will have to tell the script about it). That file contains
  98 comments that should explain everything. Note that the script can update a list
  99 of domain names, in case you need the machine to have several names (it is
 100 preferable to use a CNAME instead, this will reduce the number of updates
 101 performed in the zone).
 102
 103 To run the script regularly, simply set up a cronjob. You can do so by running
 104 ``crontab -e``, and add a line as follows::
 105
 106   */15 * * * * /home/user/dyn-ns-client
 107
 108 This sets the update interval to 15min. If your IP address changes daily, you
 109 may want to reduce this to 5min to have a smaller timeframe during which your
 110 server is not available.
 111
 112 Client setup (using a router)
 113 -----------------------------
 114
 115 Some routers are able to perform the update of the domain names themselves. The
 116 FritzBox is known to be supported. To configure it to tell your server about the
 117 current IP address, go to the DynDNS configuration section of the FritzBox and
 118 choose the "custom" DynDNS provider. Then enter the following settings:
 119
 120 - Update-URL: ``https://ns.example.com/update?domain=<domain>&password=<pass>&ip=<ipaddr>``
 121 - Domain Name: ``test.dyn.example.com``
 122 - User Name: ``just_something``
 123 - Password: ``some_secure_password``
 124
 125 Note that the user name is ignored.
 126
 127
 128
 129 Source, License
 130 ---------------
 131
 132 You can find the sources in the `git repository`_. They are provided under a
 133 2-clause BSD license.
 134
 135 .. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
 136
 137 Contact
 138 -------
 139
 140 If you found a bug, or want to leave a comment, please
 141 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_. All sorts of feedback are
 142 welcome :)