Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Linux Enterprise Desktop Documentation / Upgrade Guide / Upgrading online
Applies to SUSE Linux Enterprise Desktop 15 SP5

5 Upgrading online

SUSE offers an intuitive graphical and a simple command-line tool to upgrade a running system to a new service pack. Both provide support for rollback of service packs and more. This chapter provides step-by-step instructions on how to perform a service pack upgrade using these tools.

5.1 Conceptual overview

SUSE releases new service packs for the SUSE Linux Enterprise family at regular intervals. To make it easy for customers to migrate to a new service pack and minimize downtime, SUSE supports migrating online while the system is running.

Starting with SLE 12, YaST Wagon has been replaced by YaST migration (GUI) and Zypper migration (command line). This has the following advantages:

  • The system is always in a defined state until the first RPM is updated.

  • Canceling is possible until the first RPM is updated.

  • Simple recovery if there is an error.

  • It is possible to do a rollback via system tools—no backup or restore needed.

  • Use of all active repositories.

  • The ability to skip a service pack

Warning
Warning: Online migration not supported for major releases

The online migration is only supported for migrating between service packs. Online migration is not supported for upgrading to new major releases. For details, see Chapter 2, Upgrade paths and methods.

Use the offline migration to upgrade to a new major release. For details, see Chapter 4, Upgrading offline.

Important
Important: Upgrading SUSE Manager clients

If the system to upgrade is a SUSE Manager client, it cannot be upgraded by YaST online migration or zypper migration. Use the Client Migration procedure instead. It is described in the SUSE Manager Upgrade Guide.

5.2 Service pack migration workflow

A service pack migration can be executed by either YaST, zypper, or AutoYaST.

Before you can start a service pack migration, your system must be registered at the SUSE Customer Center or a local RMT server. SUSE Manager can also be used.

Regardless of the method, a service pack migration consists of the following steps:

  1. Find possible migration targets on your registered systems.

  2. Select one migration target.

  3. Request and enable new repositories.

  4. Run the migration.

The list of migration targets depends on the products you have installed and registered. If you have an extension installed for which the new SP is not yet available, it could be that no migration target is offered to you.

The list of migration targets available for your host will always be retrieved from the SUSE Customer Center and depend on products or extensions installed.

5.3 Canceling service pack migration

