rename COPYING
[dyn-nsupdate.git] / README.rst
index 5612bbb19da7aca0dc43571a36965aef92e654ae..e1426d476125eb2c6e9b2a7f89e2c4c8b8bce47e 100644 (file)
@@ -1,14 +1,15 @@
-dyn-nsupdate: Dynamically and securely update DNS zones via CGI
-===============================================================
+dyn-nsupdate: Self-made DynDNS
+==============================
 
 Introduction
 ------------
 
 Welcome to dyn-nsupdate_, a collection of tools using BIND_, CGI_ and Python_ to 
 
 Introduction
 ------------
 
 Welcome to dyn-nsupdate_, a collection of tools using BIND_, CGI_ and Python_ to 
-provide DynDNS services. Both IPv4 and IPv6 are fully supported.
+provide DynDNS services with your own nameserver. Both IPv4 and IPv6 are fully
+supported.
 
 dyn-nsupdate consists of two pieces: The server part provides a way to update IP 
 
 dyn-nsupdate consists of two pieces: The server part provides a way to update IP 
-addresses in Bind's DNS zone via CGI, in a safe manner. The client part uses CGI 
+addresses in Bind's DNS zones via CGI, in a safe manner. The client part uses CGI
 to update some domain to the current address(es) of the machine it is running 
 on. Alternatively, some routers can be configured to do this themselves. The 
 FritzBox is known to be supported.
 to update some domain to the current address(es) of the machine it is running 
 on. Alternatively, some routers can be configured to do this themselves. The 
 FritzBox is known to be supported.
@@ -29,39 +30,49 @@ configuration. Furthermore, I assume the directory ``/var/lib/bind/`` exists.
 
 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 
 
 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::
 
   cd nsupd-wrapper
   mkdir -p build
   cd build
 boost, including the regex and program_options boost packages. Starting in the 
 source directory, run::
 
   cd nsupd-wrapper
   mkdir -p build
   cd build
-  cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=/var/lib/bind/dyn-nsupdate.conf
+  DIR=/var/lib/bind
+  cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=$DIR/dyn-nsupdate.conf
   make
 
   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 /var/lib/bind/dyn-nsupdate -o bind -g bind -m +rx,u+ws
-  sudo install ../../dyn-nsupdate.conf /var/lib/bind/dyn-nsupdate.conf -o bind -g bind -m u+rw
+  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
 
 Finally, edit the config file. The format should be pretty self-explanatory. In 
 
 Finally, edit the config file. The format should be pretty self-explanatory. In 
-particular, *change the password*!
+particular, **change the password**!
 
 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 
 
 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 
 ``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 
 
 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 
@@ -73,19 +84,70 @@ path in the ``update`` CGI script accordingly.
 That's it! Your server is now configured. You can use ``curl`` to test your 
 setup::
 
 That's it! Your server is now configured. You can use ``curl`` to test your 
 setup::
 
-  curl 'https://ns.example.com/update?domain=tests.dyn.example.com&password=some_secure_password&ip=127.0.0.1'
+  DOMAIN=test.dyn.example.com
+  PW=some_secure_password
+  curl 'https://ns.example.com/update?domain=$DOMAIN&password=$PW&ip=127.0.0.1'
+
+
+Client setup (using the script)
+-------------------------------
+
+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. 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::
+
+  */15 * * * * /home/user/dyn-ns-client
+
+This sets the update interval to 15min. If your IP address changes daily, you 
+may want to reduce this to 5min to have a smaller timeframe during which your 
+server is not available.
+
+Client setup (using a router)
+-----------------------------
+
+Some routers are able to perform the update of the domain names themselves. The 
+FritzBox is known to be supported. To configure it to tell your server about the 
+current IP address, go to the DynDNS configuration section of the FritzBox and 
+choose the "custom" DynDNS provider. Then enter the following settings:
+
+- Update-URL: ``https://ns.example.com/update?domain=<domain>&password=<pass>&ip=<ipaddr>``
+- Domain Name: ``test.dyn.example.com``
+- User Name: ``just_something``
+- Password: ``some_secure_password``
+
+Note that the user name is ignored.
+
 
 
 Source, License
 ---------------
 
 
 
 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
 
 .. _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
 
 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 :)