6a4054f989da4df47d3b58aec0df70a8d2c09e00
[dyn-nsupdate.git] / README.rst
1 dyn-nsupdate: Dynamically and securely update DNS zones via CGI
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. Both IPv4 and IPv6 are fully supported.
9
10 dyn-nsupdate consists of two pieces: The server part provides a way to update IP 
11 addresses in Bind's DNS zone via CGI, in a safe manner. The client part uses CGI 
12 to update some domain to the current address(es) of the machine it is running 
13 on. Alternatively, some routers can be configured to do this themselves. The 
14 FritzBox is known to be supported.
15
16 .. _dyn-nsupdate: https://www.ralfj.de/projects/dyn-nsupdate
17 .. _BIND: https://www.isc.org/downloads/bind/
18 .. _CGI: https://en.wikipedia.org/wiki/Common_Gateway_Interface
19 .. _Python: https://www.python.org/
20
21 Server Setup
22 ------------
23
24 In the following, replace ``dyn.example.com`` by whatever domain will be managed 
25 through DynDNS. I assume that BIND has already been set up for 
26 ``dyn.example.com`` as a dynamic zone that can be updated through ``nsupdate 
27 -l``. This can be achieved by setting ``update-policy local;`` in the zone 
28 configuration. Furthermore, I assume the directory ``/var/lib/bind/`` exists.
29
30 There are two pieces that have to be installed: A setuid wrapper which checks 
31 the passwords, and applies the updates; and some CGI scripts offered through a 
32 webserver.
33
34 Let's start with the setuid wrapper. To compile it, you will need cmake and 
35 boost, including the regex and program_options boost packages. Starting in the 
36 source directory, run::
37
38   cd nsupd-wrapper
39   mkdir -p build
40   cd build
41   cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=/var/lib/bind/dyn-nsupdate.conf
42   make
43
44 This should compile the binary ``dyn-nsupdate``. If you want to put the files in 
45 another directory, change the configuration file name accordingly. You can now 
46 install it and the sample configuration file, and set their permissions::
47
48   sudo install dyn-nsupdate /var/lib/bind/dyn-nsupdate -o bind -g bind -m +rx,u+ws
49   sudo install ../../dyn-nsupdate.conf /var/lib/bind/dyn-nsupdate.conf -o bind -g bind -m u+rw
50
51 Finally, edit the config file. The format should be pretty self-explanatory. In 
52 particular, *change the password*!
53
54 Now, let's go on with the CGI scripts. They are using Python 2, so make sure you 
55 have that installed. There are two scripts: One is used for clients to detect 
56 their current external IP address, and one is used to do the actual update of 
57 the domain. The first script should be available on a domain that is available 
58 only through a single protocol, i.e., IPv4 only or IPv6 only. If you want to 
59 support both IPv4 and IPv6, I suggest you have three domains 
60 ``ipv4.ns.example.com``, ``ipv6.ns.example.com`` and ``ns.example.com`` where 
61 only the latter is available via both protocols (this is something you have to 
62 configure in your ``example.com`` zone). All can serve the same scripts (e.g. 
63 via a ``ServerAlias`` in the apache configuration). I also **strongly suggest** 
64 you make these domains *HTTPS-only*, as the client script will send a password!
65
66 Choose some directory (e.g., ``/srv/ns.example.com``) for the new domain, and 
67 copy the content of ``server-scripts`` there. Now configure your webserver 
68 appropriately for CGI scripts to be executed there. You can find a sample 
69 configuration for apache in ``apache-ns.example.com.conf``. If you used a 
70 non-default location for the ``dyn-nsupdate`` wrapper, you have to change the 
71 path in the ``update`` CGI script accordingly.
72
73 That's it! Your server is now configured. You can use ``curl`` to test your 
74 setup::
75
76   curl 'https://ns.example.com/update?domain=test.dyn.example.com&password=some_secure_password&ip=127.0.0.1'
77
78
79 Client setup (using the script)
80 -------------------------------
81
82 You can find the client script at ``client-scripts/dyn-ns-client``. It requires 
83 Python 3. Copy that script to the machine that should be available under the 
84 dynamic domain. Then change the configuration section at the top to match your 
85 setup. Note that the script can update a list of domain names, in case you need 
86 the machine to have several names (it is preferable to use a CNAME instead, this 
87 will reduce the number of updates performed in the zone). The ``serverIPv4`` and 
88 ``serverIPv6`` are only used if IPv4/IPv6 is enabled. These machines must be 
89 available with that protocol only, otherwise it is not possible to reliably 
90 detect the current external address.
91
92 To run the script regularly, simply set up a cronjob. You can do so by running 
93 ``crontab -e``, and add a line as follows::
94
95   */15 * * * * /home/user/dyn-ns-client
96
97 This sets the update interval to 15min. If your IP address changes daily, you 
98 may want to reduce this to 5min to have a smaller timeframe during which your 
99 server is not available.
100
101 Client setup (using a router)
102 -----------------------------
103
104 Some routers are able to perform the update of the domain names themselves. The 
105 FritzBox is known to be supported. To configure it to tell your server about the 
106 current IP address, go to the DynDNS configuration section of the FritzBox and 
107 choose the "custom" DynDNS provider. Then enter the following settings:
108
109 - Update-URL: ``https://ns.example.com/update?domain=<domain>&password=<pass>&ip=<ipaddr>``
110 - Domain Name: ``test.dyn.example.com``
111 - User Name: ``just_something``
112 - Password: ``some_secure_password``
113
114 Note that the user name is ignored.
115
116
117
118 Source, License
119 ---------------
120
121 You can find the sources in the `git repository`_. They are provided under a 
122 2-clause BSD license.
123
124 .. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
125
126 Contact
127 -------
128
129 If you found a bug, or want to leave a comment, please
130 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_.