docs: Rewrite snf-network-dnshook

Mention correctly when it runs and be more informative wrt
nsupdate authentication methods supported (TSIG for bind9
and GSS-TSIG for AD).
Signed-off-by: Dimitris Aragiorgis <dimara@grnet.gr>

docs/index.rst

@@ -216,25 +216,35 @@ neighbor proxy entry related to an instance's IPv6 on the source node.
 Otherwise the traffic would continue to go via the source node since
 there would be two nodes proxy-ing this IP.
 
+.. _snf-network-dnshook:
 
 snf-network-dnshook
 """""""""""""""""""
 
-Installed under `instance-stop-post.d`, `instance-rename-post.d` and
-`instance-remove-post.d` hook dirs.
+Installed under `instance-add-post.d`, `instance-rename-post.d`,
+`instance-remove-post.d` and `instance-modify-post.d` hook dirs.
 
-This hook updates an external `DDNS <https://wiki.debian.org/DDNS>`_
-setup via ``nsupdate``. To do so, the path to a valid keyfile, along
-with the nameserver must be added in settings
-(/etc/default/snf-network).
+Currently it supports dynamic updates against a BIND server or
+secure Microsoft DNS (Active Directory) by using the `nsupdate`
+command (found in `dnsutils` debian package).
 
-To authenticate against an AD controller using Kerberos, snf-network uses
-the -g option of nsupdate (GSS-TSIG mode). Prior to that it uses "k5start
--H" to ensure there is a happy ticket (stored under /var/lib/snf-network;
-see KERBEROS_TICKET default option), otherwise use a keytab containing
-the password to obtain a ticket automatically (password-less). The
-keytab with the corresponding service principal must already exist and
-both should be mentioned in the settings.
+On both cases, to enable it, the admin must set the SERVER (the IP of
+the DNS server) and FZONE (the domain of the instances) variables found
+in `/etc/default/snf-network`. Please note that currenlty only one
+domain is supported for the instances.
+
+In case of BIND (e.g `DDNS <https://wiki.debian.org/DDNS>`_),
+the KEYFILE variable in `/etc/default/snf-network` must point to
+the .private file created by dnssec-keygen.
+
+To authenticate against an AD controller using Kerberos, snf-network
+uses the -g option of nsupdate (GSS-TSIG mode). Prior to that, it uses
+"k5start -H" to ensure there is a happy ticket (stored under
+/var/lib/snf-network; see KERBEROS_TICKET default option). In case the
+ticket is invalid, it will use a keytab containing the password and it
+will try to obtain a ticket automatically (password-less). The keytab
+with the corresponding service principal must already exist and both
+should be mentioned in the settings.
 
 To add a valid keytab one can use:
 
@@ -242,15 +252,17 @@ To add a valid keytab one can use:
 
  ktutil -v add -V 1 -e aes256-cts -p SYNNEFO.NSUPDATE
 
-``dnsutils`` debian packages includes ``nsupdate`` client while
 ``kstart`` and ``heimdal-clients`` packages are required in case
 kerberos authentication is desired.
 
-Since we add/remove entries during ifup/ifdown
-scripts, we use this only during instance remove/shutdown/rename. It
-does not rely on exported environment but it queries first the DNS
-server to obtain current entries and then it invokes the necessary
-commands to remove them (and the relevant reverse ones too).
+In general this hook relies on the exported enviroment and according to
+the opcode it updates the external DNS server.
+
+Upon instance modification it first queries the DNS server to obtain
+current entries, then removes them (along with their reverse ones) and
+then re-adds any entries needed. This is done, because currently the
+environment exported by Ganeti includes the whole instance's state and
+does not explicitly mention the changes made.
 
 
 .. _setups:
@@ -327,12 +339,8 @@ dns
 snf-network can update an external `DDNS
 <https://wiki.debian.org/DDNS>`_ server. If the `dns` network tag is
 found, `snf-network-dnshook` will use `nsupdate` and add/remove entries
-related to the interface that is being managed. To enable it the admin
-must set the SERVER (the IP of the DNS server), FZONE (the domain of the
-instances), KEYFILE (the .private file created by dnssec-keygen)
-variables found in `/etc/default/snf-network`. Please note that
-currenlty only one domain is supported for the instances.
-
+related to the interface that is being managed. For more details see
+`snf-network-dnshook`_.
 
 nfdhcpd
 ^^^^^^^