docs-xml:smbdotconf: Document new options for 'sync machinepassword to keytab'

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

Signed-off-by: Pavel Filipenský <pfilipensky@samba.org>
Reviewed-by: Andreas Schneider <asn@samba.org>
Reviewed-by: Alexander Bokovoy <ab@samba.org>
Autobuild-User(master): Pavel Filipensky <pfilipensky@samba.org>
Autobuild-Date(master): Thu Feb 13 18:45:21 UTC 2025 on atb-devel-224

(cherry picked from commit 7a662e097be5e0d3f7779fa544486968b8f57063)

diff --git a/docs-xml/manpages/net.8.xml b/docs-xml/manpages/net.8.xml
index f388644172f9f30936f2f7a3cd7d184063fbe8f6..8091368a48ea183f6310787418888959be8767d3 100644 (file)
--- a/docs-xml/manpages/net.8.xml
+++ b/docs-xml/manpages/net.8.xml
@@ -1549,29 +1549,25 @@ to show in the result.
 
 <para>
 Since Samba 4.21.0, keytab file is created as specified in <smbconfoption
-name="sync machine password to keytab"/>. The keytab is created only for
+name="sync machine password to keytab"/> . The keytab can be created only when
+machine password is available in secrets.tdb, i.e. only for
 <smbconfoption name="kerberos method">secrets only</smbconfoption> and
 <smbconfoption name="kerberos method">secrets and keytab</smbconfoption>. With
 the smb.conf default values for <smbconfoption name="kerberos method"> secrets
 only</smbconfoption> and <smbconfoption name="sync machine password to keytab"/>
 (default is empty) the keytab is not generated at all.  Keytab with a default
-name and SPNs synced from AD is created for <smbconfoption name="kerberos
-method">secrets and keytab</smbconfoption> if <smbconfoption name="sync machine
-password to keytab"/> is missing.
+name containing: SPNs synced from AD, account name COMPUTER$ and principal
+host/dns_hostname is created for <smbconfoption name="kerberos method">secrets
+and keytab</smbconfoption> if <smbconfoption name="sync machine password to
+keytab"/> is missing.
 </para>
 <para>
-Till Samba 4.20.0, two more entries were created by default: the machinename of
-the client (ending with '$') and the UPN (host/domain@REALM).  If these two
-entries are still needed, each must be specified in an own keytab file.
-Example below will generate three keytab files that contain SPNs synced from
-AD, host UPN and machine$ SPN:
+Till Samba 4.20, these entries were created by default: the account name
+COMPUTER$, 'host' principal and SPNs synced from AD. Example below generates
+such keytab ('host' is added implicitly):
 </para>
 <programlisting>
-<smbconfoption name="sync machine password to keytab">
-/etc/krb5.keytab0:sync_spns:machine_password,
-/etc/krb5.keytab1:spns=host/smb.com@SMB.COM:machine_password,
-/etc/krb5.keytab2:account_name:machine_password
-</smbconfoption>
+<smbconfoption name="sync machine password to keytab">/etc/krb5.keytab:account_name:sync_spns:sync_kvno:machine_password</smbconfoption>
 </programlisting>
 <para>
 No changes are made to the computer AD account.

diff --git a/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml b/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml
index f7dc30023d4390627dda16e89a4113db7541584c..02eaf3162c00b41440ec32cbc49c995fdb0690f3 100644 (file)
--- a/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml
+++ b/docs-xml/smbdotconf/security/syncmachinepasswordtokeytab.xml
@@ -24,36 +24,49 @@ synchronization.
 
 Each string has this form:
 <programlisting>
-absolute_path_to_keytab:spn_spec[:sync_etypes][:sync_kvno][:netbios_aliases][:additional_dns_hostnames][:machine_password]
+absolute_path_to_keytab:spn_spec[:spn_spec]*[:sync_etypes][:sync_kvno][:netbios_aliases][:additional_dns_hostnames][:machine_password]
 </programlisting>
 
-where spn_spec can have exactly one of these four forms:
+spn_spec can be specified multiple times (separated using ':') and each spn_spec can have exactly one of these forms:
 <programlisting>
 account_name
+sync_account_name
+sync_upn
 sync_spns
 spn_prefixes=value1[,value2[...]]
 spns=value1[,value2[...]]
 </programlisting>
-No other combinations are allowed.
 </para>
 
 <para>
-Specifiers:
+Every keytab contains the 'host' principal and principals according the specification below:
 <programlisting>
-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.
+account_name      - COMPUTER$@REALM
+sync_account_name - uses attribute "sAMAccountName" from AD
+host              - always present, no need to specify it explicitly
+                    the 'host' principal is created for the same variants (netbios name, dns hostname, netbiosalias, additional_dns_hostname) as in spn_prefixes
+sync_upn          - uses attribute "userPrincipalName" (if exists in AD)
+sync_spns         - uses attribute "servicePrincipalName" (if exists in AD)
+spn_prefixes      - creates these two principals from each prefix. e.g.:
+                      prefix/<smbconfoption name="netbios name"/>@REALM
+                      prefix/<smbconfoption name="dns hostname"/>@REALM
+                    with :netbios_aliases for each netbiosalias in <smbconfoption name="netbios aliases"/>
+                      prefix/netbiosalias@REALM
+                      prefix/netbiosalias.dnsdomain@REALM
+                    with :additional_dns_hostnames for each additionaldnshostname in <smbconfoption name="additional dns hostnames"/>
+                      prefix/additionaldnshostname@REALM
+spns              - creates only the principals defined in the list
 </programlisting>
+'account_name' and 'sync_account_name' are the same, just the source differs (secrets.tdb vs. AD).
 </para>
 
 <para>
 Options:
 <programlisting>
-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"/>
+sync_etypes              - attribute "msDS-SupportedEncryptionTypes" is read from AD and is used to find the highest common enc type for AD and KRB5 lib.
+sync_kvno                - attribute "msDS-KeyVersionNumber" from AD is used to set KVNO. If this option is missing, KVNO is set to -1.
+netbios_aliases          - evaluated only for spn_prefixes (see details above) and for the 'host' principal.
+additional_dns_hostnames - evaluated only for spn_prefixes (see details above) and for the 'host' principal.
 machine_password         - mandatory, if missing the entry is ignored. For future use.
 </programlisting>
 </para>
@@ -68,7 +81,8 @@ Example:
 "/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"
+"/path/to/keytab7:spns=wurst/brot@REALM,wurst2/brot@REALM:sync_kvno:machine_password",
+"/path/to/keytab8:account_name:sync_account_name:host:sync_upn:sync_spns:spn_prefixes=cifs,http:spns=wurst/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.
 </para>
@@ -80,7 +94,7 @@ If no value is present and <smbconfoption name="kerberos method"/> is different
 <itemizedlist>
         <listitem>
                 <para><userinput>winbind</userinput> uses value
-                      <programlisting>/path/to/keytab:sync_spns:sync_kvno:machine_password</programlisting>
+                      <programlisting>/path/to/keytab:host:account_name:sync_spns:sync_kvno:machine_password</programlisting>
                       where the path to the keytab is obtained either from the krb5 library or from
                       <smbconfoption name="dedicated keytab file"/>.
                 </para>