Using the SUSE Distribution Migration System #

Systems that are to be upgraded need to be registered. "Pay as you go"-instances in the Public Cloud are automatically registered to the SUSE operated update infrastructure. All other systems must be connected to the SUSE Customer Center (SCC) or a Repository Management tool (RMT) server. For systems managed via SUSE Manager, use the upgrade path provided by SUSE Manager. The server that provides the repositories must have the appropriate repositories synched and they must be up to date. This requirement is automatically met by the SUSE update infrastructure in the Public Cloud and by SCC.

During the upgrade, it is only possible to log in via SSH key-based login. If your system is not configured for it, it is recommended that at least one of the users on the system has a ~/.ssh/authorized_keys file with a private key accessible by the person executing the system upgrade.

Root "/" and all core OS functional folders such as /var, /etc, /usr must be on a single partition. Multiple partition support, such as LVM, is limited to configurations where the separated partitions do not contain OS critical data or processes. For example, DMS will function if /home is its own partition, but not if /var is on a separate partition from root.

Upgrade is supported from SLES12 SP5 to SLES 15 SP3. It is possible to configure other versions of SLES as the migration target, but doing so is not a tested or supported use case.

tux > sudo zypper in SLES15-Migration

The run_migration uses kexec to boot into the kernel delivered with the upgrade image delivered by the SLES15-Migration package. Once this system is live after the kexec the distribution migration process is automatically started. However, kexec is not supported and does not function in certain conditions. The run_migration utility does not work in Xen based environments.

If kexec causes a kernel panic this can cause the system to hang and the distribution migration to fail. In that case refer to this TID: https://www.suse.com/support/kb/doc/?id=000019733 And set the "soft_reboot" customization option:

echo "soft_reboot: false" >> /etc/sle-migration-service.yml

tux > sudo zypper in SLES15-Migration suse-migration-sle15-activation

Starting the migration via reboot after installing the suse-migration-sle15-activation package covers the Xen use case but does not work in cases where there is no direct access to the root file system from the bootloader or on architectures other than x86_64. During installation of the suse-migration-sle15-activation package the bootloader configuration is modified such that on the next boot the system will boot into the upgrade image. This in turns starts the automated distribution migration process.

If the upgrade process is used on systems that are not registered or for which the repository server has no upgrade path, it’s required to switch off the use of the migration workflow.

use_zypper_migration: true|false

Note

The use of the migration workflow is the default behavior. If the migration workflow is not used, the setup of the repositories must be performed manually. Once done, the upgrade process uses zypper dup and expects all required repositories to be setup correctly.

By default the system will be migrated to SLES15 SP3. This default target can be changed via the migration_product setting. The product must be specified with the triplet name/version/arch found in '/etc/products.d/baseproduct' of the target product, for example:

migration_product: SLES/15.3/x86_64

Warning

Changing the default product leads to unsupported territory and is not tested nor covered by the SUSE support offering ! The specified product name must be supported by the repository server used for the migration. If the given product does not exist or the repository server cannot calculate an upgrade path, an error message from the repository server will be logged in the migration log file. Also see: Lifecycle and support

Preserve custom data file(s) e.g. udev rules from the system to be migrated into the upgrade live system and make sure they will become effective.

Under preserve section, there are two subsections: rules and static. The difference between 'rules' and 'static' sections is that files preserved as udev rules will also make the DMS to reload udev and its rules to make the new rule set effective, while the files in the static section are copied with no further action.

preserve:
  rules:
    - /etc/udev/rules.d/a.rules
    - /etc/udev/rules.d/b.rules
  static:
    - /etc/sysconfig/proxy
    - /path/to/be/preserved/file

Note

udev rules that require custom drivers will not have the desired effect as the migration system will not include these drivers and therefore execution of those rules will fail. Rules with such properties should not be listed.

If enabled, prevents the upgrade system from rewinding the setup steps and rebooting due to a failed upgrade, allowing the issue to be debugged.

debug: true|false

By default, the migration system uses kexec to boot back into the host system once migration is complete. If this is in any way problematic, a regular reboot can be requested by setting soft_reboot: false.

soft_reboot: true|false

If enabled, it will run the zypper migration plugin with increased verbosity.

verbose_migration: true|false

If enabled (default), the run_pre_checks systemd process will use the --fix option to automatically remediate applicable issues before the migration is started.

pre_checks_fix: true|false

The live system may not contain all necessary tools to create an initrd that meets the need of the system being upgraded. Building a host independent initrd will create an initrd in a way that contains the tools and modules available on the system being upgraded. If this is needed, a host independent initrd can be created by setting build_host_independent_initrd: True.

build_host_independent_initrd: true|false

After the install of the SLES15-Migration package, start the migration process by calling the following command:

tux > sudo run_migration