docs:smbdotconf: Add parameter 'sync machine password to keytab'

BUG: https://bugzilla.samba.org/show_bug.cgi?id=6750

Signed-off-by: Pavel Filipenský <pfilipen@redhat.com>
Reviewed-by: Stefan Metzmacher <metze@samba.org>

diff --git a/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml b/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml
new file mode 100644 (file)
index 0000000..48d8921
--- /dev/null
+++ b/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml
@@ -0,0 +1,69 @@
+<samba:parameter name="sync machine password to keytab"
+                 context="G"
+                 type="cmdlist"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+    <para>This option allows you to describe what keytabs and how should be
+    updated when machine account is changed via one of these commands
+
+<programlisting>
+wbinfo --change-secret
+rpcclient --machine-pass -c change_trust_pw
+net rpc changetrustpw
+net ads changetrustpw
+</programlisting>
+
+    or by winbindd doing regular updates (see <smbconfoption name="machine password timeout"/>)
+
+</para>
+
+<para>The option takes a list of keytab strings. Each string has this form:
+
+<programlisting>
+    absolute_path_to_keytab:spn_spec[:sync_etypes][:sync_kvno][:netbios_aliases][:additional_dns_hostnames][:machine_password]
+</programlisting>
+
+    where spn_spec can have exactly one of these three forms:
+<programlisting>
+    account_name
+    sync_spns
+    spn_prefixes=value1[,value2[...]]
+    spns=value1[,value2[...]]
+</programlisting>
+<para>
+    No other combinations are allowed.
+
+    Specifiers:
+    account_name - creates entry using principal 'computer$@REALM'.
+    sync_spns   - uses principals received from AD DC.
+    spn_prefixes - creates principals from the prefixes and adds netbios_aliases or additional_dns_hostnames if specified.
+    spns    - creates only the principals defined in the list.
+
+    Options:
+    sync_etypes - parameter "msDS-SupportedEncryptionTypes" is read from DC and is used to find the highest common enc type for AD and KRB5 lib.
+    sync_kvno - the key version number ("msDS-KeyVersionNumber") is synchronized from DC, otherwise is set to -1.
+    netbios_aliases - evaluated only for SPN_SPEC_PREFIX. If present, PREFIX/netbiosname@REALM and PREFIX/netbiosname.domainname@REALM are added for each alias. See <smbconfoption name="netbios aliases"/>
+    additional_dns_hostnames - evaluated only for SPN_SPEC_PREFIX. If present, PREFIX/dnshostname@REALM is  added for each dns name. See <smbconfoption name="additional dns hostnames"/>
+    machine_password - mandatory, if missing the entry is ignored. For future use.
+</para>
+
+</para>
+<para>
+Example:
+<programlisting>
+    "/path/to/keytab0:account_name:machine_password",
+    "/path/to/keytab1:account_name:sync_etypes:sync_kvno:machine_password",
+    "/path/to/keytab2:sync_spns:machine_password",
+    "/path/to/keytab3:sync_spns:sync_kvno:machine_password",
+    "/path/to/keytab4:spn_prefixes=imap,smtp:machine_password",
+    "/path/to/keytab5:spn_prefixes=imap,smtp:netbios_aliases:additional_dns_hostnames:sync_kvno:machine_password",
+    "/path/to/keytab6:spns=wurst/brot@REALM:machine_password",
+    "/path/to/keytab7:spns=wurst/brot@REALM,wurst2/brot@REALM:sync_kvno:machine_password"
+</programlisting>
+If sync_etypes or sync_kvno or sync_spns is present then winbind connects to DC. For "offline domain join" it might be useful not to use these options.
+
+If no value is present, winbind uses value /path/to/keytab:sync_spns:sync_kvno:machine_password
+where the path to the keytab is obtained either from the krb5 library or from <smbconfoption name="dedicated keytab file"/>
+</para>
+</description>
+</samba:parameter>