e1426d476125eb2c6e9b2a7f89e2c4c8b8bce47e
[dyn-nsupdate.git] / README.rst
1 dyn-nsupdate: Self-made DynDNS
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 with your own nameserver. Both IPv4 and IPv6 are fully
9 supported.
10
11 dyn-nsupdate consists of two pieces: The server part provides a way to update IP 
12 addresses in Bind's DNS zones via CGI, in a safe manner. The client part uses CGI
13 to update some domain to the current address(es) of the machine it is running 
14 on. Alternatively, some routers can be configured to do this themselves. The 
15 FritzBox is known to be supported.
16
17 .. _dyn-nsupdate: https://www.ralfj.de/projects/dyn-nsupdate
18 .. _BIND: https://www.isc.org/downloads/bind/
19 .. _CGI: https://en.wikipedia.org/wiki/Common_Gateway_Interface
20 .. _Python: https://www.python.org/
21
22 Server Setup
23 ------------
24
25 In the following, replace ``dyn.example.com`` by whatever domain will be managed 
26 through DynDNS. I assume that BIND has already been set up for 
27 ``dyn.example.com`` as a dynamic zone that can be updated through ``nsupdate 
28 -l``. This can be achieved by setting ``update-policy local;`` in the zone 
29 configuration. Furthermore, I assume the directory ``/var/lib/bind/`` exists.
30
31 There are two pieces that have to be installed: A setuid wrapper which checks 
32 the passwords, and applies the updates; and some CGI scripts offered through a 
33 webserver. Please read this guide carefully and make sure you understand the
34 security implications of what you are doing. setuid wrappers are not toys!
35
36 Let's first set up the setuid wrapper. To compile it, you will need cmake and 
37 boost, including the regex and program_options boost packages. Starting in the 
38 source directory, run::
39
40   cd nsupd-wrapper
41   mkdir -p build
42   cd build
43   DIR=/var/lib/bind
44   cmake .. -DCMAKE_BUILD_TYPE=Release -DDYNNSUPDATE_CONFIG_FILE=$DIR/dyn-nsupdate.conf
45   make
46
47 This should compile the binary ``dyn-nsupdate``. Notice that the path to the 
48 configuration file will be hard-coded into the binary. If it were run-time 
49 configurable, then a user could call the script with her own configuration file, 
50 gaining access to all domains BIND lets you configure. If you want to put the 
51 files in another directory, change the configuration file name accordingly. Make 
52 sure the file (and all of the directories it is in) can *not be written by 
53 non-root*. The setuid wrapper trusts that file. You can now install it and the 
54 sample configuration file, and set their permissions::
55
56   sudo install dyn-nsupdate $DIR/dyn-nsupdate -o bind -g bind -m +rx,u+ws
57   sudo install ../../dyn-nsupdate.conf.dist $DIR/dyn-nsupdate.conf -o bind -g bind -m u+rw
58
59 Finally, edit the config file. The format should be pretty self-explanatory. In 
60 particular, **change the password**!
61
62 Now, let's go on with the CGI scripts. They are using Python 2, so make sure you 
63 have that installed. There are two scripts: One is used for clients to detect 
64 their current external IP address, and one is used to do the actual update of 
65 the domain. The first script is used by the "web" IP detection method (see 
66 client configuration below). It should be available on a domain that is 
67 available only through a single protocol, i.e., IPv4 only or IPv6 only. This is 
68 required to reliably detect the current address of the given protocol. If you 
69 want to support both IPv4 and IPv6, I suggest you have three domains 
70 ``ipv4.ns.example.com``, ``ipv6.ns.example.com`` and ``ns.example.com`` where 
71 only the latter is available via both protocols (this is something you have to 
72 configure in your ``example.com`` DNS zone). All can serve the same scripts 
73 (e.g. via a ``ServerAlias`` in the apache configuration). I also **strongly 
74 suggest** you make these domains *HTTPS-only*, as the client script will send a 
75 password!
76
77 Choose some directory (e.g., ``/srv/ns.example.com``) for the new domain, and 
78 copy the content of ``server-scripts`` there. Now configure your webserver 
79 appropriately for CGI scripts to be executed there. You can find a sample 
80 configuration for apache in ``apache-ns.example.com.conf``. If you used a 
81 non-default location for the ``dyn-nsupdate`` wrapper, you have to change the 
82 path in the ``update`` CGI script accordingly.
83
84 That's it! Your server is now configured. You can use ``curl`` to test your 
85 setup::
86
87   DOMAIN=test.dyn.example.com
88   PW=some_secure_password
89   curl 'https://ns.example.com/update?domain=$DOMAIN&password=$PW&ip=127.0.0.1'
90
91
92 Client setup (using the script)
93 -------------------------------
94
95 You can find the client script at ``client-scripts/dyn-ns-client``. It requires 
96 Python 3. Copy that script to the machine that should be available under the 
97 dynamic domain. Also copy the sample configuration file 
98 ``dyn-ns-client.conf.dist`` to ``$HOME/.config/dyn-nsupdate/dyn-ns-client.conf``.
99 You can choose another name, but then you will have to tell the script about it. 
100 Call ``dyn-ns-client --help`` for this and other options the script accepts. An 
101 important aspect of configuration is how to detect the current addresses of the 
102 machine the script is running on. For IPv4, this can only be "web", which can 
103 deal with NAT. For IPv6, the script can alternatively attempt to detect the 
104 correct local address to use. The sample file contains comments that should 
105 explain everything.
106
107 Note that the script can update a list of domain names, in case you need the 
108 machine to have several names. It is preferable to use a CNAME instead, this 
109 will reduce the number of updates performed in the zone.
110
111 To run the script regularly, simply set up a cronjob. You can do so by running 
112 ``crontab -e``, and add a line as follows::
113
114   */15 * * * * /home/user/dyn-ns-client
115
116 This sets the update interval to 15min. If your IP address changes daily, you 
117 may want to reduce this to 5min to have a smaller timeframe during which your 
118 server is not available.
119
120 Client setup (using a router)
121 -----------------------------
122
123 Some routers are able to perform the update of the domain names themselves. The 
124 FritzBox is known to be supported. To configure it to tell your server about the 
125 current IP address, go to the DynDNS configuration section of the FritzBox and 
126 choose the "custom" DynDNS provider. Then enter the following settings:
127
128 - Update-URL: ``https://ns.example.com/update?domain=<domain>&password=<pass>&ip=<ipaddr>``
129 - Domain Name: ``test.dyn.example.com``
130 - User Name: ``just_something``
131 - Password: ``some_secure_password``
132
133 Note that the user name is ignored.
134
135
136
137 Source, License
138 ---------------
139
140 You can find the sources in the `git repository`_ and `on GitHub`_. They are 
141 provided under a `2-clause BSD license`_. See the file ``LICENSE-BSD`` for more 
142 details.
143
144 .. _git repository: http://www.ralfj.de/git/dyn-nsupdate.git
145 .. _on GitHub: https://github.com/RalfJung/dyn-nsupdate
146 .. _2-clause BSD license: http://opensource.org/licenses/bsd-license.php
147
148 Contact
149 -------
150
151 If you found a bug, or want to leave a comment, please
152 `send me a mail <mailto:post-AT-ralfj-DOT-de>`_. All sorts of feedback are
153 welcome :)