A service pack migration can only be canceled at specific stages during the migration process:

  1. Until the package upgrade starts, there are only minimal changes on the system, such as changes to services and repositories. Restore /etc/zypp/repos.d/* to revert to the previous state.

  2. After the package upgrade starts, you can revert to the previous state by using a Snapper snapshot (see Chapter 10, System recovery and snapshot management with Snapper).

  3. After the migration target was selected, SUSE Customer Center changes the repository data. To revert this state manually, use SUSEConnect --rollback.

5.4 Upgrading with the online migration tool (YaST)

To perform a service pack migration with YaST, use the Online Migration tool. By default, YaST does not install any packages from a third-party repository. If a package was installed from a third-party repository, YaST prevents packages from being replaced with the same package coming from SUSE.

Note
Note: Reduce installation size

When performing the Service Pack migration, YaST will install all recommended packages. Especially in the case of custom minimal installations, this may increase the installation size of the system significantly.

To change this default behavior and allow only required packages, adjust the solver.onlyRequires option in /etc/zypp/zypp.conf.

solver.onlyRequires = true

Additionally, edit the file /etc/zypp/zypper.conf and change the installRecommends option.

installRecommends=false

This changes the behavior of all package operations, such as the installation of patches or new packages. To change the behavior of Zypper for a single invocation, use the parameter --no-recommends.

To start the service pack migration, do the following:

  1. Deactivate all unused extensions on your registration server to avoid future dependency conflicts. If you forget an extension, YaST will later detect unused extension repositories and deactivate them.

  2. If you are logged in to a GNOME session running on the machine you are going to update, switch to a text console. Running the update from within a GNOME session is not recommended. Note that this does not apply when being logged in from a remote machine (unless you are running a VNC session with GNOME).

  3. Run YaST online update to get the latest package updates for your system.

  4. Install the package yast2-migration and its dependencies (in YaST under Software › Software Management).

  5. Restart YaST, otherwise the newly installed module will not be shown in the control center.

  6. In YaST, choose Online Migration (depending on the version of SUSE Linux Enterprise Desktop that you are upgrading from, this module is categorized under either System or Software). YaST will show possible migration targets and a summary. If more than one migration target is available for your system, select one from the list.

  7. Select one migration target from the list and proceed with Next.

  8. If the migration tool offers update repositories, it is recommended to proceed with Yes.

  9. If the online migration tool finds obsolete repositories from DVD or a local server, it is highly recommended to disable them. Obsolete repositories are for a previous service pack. Old repositories from SUSE Customer Center or RMT are removed automatically.

    If the registration server does not offer migrations for a module or extension, its repository configuration will remain unchanged. This usually happens with 3rd party repositories such as the NVIDIA Compute Module that are not specific to a product version or service pack. If necessary, you can manually check the repository configuration after the migration.

  10. Check the summary and proceed with the migration by clicking Next. Confirm with Start Update.

  11. After the successful migration restart your system.

5.5 Upgrading with Zypper

To perform a service pack migration with Zypper, use the command line tool zypper migration from the package zypper-migration-plugin.

Note
Note: Reduce installation size

When performing the Service Pack migration, YaST will install all recommended packages. Especially in the case of custom minimal installations, this may increase the installation size of the system significantly.

To change this default behavior and allow only required packages, adjust the solver.onlyRequires option in /etc/zypp/zypp.conf.

solver.onlyRequires = true

Additionally, edit the file /etc/zypp/zypper.conf and change the installRecommends option.

installRecommends=false

This changes the behavior of all package operations, such as the installation of patches or new packages. To change the behavior of Zypper for a single invocation, use the parameter --no-recommends.

To start the service pack migration, do the following:

  1. If you are logged in to a GNOME session running on the machine you are going to update, switch to a text console. Running the update from within a GNOME session is not recommended. Note that this does not apply when being logged in from a remote machine (unless you are running a VNC session with GNOME).

  2. Register your SUSE Linux Enterprise machine if you have not done so:

    > sudo SUSEConnect --regcode YOUR_REGISTRATION_CODE
  3. Start the migration:

    > sudo zypper migration

    Some notes about the migration process:

    • If more than one migration target is available for your system, Zypper allows you to select one SP from the list. This is the same as skipping one or more SPs. Keep in mind, online migration for base products (SLES, SLED) remains available only between the SPs of a major version.

    • By default, Zypper uses the option --no-allow-vendor-change which is passed to zypper dup. If a package was installed from a third-party repository, this option prevents packages from being replaced with the same package coming from SUSE.

    • If Zypper finds obsolete repositories coming from DVD or a local server, it is highly recommended to disable them. Old SUSE Customer Center or RMT repositories are removed automatically.

  4. Review all the changes, especially the packages that are going to be removed. Proceed by typing y (the exact number of packages to upgrade can vary on your system):

    266 packages to upgrade, 54 to downgrade, 17 new, 8 to reinstall, 5 to remove, 1 to change arch.
    Overall download size: 285.1 MiB. Already cached: 0 B  After the operation, additional 139.8 MiB will be used.
    Continue? [y/n/? shows all options] (y):

    Use the ShiftPage ↑ or ShiftPage ↓ keys to scroll in your shell.

  5. After successful migration restart your system.

5.6 Upgrading with plain Zypper

If your system is not registered because you do not have access to the Internet or a registration server, migrating to a new service pack is not possible with YaST Migration or zypper migration. In this case you can still migrate to a new service pack with plain Zypper and some manual interactions.

Important
Important: For unregistered systems only

This migration path to a new service pack is only supported for unregistered systems that do not have access to the Internet or a registration server. This may, for example, be the case for machines in a specially protected network. If you have a registered system, use YaST or Zypper migration.

Important
Important: Installation sources

This migration path requires that the system you are going to migrate has access to the installation sources. For example, this can be done by setting up an RMT server or an SLP server.

It is also required that the system has access to an up-to-date update repository for the installed product version.

  1. If you are logged in to a graphical session running on the machine you are going to migrate, log out of that session and switch to a text console. Running the update from within a graphical session is not recommended. Note that this does not apply when being logged in from a remote machine (unless you are running a VNC session with X).

  2. Update the package management tools with the old SUSE Linux Enterprise repositories:

    > sudo zypper patch --updatestack-only
  3. Get a list of packages that currently do not have a repository assigned to them (orphaned packages). These packages will not be migrated and there is no guarantee that they will work after the migration (because other packages they rely on may have changed in such a way that they are no longer compatible). To get the list, run:

    > sudo zypper packages --orphaned

    Carefully review the list and remove all orphaned packages that are no longer needed. Make a note of all remaining orphaned packages, you will need it later for comparison.

  4. Get a list of all repositories that the system is currently subscribed to by running:

    > sudo zypper repos -u

    Update each repository URL so that its product version number is 15-SP5. For example, if the URL of a repository is

    http://rmt.example.com/repo/SUSE/Products/SLE-15-SP2-Product-SLES/x86_64/product/

    change it to

    http://rmt.example.com/repo/SUSE/Products/SLE-15-SP3-Product-SLES/x86_64/product/

    This needs to be done with all repositories that are enabled. You may want to consider also doing this for repositories that are currently disabled, to avoid having wrong installation sources in the system when activating them at a later point in time.

    To change the repository URLs you have the following options:

    1. Using YaST › Software › Software Repositories. Select a repository and click Edit to make the required change. Repeat this for all repositories.

    2. Using Zypper. Remove the old repository by running

      > sudo zypper removerepo OLD_REPO_ID

      Then add the corresponding new repository by running

       > sudo zypper addrepo -f URL NAME-15-SP5
    3. By editing repository configuration files in /etc/zypp/repos.d. Each repository is represented by one configuration file. Changing the value for the baseurl parameter is required in each file.

  5. Review your changes by running zypper repos -u and update the repositories by running:

    > sudo zypper refresh -f -s

    In case updating a repository fails, double-check whether you entered the wrong URL. If the problem cannot be fixed, it is recommended to disable the failing repository.

    If all repositories are correctly configured, run

    > sudo zypper refresh -f -s

    again, to make sure all repositories are up-to-date.

  6. Before starting the migration it is recommended do a test run first:

    > sudo zypper dup -D --no-allow-vendor-change --no-recommends

    The parameter -D will perform a dry run that simulates the migration without actually changing the system. If problems occur, fix them before proceeding. In case the test run succeeds, perform the real migration by running:

    > sudo zypper dup --no-allow-vendor-change --no-recommends

    -no-allow-vendor-change ensures that third-party RPMs will not overwrite RPMs from the base system. The option --no-recommends ensures that packages deselected during initial installation will not be added again.

  7. When the migration has finished and the system has booted into the new service pack version, run the check for orphaned packages again:

    > sudo zypper packages --orphaned

    Compare the new list with the one you generated before starting the migration. If new packages appear in the list, it may be because they were moved to a different module in the new service pack. If you did not have that module in the previous installation, the package did not get updated.

    You can check to which module a package belongs at https://scc.suse.com/packages. Add the missing modules using zypper addrepo or the YaST Software Repositories module, and update the orphaned packages afterwards by running:

    > sudo zypper install --no-recommends LIST OF PACKAGES
  8. You have successfully migrated to a new service pack!

5.7 Rolling back a service pack

If a service pack does not work for you, SUSE Linux Enterprise supports reverting the system to the state before the service pack migration was started. Prerequisite is a Btrfs root partition with snapshots enabled (this has been the default since SLES 12). See Chapter 10, System recovery and snapshot management with Snapper for details.

  1. Get a list of all Snapper snapshots:

    > sudo snapper list

    Review the output to locate the snapshot that was created immediately before the service pack migration was started. The column Description contains a corresponding statement and the snapshot is marked as important in the column Userdata. Memorize the snapshot number from the column # and its date from the column Date.

  2. Reboot the system. From the boot menu, select Start boot loader from a read-only snapshot and then choose the snapshot with the date and number you memorized in the previous step. A second boot menu (the one from the snapshot) is loaded. Select the entry starting with SLES 15 SP5 and boot it.

  3. The system boots into the previous state with the system partition mounted read-only. Log in as root and check whether you have chosen the correct snapshot. Also make sure everything works as expected. Note that since the root file system is mounted read-only, restrictions in functionality may apply.

    In case of problems or if you have booted the wrong snapshot, reboot and choose a different snapshot to boot from—up to this point no permanent changes have been made. If the snapshot is correct and works as expected, make the change permanent by running the following command:

    > sudo snapper rollback

    Reboot the machine. On the boot screen, choose the default boot entry to reboot into the reinstated system.

  4. Check if the repository configuration has been properly reset. Furthermore, check if all products are properly registered. If either one is not the case, updating the system at a later point in time may no longer work, or the system may be updated using the wrong package repositories.

    Make sure the system can access the Internet before starting this procedure.

    1. Refresh services and repositories by running

      > sudo zypper ref -fs
    2. Get a list of active repositories by running

      > sudo zypper lr

      Carefully check the output of this command. No services and repositories that were added for the update should be listed. For example, if you are rolling back from SLES 15 SP5 to SLES15 GA, the list must contain the SLES15-GA repositories, and not the SLES15-SP5 repositories.

      If wrong repositories are listed, delete them and, if necessary, replace them with the versions matching your product or service pack version. For a list of repositories for the supported migration paths refer to Section 1.3, “Module dependencies and lifecycles”. (Note that manual intervention should not be necessary, as the repositories should be updated automatically, but it is a best practice to verify and make any necessary corrections.)

    3. Last, check the registration status for all products installed by running

      > sudo SUSEConnect --status

      All products should be reported as being Registered. If this is not the case, repair the registration by running

      > sudo SUSEConnect --rollback

Now you have successfully reverted the system to the state that was captured immediately before the service pack migration was started.

5.8 Upgrading with SUSE Manager

SUSE Manager is a server solution for providing updates, patches, and security fixes for SUSE Linux Enterprise clients. It comes with a set of tools and a Web-based user interface for management tasks. See https://www.suse.com/products/suse-manager/ for more information about SUSE Manager.

SP Migration allows migrating from one Service Pack (SP) to another within one major version (for example, from SLES 15 GA to SLES 15 SP5).

If your machine is managed by SUSE Manager, update it as described in the SUSE Manager documentation. The Client Migration procedure is described in the SUSE Manager Upgrade Guide, available at https://documentation.suse.com/suma/.