dyn-nsupdate: Self-made DynDNS
-===============================================================
+==============================
Introduction
------------
There are two pieces that have to be installed: A setuid wrapper which checks
the passwords, and applies the updates; and some CGI scripts offered through a
-webserver.
+webserver. Please read this guide carefully and make sure you understand the
+security implications of what you are doing. setuid wrappers are not toys!
-Let's start with the setuid wrapper. To compile it, you will need cmake and
+Let's first set up the setuid wrapper. To compile it, you will need cmake and
boost, including the regex and program_options boost packages. Starting in the
source directory, run::
cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=$DIR/dyn-nsupdate.conf
make
-This should compile the binary ``dyn-nsupdate``. If you want to put the files in
-another directory, change the configuration file name accordingly. You can now
-install it and the sample configuration file, and set their permissions::
+This should compile the binary ``dyn-nsupdate``. Notice that the path to the
+configuration file will be hard-coded into the binary. If it were run-time
+configurable, then a user could call the script with her own configuration file,
+gaining access to all domains BIND lets you configure. If you want to put the
+files in another directory, change the configuration file name accordingly. Make
+sure the file (and all of the directories it is in) can *not be written by
+non-root*. The setuid wrapper trusts that file. You can now install it and the
+sample configuration file, and set their permissions::
sudo install dyn-nsupdate $DIR/dyn-nsupdate -o bind -g bind -m +rx,u+ws
sudo install ../../dyn-nsupdate.conf.dist $DIR/dyn-nsupdate.conf -o bind -g bind -m u+rw
Now, let's go on with the CGI scripts. They are using Python 2, so make sure you
have that installed. There are two scripts: One is used for clients to detect
their current external IP address, and one is used to do the actual update of
-the domain. The first script should be available on a domain that is available
-only through a single protocol, i.e., IPv4 only or IPv6 only. If you want to
-support both IPv4 and IPv6, I suggest you have three domains
+the domain. The first script is used by the "web" IP detection method (see
+client configuration below). It should be available on a domain that is
+available only through a single protocol, i.e., IPv4 only or IPv6 only. This is
+required to reliably detect the current address of the given protocol. If you
+want to support both IPv4 and IPv6, I suggest you have three domains
``ipv4.ns.example.com``, ``ipv6.ns.example.com`` and ``ns.example.com`` where
only the latter is available via both protocols (this is something you have to
-configure in your ``example.com`` zone). All can serve the same scripts (e.g.
-via a ``ServerAlias`` in the apache configuration). I also **strongly suggest**
-you make these domains *HTTPS-only*, as the client script will send a password!
+configure in your ``example.com`` DNS zone). All can serve the same scripts
+(e.g. via a ``ServerAlias`` in the apache configuration). I also **strongly
+suggest** you make these domains *HTTPS-only*, as the client script will send a
+password!
Choose some directory (e.g., ``/srv/ns.example.com``) for the new domain, and
copy the content of ``server-scripts`` there. Now configure your webserver
You can find the client script at ``client-scripts/dyn-ns-client``. It requires
Python 3. Copy that script to the machine that should be available under the
-dynamic domain. Then change the configuration section at the top to match your
-setup. Note that the script can update a list of domain names, in case you need
-the machine to have several names (it is preferable to use a CNAME instead, this
-will reduce the number of updates performed in the zone). The ``serverIPv4`` and
-``serverIPv6`` are only used if IPv4/IPv6 is enabled. These machines must be
-available with that protocol only, otherwise it is not possible to reliably
-detect the current external address.
+dynamic domain. Also copy the sample configuration file
+``dyn-ns-client.conf.dist`` to ``$HOME/.config/dyn-nsupdate/dyn-ns-client.conf``.
+You can choose another name, but then you will have to tell the script about it.
+Call ``dyn-ns-client --help`` for this and other options the script accepts. An
+important aspect of configuration is how to detect the current addresses of the
+machine the script is running on. For IPv4, this can only be "web", which can
+deal with NAT. For IPv6, the script can alternatively attempt to detect the
+correct local address to use. The sample file contains comments that should
+explain everything.
+
+Note that the script can update a list of domain names, in case you need the
+machine to have several names. It is preferable to use a CNAME instead, this
+will reduce the number of updates performed in the zone.
To run the script regularly, simply set up a cronjob. You can do so by running
``crontab -e``, and add a line as follows::
Source, License
---------------
-You can find the sources in the `git repository`_. They are provided under a
-2-clause BSD license.
+You can find the sources in the `git repository`_ and `on GitHub`_. They are
+provided under a `2-clause BSD license`_. See the file ``LICENSE-BSD`` for more
+details.
.. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
+.. _on GitHub: https://github.com/RalfJung/dyn-nsupdate
+.. _2-clause BSD license: http://opensource.org/licenses/bsd-license.php
Contact
-------
If you found a bug, or want to leave a comment, please
-`send me a mail <mailto:post-AT-ralfj-DOT-de>`_.
+`send me a mail <mailto:post-AT-ralfj-DOT-de>`_. All sorts of feedback are
+welcome :)