start writing a documentation

diff --git a/.gitignore b/.gitignore
index 378eac25d311703f3f2cd456d8036da525cd0366..acd1c739261a809e63445a30c43fd7124085761c 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 build
+README.html

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..5612bbb
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,91 @@
+dyn-nsupdate: Dynamically and securely update DNS zones via CGI
+===============================================================
+
+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.
+
+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 
+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.
+
+.. _dyn-nsupdate: https://www.ralfj.de/projects/dyn-nsupdate
+.. _BIND: https://www.isc.org/downloads/bind/
+.. _CGI: https://en.wikipedia.org/wiki/Common_Gateway_Interface
+.. _Python: https://www.python.org/
+
+Server Setup
+------------
+
+In the following, replace ``dyn.example.com`` by whatever domain will be managed 
+through DynDNS. I assume that BIND has already been set up for 
+``dyn.example.com`` as a dynamic zone that can be updated through ``nsupdate 
+-l``. This can be achieved by setting ``update-policy local;`` in the zone 
+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 
+webserver.
+
+Let's start with 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
+  cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=/var/lib/bind/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::
+
+  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
+
+Finally, edit the config file. The format should be pretty self-explanatory. In 
+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 
+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 
+``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!
+
+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 
+appropriately for CGI scripts to be executed there. You can find a sample 
+configuration for apache in ``apache-ns.example.com.conf``. If you used a 
+non-default location for the ``dyn-nsupdate`` wrapper, you have to change the 
+path in the ``update`` CGI script accordingly.
+
+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'
+
+
+Source, License
+---------------
+
+You can find the sources in the `git repository`_. They are provided under a 
+2-clause BSD license.
+
+.. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
+
+Contact
+-------
+
+If you found a bug, or want to leave a comment, please
+`send me a mail <mailto:post-AT-ralfj-DOT-de>`_.

diff --git a/apache-ns.example.com.conf b/apache-ns.example.com.conf
new file mode 100644 (file)
index 0000000..d1ff42b
--- /dev/null
+++ b/apache-ns.example.com.conf
@@ -0,0 +1,14 @@
+<VirtualHost *:443>
+    ServerName ns.example.com
+    ServerAlias ipv4.ns.example.com ipv6.ns.example.com
+    DocumentRoot /srv/ns.example.com
+
+    # add your SSL configuration here
+
+    # allow access and CGI
+    <Directory /srv/ns.example.com>
+        Allow from all
+        SetHandler cgi-script
+        Options +ExecCGI
+    </Directory>
+</VirtualHost>

diff --git a/dyn-nsupdate.conf.dist b/dyn-nsupdate.conf.dist
new file mode 100644 (file)
index 0000000..96af7c7
--- /dev/null
+++ b/dyn-nsupdate.conf.dist
@@ -0,0 +1,4 @@
+nsupdate = /usr/bin/nsupdate
+
+[test.dyn.example.com]
+password = some_secure_password