View source for UCS@school Samba 3 to Samba 4 Migration

{{Version|school=3.0}}
{{Version|school=3.1}}

= Warning =
All steps described here schould be tested first in a non-productive snapshot of the main productive environment. A good starting point for creating a virtualised copy of the productive systems might be [[Migrating_a_native_UCS_installation_to_UVMM#Migration_by_copying_the_core_files|this Howto article]].

= Preparations for the Migration of UCS@school from Samba 3 to Samba 4 =
* Update of the entire domain to at least UCS@school 3.0.
* Ensure that all errata updates for UCS@school are installed.
* Make sure you know about the underlying conceptual differences between a Samba3/NT Domain and Samba4/Active Directory. We strongly recommend to review the existing setup to meet the changed requirements. If you are unsure about designing an Active Directory Domain please read the Microsoft documentation carefully or consult Univention Professional Services.
* All steps schould be tested first in a non-productive snapshot of the main productive environment.
* Before starting the update process, as usual, make sure up-to-date backups of all DCs are available.
* Before starting the update process, it is important to check the consistency of the LDAP data. As a starting point the following script should be run to ensure that all users are listed as members of their primary group:
<syntaxhighlight lang=bash>
/usr/share/univention-directory-manager-tools/proof_uniqueMembers
</syntaxhighlight>
* If the domain was originally updated from UCS 2.4 ensure that all existing Kerberos keys are properly migrated from the UCS 2.4 format to the UCS 3.x format run
<syntaxhighlight lang=bash>
/usr/share/univention-heimdal/salt_krb5Keys
</syntaxhighlight>
* Make shure that there are no Samba user accounts with the same name as any Samba group in the LDAP directory. Samba 4 does not tolerate this and will only accept uniquely named Samba account, irrespective if it is a group or a user account.
* Samba 4 does not evaluate the per-server UCR setting samba/profilepath. Instead Samba 4 uses the per-user LDAP attribute ''sambaProfilePath'', which can be set in the Univention Directory Manager in the field ''Windows profile directory'' in section ''Windows'' on the ''Account'' tab. Its value can be set via multiedit or via user-template. The directory name is an UNC-path and can contain Windows environment variables, e.g.
<syntaxhighlight lang=bash>
%LOGONSERVER%\%USERNAME%\windows-profiles\default
</syntaxhighlight>
* Samba/Active Directory relies a lot on Kerberos, which in turn relies on DNS. That's why it is very important to ensure that all Windows Clients are configured to use the UCS Samba/Active Directory server of the school site they are located at.

= Migration of UCS@school Samba 3/NT4 to a Samba 4/AD domain =
* It is advisable to do the stepwise upgrade of the UCS@school Samba 3/NT4 domain to a Samba 4/AD domain in a mainenance windows to avoid disturbance of productive systems.
* It is advisable to complete the update of all school DCs to Samba 4 before proceeding to the update the UCS@school systems in the central school department (with the DC Master) to Samba 4.
== Preparation of the UCS@school domain ==
* Make sure that the existing UCS Kerberos realm (UCR variable kerberos/realm) matches the DNS domainname (UCR variable domainname) of the UCS domain (not case sensitive). This is mandatory.
* Beware that as each school DC is updated to Samba 4 in turn all Samba 3 domain controllers have to be updated to Samba 4 at each individual school. Unexpected results may occur while any Samba 3 domain controllers are still active at a school where Samba 4 DCs have been installed. This is also important with regard to the update of the central school department.
== Migration of a school to Samba 4 ==
* In the UCS@school concept each school is treated as an organizational unit ("OU") in the LDAP directory. Usually each school has its own unique OU. Additionally UCS@school 3 with Samba 4 implements the Active Directory concept of ''sites'' and creates an AD-site for each OU. The name of the sites matches the name of the OUs. While the Samba 4 school DC concept in UCS@school 3.x AD-sites does not heavily rely on the AD-sites structure, it can be useful for GPO assignment or in other specific scenarios. Note that while originally AD-sites are used to influence the structure of the Active Directory replication between remote branch sites e.g. over wide area networks, this is not the use case in UCS@school, which uses selective OpenLDAP replication.
* Each UCS@school Slave DC runs his own Univention Samba 4 Connector to synchronize  identity management objects bidirectionally between OpenLDAP and the Samba 4 directory service.
* Replication between schools and the UCS@school DC Master at the central school department happens in the same way as in former versions of UCS@school, via selective LDAP replication.
=== Migration of the school DC ===
* If the current UCS@school domain is a single master environment without any UCS@school Samba 3 Slave DCs, then you can skip this step.
* The following steps update the UCS@school DCs one by one from Samba 3 to Samba 4.
* Check the general requirements of [[UCS@school_Samba_3_to_Samba_4_Migration#Preparation_of_the_UCS.40school_domain|Preparation of the UCS@school domain]].
* This way any school can be chosen for the update of the first UCS@school DC.
* Before the first UCS@school DC can be upgraded to Samba 4, all existing systems must be updated properly at least to UCS@school 3.0.
* The Upgrade can be initiated by the following commands:
<syntaxhighlight lang=bash>
ucr set samba4/ignore/mixsetup=yes \
        samba4/ntacl/backend=native \
        samba/debug/level=2 \
        ldap/master/port=7389
apt-get remove ucs-school-slave  ## workaround for APT resolver
univention-install univention-samba4 \
    univention-s4-connector libunivention-ldb-modules ucs-school-slave
univention-run-join-scripts
/usr/share/univention-s4-connector/univention-s4-position-sync
chgrp ntp /var/lib/samba/ntp_signd; service ntp restart
</syntaxhighlight>
* After the first UCS@school DC Slave has been upgraded to a Samba 4 DC, it is advisable to to extensive tests, e.g. login on the windows clients with some school accounts etc.
* If satisfied with the functionality of the first school, migration of the other schools may continue in a stepwise fashion.

==== Proxy kerberos authentication (optional)====

In a samba4 environment it is possible to activate the kerberos authentication for the proxy server (squid) on the UCS@school Slave. The following steps are necessary to activate the kerberos authentication:
<syntaxhighlight lang=bash>
univention-install univention-squid-kerberos
univention-run-join-scripts
univention-config-registry squid/krb5auth=yes
/etc/init.d/squid3 restart
</syntaxhighlight>

=== Migration of the UCS member servers ===
On UCS member servers the mode of domain membership needs to be reconfigured from NT4-domain membership to AD-domain membership. This can be achieved simply by joining the systems again, i.e. by running
<syntaxhighlight lang=bash>
univention-join
</syntaxhighlight>
and rebooting the machine after the join process completed successfully.

=== Post-Migration Tasks ===
* Netlogon scripts are not migrated automatically. They should be checked and can copied to the new location. In univention-samba3 they are stored below ''/var/lib/samba/netlogon'', univention-samba4 expects them below ''/var/lib/samba/sysvol/$domainname/scripts''. Logon scripts can also be configured via GPO.
* The Samba 4 domain password policies can be looked up running
<syntaxhighlight lang=bash>
samba-tool domain passwordsettings show
</syntaxhighlight>
* The Samba 4 domain password policies can be adjusted manually to match the values in the UCS directory. As an example, the password expiry can be disabled with the special value 0:
<syntaxhighlight lang=bash>
samba-tool domain passwordsettings set --max-pwd-age=0
</syntaxhighlight>

== Migration of the UCS@school DCs in the central school department ==

=== Migration of the UCS@school Samba 3 DCs in the central school department ===
* If no UCS@school server in the central school department runs Samba, you may skip these steps.

* Beware that all Samba 3 domain controllers have to be updated to Samba 4 once any of the DCs in the central school department has been migrated to Samba 4. Unexpected results may occur while any Samba 3 domain controllers are still active.
* Before the first UCS@school DC can be upgraded to Samba 4, all existing systems must be updated properly at least to UCS@school 3.0.
* The recommended order for updating would be DC master, DC backup, DC slave and finally Memberservers.
* On the first UCS@school Samba 4 DC the Administrator migrates in the central school department, the actual ''S4 Connector'' service will be started. Additionally two of the Active Directory [http://en.wikipedia.org/wiki/Flexible_single_master_operation Flexible Single Master Operations (FSMO)] roles will be assigned to this system. In case there are school DCs that have been migrated to Samba 4 at any school in the domain at this point, it is necessary to set the following variable in the Univention Config Registry on the first UCS@school Samba 4 DC  in the central school department. In most cases the Administrator will chose the DC Master for this unique role.
<syntaxhighlight lang=bash>
ucr set samba4/provision/primary=yes \
        connector/s4/allow/secondary=yes
</syntaxhighlight>
:'''Warning''': Be careful to set the ''samba4/provision/primary'' variable only on one single system and only in the central school depeartment. This step is not necessary in a UCS@school Single Master environment.
* On the UCS DC Master and on UCS DC Backup servers the upgrade can be initiated by the following commands:
<syntaxhighlight lang=bash>
ucr set samba4/ignore/mixsetup=yes \
        samba4/ntacl/backend=native \
        samba/debug/level=2
univention-install univention-s4-connector
univention-run-join-scripts
chgrp ntp /var/lib/samba/ntp_signd; service ntp restart
</syntaxhighlight>
* On UCS DC Slave systems the upgrade should be initiated by the following commands instead:
<syntaxhighlight lang=bash>
ucr set samba4/ignore/mixsetup=yes \
        samba4/ntacl/backend=native \
        samba/debug/level=2
univention-install univention-samba4
univention-run-join-scripts
chgrp ntp /var/lib/samba/ntp_signd; service ntp restart
</syntaxhighlight>
: This way the package univention-s4-connector is not installed on UCS@school DC Slaves in the central school department.
* The Samba 3 to Samba 4 in-place migration script migrates users, groups and computers to the default locations in the Samba 4 directory. Since UCS@school make use of  additional OU-containers in the UCS LDAP directory, it is necessary to run the following script as the next step, to synchronize the object positions in the Samba 4 directory to match the structure in the UCS LDAP directory. It is recommended to run first the script with the option ''--dry-run'' to see what steps would be taken:
<syntaxhighlight lang=bash>
/usr/share/univention-s4-connector/univention-s4-position-sync --dry-run
</syntaxhighlight>
:If this looks reasonable, the command shoud be run again without this option:
<syntaxhighlight lang=bash>
/usr/share/univention-s4-connector/univention-s4-position-sync
</syntaxhighlight>
* After all UCS Samba 3 DCs have been upgraded to Samba 4 DCs make sure the procedure worked as expected, e.g. by verifying that existing UCS users are able to log on to the Microsoft Windows clients.

=== Migration of the UCS member servers ===
On UCS member servers the mode of domain membership needs to be reconfigured from NT4-domain membership to AD-domain membership. This can be achieved simply by joining the systems again, i.e. by running
<syntaxhighlight lang=bash>
univention-join
</syntaxhighlight>
and rebooting the machine after the join process completed successfully.

=== Post-Migration Tasks ===
* Netlogon scripts are not migrated automatically. They should be checked and can copied to the new location. In univention-samba3 they are stored below ''/var/lib/samba/netlogon'', univention-samba4 expects them below ''/var/lib/samba/sysvol/$domainname/scripts''. Logon scripts can also be configured via GPO.
* The Samba 4 domain password policies can be looked up running
<syntaxhighlight lang=bash>
samba-tool domain passwordsettings show
</syntaxhighlight>
* The Samba 4 domain password policies can be adjusted manually to match the values in the UCS directory. As an example, the password expiry can be disabled with the special value 0:
<syntaxhighlight lang=bash>
samba-tool domain passwordsettings set --max-pwd-age=0
</syntaxhighlight>

[[Category:UCS@school]]
[[Category:Samba 4]]
[[Category:EN]]