Jump to content

Using the SUSE Distribution Migration System

Authors: Marcus Schäfer and Jesús Velázquez
Publication Date: 2021-07-23

1 Concept

The Distribution Migration System provides an upgrade path for an installed SUSE Linux Enterprise system from one major version to another, for example, from SUSE Linux Enterprise Server 12 SP4 to SUSE Linux Enterprise Server 15. For a service pack upgrade from one Service Pack (SP) to another within a given major version release series the existing Zypper migration workflow provides the supported upgrade path. The distribution migration system provides the ability to upgrade across major distributions without the need to use the next major version installation media to perform the system upgrade.

The upgrade is done via the network using the Zypper migration workflow which sends a request to the repository server, asking for an upgrade path. SUSE supported repository servers are the SUSE Customer Center (SCC), the Repository Management Tool (RMT), and the Subscription Management Tool (SMT). The request response contains the list of repositories required to upgrade the system. This requires the system to be upgraded to be registered. The migration implementation also supports an upgrade mode that works with systems not registered to a repository service. For details, see Section 4, “Optional Customization of the Upgrade Process”.

The upgrade to a new major version requires the system to be migrated to be offline during the upgrade to avoid system inconsistencies that may leave the system in a state that does not allow recovery. This behavior is implemented using a Live Migration Image.

The distribution migration system provides the live image and a startup utility named: run_migration which reboots the running system into the upgrade live image. Once booted into the upgrade live image the following chain of services will be executed:

  1. Detect the system to be upgraded

  2. Mount the necessary file systems

  3. Setup the network to match the network configuration of the system to be upgraded

  4. Prepare SSH access to the upgrade live image

  5. Prepare the package manager for the upgrade task

  6. Upgrade the system using zypper

  7. Update the boot loader configuration

  8. Unmount all mounted file systems

  9. Reboot

In case an error occurs prior to the start of the upgrade the system will be reverted to its original state.

2 Upgrade Prerequisites

Requirement for using the Zypper migration workflow

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), a Subscription Management Tool (SMT), or a Repository Management tool (RMT) server. For systems managed via SUSE Manager, use the upgrade path provided by SUSE Manager.

Recommendation for SSH access during upgrade

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.

3 Installation

The distribution migration system is available from the Public Cloud module. Therefore this module has to be enabled on the system prior to upgrade. For running on-demand instances this module is already enabled.


For data center customers it is recommended to continue to use the documented offline distribution upgrade using the next distribution version installation media.

To install the distribution migration system run:

tux > sudo zypper in SLES15-Migration

The distribution migration process can be invoked using different methods. One method of activating the migration is the run_migration included with the SLES15-Migration package. The second method to invoking the migration process is via reboot after installing the suse-migration-sle15-activation package.

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

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.

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.

4 Optional Customization of the Upgrade Process

The upgrade live image is pre-configured to run without any further setup. The migration system reads a custom configuration file from the system to be upgraded. The content of this file modifies the behavior of the upgrade process. Prior to the start of the upgrade process, create the following file if a change of the default behavior is needed:

tux > ssh INSTANCE_USER@IP_OF_INSTANCE 'touch /etc/sle-migration-service.yml'

The custom config file supports the following settings:

Control Zypper Installation Mode

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

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.

Preserve System Data

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.

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

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.

Enable Debug Mode

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
Configure Reboot Method

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

5 Run the Migration

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

tux > sudo run_migration

If the suse-migration-sle15-activation package was installed, start the migration by a reboot of the system as follows:

tux > sudo reboot

After the upgrade has started, the only way to access the system during the upgrade process is via ssh with a user called migration:

tux > sudo ssh migration@IP_OF_INSTANCE

There is no need to provide any other information or key. The known SSH keys on the system to be upgraded have been imported into the upgrade system. Password-based login is not possible.

6 After the Migration

Whether the upgrade succeeded or not, a log file is available in /var/log/distro_migration.log and it will contain information about the upgrade process. If the upgrade failed, the file /etc/issue will contain a pointer to the respective log file.

7 Caveats and Unsupported Conditions

  • Configuration files that have been modified in the original system will not be overwritten by the upgrade process. The new version of the respective configuration file will be copied into the same directory with the file name extension .rpmnew. It is recommended to compare the existing and the new configuration files and make manual adjustments when needed.

  • Repositories not registered via SUSEConnect and added to the system manually will remain untouched.

  • Upgrade is only possible for systems that use unencrypted root file systems, at the OS level. Encrypting the root device using a cloud framework encryption mechanism happens at a different level.

  • Upgrade has been tested for SLES 12 SP4 to SLES 15

  • The system is primarily intended for Public Cloud instance upgrade use. The system also works for simple setups in a data center setting on physical installations. However, for any more complex configurations the off line upgrade path via install ISO file should be used as documented in the SUSE Linux Enterprise Server documentation.

  • In systems that contain multiple root file systems on different mount points only the root file system mounted on / (primary system) will be migrated.

7.1 Public and Private Cloud Specific

  • Migration initiation for a cloud instance is only supported via a reboot. The required GRUB changes to make this process are automated and provided with the suse-migration-sle15-activation package. We recommend to use the provided automation.

  • Public Cloud instances from SUSE images have a custom /etc/motd file that makes a reference to the distribution version. This needs to be updated manually after the upgrade.

  • The instance metadata will not change. As far as the cloud framework is concerned, you will still be running an instance of the SLES version you started with. This cannot be changed.

  • The only supported migration path in the Public Cloud is from the final 2 service packs of a distribution to the first service pack of the next distribution. For example from SLES 12 SP4 or SLES 12 SP5 to SLES 15 SP1. The packages delivered by SUSE in the Public Cloud Module implement this behavior by default.

Print this page