From: Mark Andrews <marka@isc.org>
Date: Fri, 24 Aug 2018 02:16:14 +0000 (+1000)
Subject: update {krb5,ms}-{self,subdomain} descriptions
X-Git-Tag: v9.13.3~35^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0370d136673052dbe18e830182e73278bbba9c21;p=thirdparty%2Fbind9.git

update {krb5,ms}-{self,subdomain} descriptions
---

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index 7dc6bba2791..4530c0876ed 100644
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -12699,7 +12699,7 @@ example.com. NS ns2.example.net.
 	      has been used to create a shared secret, the identity of
 	      the key used to authenticate the TKEY exchange will be
 	      used as the identity of the shared secret.  Some rule types
-	      use indentities matching the client's Kerberos principal
+	      use identities matching the client's Kerberos principal
 	      (e.g, <userinput>"host/machine@REALM"</userinput>) or
 	      Windows realm (<userinput>machine$@REALM</userinput>).
 	    </para>
@@ -12860,12 +12860,26 @@ example.com. NS ns2.example.net.
 		      </para>
 		    </entry> <entry colname="2">
 		      <para>
-			This rule takes a Windows machine principal
-			(machine$@REALM) for machine in REALM and
-			and converts it machine.realm allowing the machine
-			to update machine.realm.  The REALM to be matched
-			is specified in the <replaceable>identity</replaceable>
-			field.  The name field should be set to "."
+			When a client sends an UPDATE using a Windows
+			machine principal (for example, 'machine$@REALM'),
+			this rule allows records with the absolute name
+			of 'machine.REALM' to be updated.
+		      </para>
+		      <para>
+			The realm to be matched is specified in the
+			<replaceable>identity</replaceable> field.
+		      </para>
+		      <para>
+			The <replaceable>name</replaceable> field has
+			no effect on this rule; it should be set to "."
+			as a placeholder.
+		      </para>
+		      <para>
+			For example,
+			<userinput>grant EXAMPLE.COM ms-self . A AAAA</userinput>
+			allows any machine with a valid principal in
+			the realm <userinput>EXAMPLE.COM</userinput> to update
+			its own address records.
 		      </para>
 		    </entry>
 		  </row>
@@ -12876,13 +12890,32 @@ example.com. NS ns2.example.net.
 		      </para>
 		    </entry> <entry colname="2">
 		      <para>
-			This rule takes a Windows machine principal
-			(machine$@REALM) for machine in REALM and
-			converts it to machine.realm allowing the machine
-			to update subdomains of machine.realm.  The REALM
-			to be matched is specified in the
+			When a client sends an UPDATE using a Windows
+			machine principal (for example, 'machine$@REALM'),
+			this rule allows any machine in the specified
+			realm to update any record in the zone or in a
+			specified subdomain of the zone.
+		      </para>
+		      <para>
+			The realm to be matched is specified in the
 			<replaceable>identity</replaceable> field.
 		      </para>
+		      <para>
+			The <replaceable>name</replaceable> field
+			specifies the subdomain that may be updated.
+			If set to "." (or any other name at or above
+			the zone apex), any name in the zone can be
+			updated.
+		      </para>
+		      <para>
+			For example, if <command>update-policy</command>
+			for the zone "example.com" includes
+			<userinput>grant EXAMPLE.COM ms-subdomain hosts.example.com. A AAAA</userinput>,
+			any machine with a valid principal in
+			the realm <userinput>EXAMPLE.COM</userinput> will
+			be able to update address records at or below
+			"hosts.example.com".
+		      </para>
 		    </entry>
 		  </row>
 		  <row rowsep="0">
@@ -12892,12 +12925,32 @@ example.com. NS ns2.example.net.
 		      </para>
 		    </entry> <entry colname="2">
 		      <para>
-			This rule takes a Kerberos machine principal
-			(host/machine@REALM) for machine in REALM and
-			and converts it machine.realm allowing the machine
-			to update machine.realm.  The REALM to be matched
-			is specified in the <replaceable>identity</replaceable>
-			field. The name field should be set to "."
+			When a client sends an UPDATE using a
+			Kerberos machine principal (for example,
+			'host/machine@REALM'), this rule allows
+			records with the absolute name of 'machine'
+			to be updated provided it has been authenticated
+			by REALM.  This is similar but not identical
+			to <command>ms-self</command> due to the
+			'machine' part of the Kerberos principal
+			being an absolute name instead of a unqualified
+			name.
+		      </para>
+		      <para>
+			The realm to be matched is specified in the
+			<replaceable>identity</replaceable> field.
+		      </para>
+		      <para>
+			The <replaceable>name</replaceable> field has
+			no effect on this rule; it should be set to "."
+			as a placeholder.
+		      </para>
+		      <para>
+			For example,
+			<userinput>grant EXAMPLE.COM krb5-self . A AAAA</userinput>
+			allows any machine with a valid principal in
+			the realm <userinput>EXAMPLE.COM</userinput> to update
+			its own address records.
 		      </para>
 		    </entry>
 		  </row>
@@ -12908,13 +12961,11 @@ example.com. NS ns2.example.net.
 		      </para>
 		    </entry> <entry colname="2">
 		      <para>
-			This rule takes a Kerberos machine principal
-			(host/machine@REALM) for machine in REALM and
-			converts it to machine.realm allowing the machine
-			to update subdomains of machine.realm.  The REALM
-			to be matched is specified in the
-			<replaceable>identity</replaceable> field. The
-			name field should be set to "."
+			This rule is identical to
+			<command>ms-subdomain</command>, except that it works
+			with Kerberos machine principals (i.e.,
+			'host/machine@REALM') rather than Windows machine
+			principals.
 		      </para>
 		    </entry>
 		  </row>