complete documentation with client setup

diff --git a/README.rst b/README.rst
index 5612bbb19da7aca0dc43571a36965aef92e654ae..6a4054f989da4df47d3b58aec0df70a8d2c09e00 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -73,7 +73,46 @@ 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'
+  curl 'https://ns.example.com/update?domain=test.dyn.example.com&password=some_secure_password&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. 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.
+
+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

diff --git a/client-scripts/dyn-ns-client b/client-scripts/dyn-ns-client
index 6ab8c54e59cc007059aaf89bfad5df6c9248e34a..0fc88e6fc978f3195f4c2d4b6b4e1740c930fd0d 100755 (executable)
--- a/client-scripts/dyn-ns-client
+++ b/client-scripts/dyn-ns-client
@@ -25,19 +25,20 @@
 # The views and conclusions contained in the software and documentation are those
 # of the authors and should not be interpreted as representing official policies, 
 # either expressed or implied, of the FreeBSD Project.
-
-import urllib.request, socket, sys, argparse
-
+#==============================================================================
 # configuration variables
-domains = ['domain.dyn.ralfj.de'] # list of domains to update
-password = 'yourpassword'
+domains = ['test.dyn.example.com'] # list of domains to update
+password = 'some_secure_password'
 haveIPv4 = True
 haveIPv6 = False
 
-serverIPv4 = 'ipv4.ns.ralfj.de' # Only needed if haveIPv4 is True. This server should NOT have an AAAA record!
-serverIPv6 = 'ipv6.ns.ralfj.de' # Only needed if haveIPv6 is True. This server should NOT have an A record!
-server     = 'ns.ralfj.de'
+serverIPv4 = 'ipv4.ns.example.com' # Only needed if haveIPv4 is True. This server should NOT have an AAAA record!
+serverIPv6 = 'ipv6.ns.example.com' # Only needed if haveIPv6 is True. This server should NOT have an A record!
+server     = 'ns.example.com'
 # END of configuration variables
+#==============================================================================
+
+import urllib.request, socket, sys, argparse
 
 def urlopen(url):
     return urllib.request.urlopen(url).read().decode('utf-8').strip()