X-Git-Url: https://git.ralfj.de/dyn-nsupdate.git/blobdiff_plain/86d574acc0ee6945936ce655b3b41887e2820b0a..3958c85bcd50e23773ab6f08f087936fcd3cf050:/README.rst diff --git a/README.rst b/README.rst index 399448a..b7dad71 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ dyn-nsupdate: Self-made DynDNS -=============================================================== +============================== Introduction ------------ @@ -30,25 +30,31 @@ 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. +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 setting 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 - 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 -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 (nor any 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 particular, **change the password**! @@ -56,14 +62,17 @@ 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 +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 -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 @@ -85,13 +94,19 @@ 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. +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:: @@ -131,4 +146,5 @@ Contact ------- If you found a bug, or want to leave a comment, please -`send me a mail `_. +`send me a mail `_. All sorts of feedback are +welcome :)