Added a link, clarified wording

diff --git a/docs/dnsupdate.rst b/docs/dnsupdate.rst
index c898a73186b703515b259ecbaf997c307bf98495..234abf84abafca4e9395d1b9446500c4d5a3a68e 100644 (file)
--- a/docs/dnsupdate.rst
+++ b/docs/dnsupdate.rst
@@ -110,7 +110,8 @@ TSIG-ALLOW-DNSUPDATE
 
 This setting allows you to set the TSIG key required to do an DNS
 update. If you have GSS-TSIG enabled, you can use Kerberos principals
-here. An example, using :program:`pdnsutil` to create the key::
+here. Here is an example using :program:`pdnsutil` to create a key named
+`test`::
 
     $ pdnsutil generate-tsig-key test hmac-sha512
     Create new TSIG key test hmac-sha512 jMp41zXrTRKa9l9EGMj+9I9AL8exyIjXBdkFuNMJKv/UpNd83kFt+CrHQpuqBI8lf28xH1SrOFN1mr7QzOe7pQ==
@@ -118,13 +119,16 @@ here. An example, using :program:`pdnsutil` to create the key::
     $ pdnsutil list-tsig-keys | grep test
     test. hmac-sha512. jMp41zXrTRKa9l9EGMj+9I9AL8exyIjXBdkFuNMJKv/UpNd83kFt+CrHQpuqBI8lf28xH1SrOFN1mr7QzOe7pQ==
 
-Then adding that key with the name `test` and add the metadata::
+This adds the key with the name `test` to the zone's metadata. Note, the
+keys need to be added separately with `add-meta`, not as a comma or
+space-separated list::
 
     $ pdnsutil add-meta example.org TSIG-ALLOW-DNSUPDATE test
     $ pdnsutil get-meta example.org TSIG-ALLOW-DNSUPDATE
     TSIG-ALLOW-DNSUPDATE = test
 
-An example of how to use a TSIG key with the :program:`nsupdate` command::
+This is an example of using the new `test` TSIG key with the :program:`nsupdate`
+command (see the manpage for :program:`nsupdate` for full details)::
 
     $ nsupdate <<!
     server 127.0.0.1 53
@@ -140,10 +144,14 @@ An example of how to use a TSIG key with the :program:`nsupdate` command::
     test1.example.org. 3600    IN      A       1.2.3.4
     test1.example.org. 3600    IN      TXT     "this is a test"
 
-If any TSIG keys are listed in ``TSIG-ALLOW-DNSUPDATE`` for the zone, one of
-them is required to be used for an update.  If ``ALLOW-DNSUPDATE-FROM`` is also set,
+If any TSIG keys are listed in a zone's ``TSIG-ALLOW-DNSUPDATE`` metadata, one
+of them is required for updates. If ``ALLOW-DNSUPDATE-FROM`` is also set,
 both requirements need to be satisfied before an update will be accepted.
 
+By default, an update can add, update or delete any resource records in
+the zone.  See :ref:`dnsupdate-update-policy` for finer-grained
+control of what an update is allowed to do.
+
 .. _metadata-forward-dnsupdate:
 
 FORWARD-DNSUPDATE