<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 to describe how to synchronize
content of those keytabs or a single 'disabled' value to disable the
synchronization.

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 four forms:
<programlisting>
account_name
sync_spns
spn_prefixes=value1[,value2[...]]
spns=value1[,value2[...]]
</programlisting>
No other combinations are allowed.
</para>

<para>
Specifiers:
<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.
</programlisting>
</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"/>
machine_password         - mandatory, if missing the entry is ignored. For future use.
</programlisting>
</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.
</para>

<para>
If no value is present and <smbconfoption name="kerberos method"/> is different from
'secrets only', the behavior differs between winbind and net utility:
</para>
<itemizedlist>
        <listitem>
                <para><userinput>winbind</userinput> uses value
                      <programlisting>/path/to/keytab: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>
        </listitem>
        <listitem>
                <para><userinput>net changesecretpw -f</userinput> command uses the default 'disabled' value.</para>
        </listitem>
        <listitem><para>No other <userinput>net</userinput> subcommands use the 'disabled' value.</para></listitem>
</itemizedlist>

<para>
If a single value 'disabled' is present, the synchronization process is
disabled. This is required for FreeIPA domain member setup where keytab
synchronization uses a protocol not implemented by Samba.
</para>

<para>
    Suggested configuration is together with <smbconfoption name="kerberos method"/> set to the default value 'secrets only'.
</para>

<para>
    In clustered environments it is recommended to set <smbconfoption name="sync machine password script"/> to update the machine password on all nodes.
</para>
</description>
</samba:parameter>
