3 Preparing the upgrade #
Before starting the upgrade procedure, make sure your system is properly prepared. Among other things, preparation involves backing up data and checking the release notes. The following chapter guides you through these steps.
3.1 Make sure the system is up-to-date #
Upgrading the system is only supported from the most recent patch level.
Make sure the latest system updates are installed by
either running zypper
patch
or by starting the YaST module
.
Mid 2023, the SUSE Linux Enterprise 15 product family switched over from a RSA 2048-bit signing key to a new RSA 4096-bit key. This change covers RPM packages, package repositories and ISO signatures. Old repositories that are not updated anymore and RPMs released up to the switch-over date, will still stay signed with the old 2048 bit key.
If you update your system, the new key is automatically imported into the RPM keyring from the suse-build-key package on SLE 15 SP 4 and SP5 as well as the LTSS versions of SLE 15 SP1, SP2, and SP3.
If the key was not imported yet, you can manually import it with:
>
sudo
rpm --import /usr/lib/rpm/gnupg/keys/gpg-pubkey-3fa1d6ce-63c9481c.asc
If you are running an older version of SLE or did not import the new key, you will be asked to trust it during the upgrade. Please make sure the fingerprint matches:
pub rsa4096/0xF74F09BC3FA1D6CE 2023-01-19 [SC] [expires: 2027-01-18] Key fingerprint = 7F00 9157 B127 B994 D5CF BE76 F74F 09BC 3FA1 D6CE uid SUSE Package Signing Key <build@suse.de>
Additionally, a reserve 4096-bit RSA key for disaster recovery purposes was imported:
pub rsa4096/0xA1BFC02BD588DC46 2023-01-19 [SC] [expires: 2033-01-16] Key fingerprint = B56E 5601 41D8 F654 2DFF 3BF9 A1BF C02B D588 DC46 uid SUSE Package Signing Key (reserve key) <build@suse.de>
This key can be manually imported using:
>
sudo
rpm --import /usr/lib/rpm/gnupg/keys/gpg-pubkey-d588dc46-63c939db.asc
Both keys can also be found on the installation media and the SUSE website at https://www.suse.com/support/security/keys/.
3.2 Read the release notes #
Find a list of all changes, new features, and known issues in the
release notes.
You can also find the release notes on the installation media in the
docu
directory.
The release notes usually only contain the changes between two subsequent releases. If you are skipping one or more Service Packs, check the release notes of the skipped Service Packs as well.
Consult the release notes to check whether the following applies:
Your hardware needs special considerations
Any currently used software packages have changed significantly
Your installation requires special precautions
3.3 Make a backup #
Before upgrading, back up your data by copying the existing configuration
files to a separate medium (such as tape device, removable hard disk, etc.).
This primarily applies to files stored in /etc
and some
directories and files in /var
and
/opt
. You may also want to write the user data in
/home
(the HOME
directories) to a backup
medium.
Back up all data as root
. Only root
has sufficient permissions
for all local files.
If you have selected /etc/sysconfig
directory. However, this is not
a complete backup, as all the other important directories mentioned above
are missing. Find the backup in the /var/adm/backup
directory.
3.4 Check the available disk space #
Software tends to grow from version to version. Therefore, take a look at the available partition space before updating. If you suspect you are running short of disk space, back up your data before increasing the available space by resizing partitions, for example. There is no general rule regarding how much space each partition should have. Space requirements depend on your particular partitioning profile and the software selected.
During the update procedure, YaST will check how much free disk space is available and display a warning to the user if the installation may exceed the available amount. In that case, performing the update may lead to an unusable system! Only if you know exactly what you are doing (by testing beforehand), you can skip the warning and continue the update.
3.4.1 Checking disk space on non-Btrfs file systems #
Use the df
command to list available disk space. For
example, in Example 3.1, “List with df -h
”, the root partition is
/dev/sda3
(mounted as /
).
df -h
#Filesystem Size Used Avail Use% Mounted on /dev/sda3 74G 22G 53G 29% / tmpfs 506M 0 506M 0% /dev/shm /dev/sda5 116G 5.8G 111G 5% /home /dev/sda1 44G 4G 40G 9% /data
3.4.2 Checking disk space on Btrfs root file systems #
On a Btrfs file system, the output of df
can be
misleading, because in addition to the space the raw data allocates, a
Btrfs file system also allocates and uses space for metadata.
Consequently a Btrfs file system may report being out of space even though
it seems that plenty of space is still available. In that case, all space
allocated for the metadata is used up. For details on how
to check for used and available space on a Btrfs file system, see
Section 1.2.2.3, “Checking for free space”. For
more information refer to man 8
btrfs-filesystem
and
https://btrfs.wiki.kernel.org/index.php/FAQ.
When using Btrfs for root file systems on your machine, make sure there is
enough free space. Check the available space on all mounted partitions. In
the worst case, an upgrade needs as much disk space as the current root
file system (without /.snapshot
) for a new snapshot.
The following recommendations have been proven:
For all file systems, including Btrfs, you need enough free disk space to download and install big RPMs. The space of old RPMs is only freed after new RPMs are installed.
For Btrfs with snapshots, you need as a minimum as much free space as your current installation takes. We recommend having twice as much free space as the current installation.
If you do not have enough free space, you can try to delete old snapshots with
snapper
:#
snapper
list#
snapper
delete NUMBERHowever, this may not help in all cases. Before migration, most snapshots occupy only little space.
3.5 Listing installed packages and repositories #
You can save a list of installed packages; for example, when doing a fresh install of a new major SLE release or reverting to the old version.
Be aware that not all installed packages or used repositories are available in newer releases of SUSE Linux Enterprise. Some may have been renamed and others replaced. It is also possible that some packages are still available for legacy purposes while another package is used by default. Therefore, some manual editing of the files might be necessary. This can be done with any text editor.
Create a file named
repositories.bak.repo
containing a list of all used repositories:#
zypper
lr -e repositories.bakAlso create a file named
installed-software.bak
containing a list of all installed packages:#
rpm
-qa --queryformat '%{NAME}\n' > installed-software.bakBack up both files. The repositories and installed packages can be restored with the following commands:
#
zypper
ar repositories.bak.repo#
zypper
install $(cat installed-software.bak)Note: Number of packages increases with an update to a new major releaseA system upgraded to a new major version (SLE X+1) may contain more packages than the initial system (SLE X). It will also contain more packages than a fresh installation of SLE X+1 with the same pattern selection. Reasons for this are:
Packages were split to allow a more fine-grained package selection. For example, 37 texlive packages on SLE 11 were split into over 3000 packages on SLE 15.
When a package has been split, all new packages are installed in the upgrade case to retain the same functionality as the previous version. However, the new default for a fresh installation of SLE X+1 may be to not install all packages.
Legacy packages from SLE X may be kept for compatibility reasons.
Package dependencies and the scope of patterns may have changed.
3.6 Disable the LTSS extension #
If you upgrade a SUSE Linux Enterprise Server system with Long Term Service Pack Support
(LTSS) to a version that is still under general support, the upgrade will
fail with the error No migration available
. This happens
because zypper migration
tries to migrate
all repositories, but there is no LTSS repository for
the new version yet.
To fix this issue, disable the LTSS extension before the upgrade.
Check if the LTSS extension is enabled:
>
sudo
SUSEConnect --list-extensions | grep LTSS SUSE Linux Enterprise Server LTSS 12 SP4 x86_64 (Installed) Deactivate with: SUSEConnect -d -p SLES-LTSS/12.4/x86_64Disable the LTSS extension with the command from the
SUSEConnect
output above:>
sudo
SUSEConnect -d -p SLES-LTSS/12.4/x86_64 Deregistered SUSE Linux Enterprise Server LTSS 12 SP4 x86_64 To server: https://scc.suse.com/Verify the LTSS repository is no longer present with
zypper lr
.
3.7 Migrate your PostgreSQL database #
SUSE Linux Enterprise Server 15 SP5 ships with the PostgreSQL database versions
14 and 15.
While version 15 is the default, version 14 is still provided through the
Legacy
module for upgrades from earlier versions of
SUSE Linux Enterprise Server.
Because of the required migration work of the database, there is no automatic upgrade process. As such, the switch from one version to another needs to be performed manually.
The migration process is conducted by the pg_upgrade
command, which is an alternative method of the classic dump and reload. In
comparison with the “dump and reload” method,
pg_upgrade
makes the migration less time-consuming.
The program files for each PostgreSQL version are stored in different,
version-dependent directories. For example, in
/usr/lib/postgresql96/
for version 9.6, in
/usr/lib/postgresql10/
for version 10, and in
/usr/lib/postgres13/
for version 13. Note that the
versioning policy of PostgreSQL has changed between the major versions 9.6
and 10. For details, see
https://www.postgresql.org/support/versioning/.
When upgrading from SLE 11, postgresql94
will
be uninstalled and cannot be used for the database migration to a higher
PostgreSQL version. Therefore, in this case, make sure to migrate the
PostgreSQL database before you upgrade your system.
The procedure below describes the database migration from version 12 to 13. When using a different version as start or target, replace the version numbers accordingly.
To perform the database migration, do the following:
Make sure the following preconditions are fulfilled:
If not already done, upgrade any package of the old PostgreSQL version to the latest release through a maintenance update.
Create a backup of your existing database.
Install the packages for the new PostgreSQL major version. For SLE 15 SP5, this means installing postgresql13-server and all the packages it depends on.
Install the package postgresql13-contrib, which contains the command
pg_upgrade
.Make sure you have enough free space in your PostgreSQL data area, which is
/var/lib/pgsql/data
by default. If space is tight, try to reduce size with the following SQL command on each database (can take a long time!):VACUUM FULL
Stop the PostgreSQL server with either:
#
/usr/sbin/rcpostgresql
stopor
#
systemctl stop postgresql.service(depending on the SLE version you are using as the start version for your upgrade).
Rename your old data directory:
#
mv
/var/lib/pgsql/data /var/lib/pgsql/data.oldInitialize your new database instance either manually with
initdb
or by starting and stopping PostgreSQL, which will do it automatically:#
/usr/sbin/rcpostgresql
start#
/usr/sbin/rcpostgresql
stopor
#
systemctl start postgresql.service#
systemctl stop postgresql.service(depending on the SLE version you are using as the start version for your upgrade).
If you have changed your configuration files in the old version, consider transferring these changes to the new configuration files. This may affect the files
postgresql.auto.conf
,postgresql.conf
,pg_hba.conf
andpg_ident.conf
. The old versions of these files are located in/var/lib/pgsql/data.old/
, and the new versions can be found in/var/lib/pgsql/data
.Note that copying the old configuration files is not recommended, because this may overwrite new options, new defaults and changed comments.
Start the migration process as user
postgres
:#
su - postgres postgres >pg_upgrade
\ --old-datadir "/var/lib/pgsql/data.old" \ --new-datadir "/var/lib/pgsql/data" \ --old-bindir "/usr/lib/postgresql12/bin/" \ --new-bindir "/usr/lib/postgresql13/bin/"Start your new database instance with either:
#
/usr/sbin/rcpostgresql
startor
#
systemctl start postgresql.service(depending on the SLE version you are using as the start version for your upgrade).
Check if the migration was successful. The scope of the test depends on your use case, and there is no general tool to automate this step.
Remove any old PostgreSQL packages and your old data directory:
#
zypper
search -s postgresql12| xargs zypper rm -u#
rm
-rf /var/lib/pgsql/data.old
For more information about upgrading databases or using alternative methods such as logical replication, refer to the official PostgreSQL documentation at https://www.postgresql.org/docs/13/upgrading.html.
3.8 Migrate your MySQL or MariaDB database #
As of SUSE Linux Enterprise 12, SUSE switched from MySQL to MariaDB. Before you start any upgrade, it is highly recommended to back up your database.
To perform the database migration, do the following:
Create a dump file:
#
mysqldump
-u root -p --all-databases --add-drop-database > mysql_backup.sqlBy default,
mysqldump
does not dump theINFORMATION_SCHEMA
orperformance_schema
database. For more details refer to https://mariadb.com/kb/en/mariadb-dumpmysqldump/.Store your dump file, the configuration file
/etc/my.cnf
, and the directory/etc/mysql/
for later investigation (not installation!) in a safe place.Perform the SUSE Linux Enterprise Server upgrade. After the upgrade, your former configuration file
/etc/my.cnf
will still be intact. You can find the new configuration in the file/etc/my.cnf.rpmnew
.Configure your MariaDB database to your needs. Do not use the former configuration file and directory, but use it as a reminder and adapt it.
Make sure you start the MariaDB server:
#
systemctl
start mariadbIf you want to start the MariaDB server on every boot, enable the service:
#
systemctl
enable mariadbVerify that MariaDB is running properly by connecting to the database:
#
mariadb
-u root -p
3.9 Create non-MD5 server certificates for Java applications #
As a security measure, MD5-based certificates are no longer supported in Java. If you have certificates created as MD5, re-create your certificates with the following steps:
Open a terminal and log in as
root
.Create a private key:
#
openssl
genrsa -out server.key 1024If you want a stronger key, replace
1024
with a higher number, for example,4096
.Create a certificate signing request (CSR):
#
openssl
req -new -key server.key -out server.csrSelf-sign the certificate:
#
openssl
x509 -req -days 365 -in server.csr -signkey server.key -out server.crtCreate the PEM file:
#
cat
server.key server.crt > server.pemPlace the files
server.crt
,server.csr
,server.key
, andserver.pem
in the respective directories where the keys can be found. For Tomcat, for example, this directory is/etc/tomcat/ssl/
.
3.10 Shut down virtual machine guests #
If your machine serves as a VM Host Server for KVM or Xen, make sure to properly shut down all running VM Guests prior to the update. Otherwise you may not be able to access the guests after the update.
3.11 Adjust your SMT client setup #
If the machine you want to upgrade is registered as a client against an SMT server, take care to do the following:
Check if the version of the clientSetup4SMT.sh
script on
your host is up to date. clientSetup4SMT.sh
from older
versions of SMT cannot manage SMT 12 clients. If you apply software
patches regularly on your SMT server, you can always find the latest
version of clientSetup4SMT.sh
at
<SMT_HOSTNAME>/repo/tools/clientSetup4SMT.sh
.
In case upgrading your machine to a higher version of SUSE Linux Enterprise Server fails, deregister the machine from the SMT server as described in Procedure 3.1. Afterward, restart the upgrade process.
Log in to the client machine.
The following step depends on the current operating system of the client:
For SUSE Linux Enterprise 11, execute the following commands:
>
sudo
suse_register -E>
sudo
rm -f /etc/SUSEConnect>
sudo
rm -rf /etc/zypp/credentials.d/*>
sudo
rm -rf /etc/zypp/repos.d/*>
sudo
rm -f /etc/zypp/services.d/*>
sudo
rm -f /var/cache/SuseRegister/*>
sudo
rm -f /etc/suseRegister*>
sudo
rm -f /var/cache/SuseRegister/lastzmdconfig.cache>
sudo
rm -f /etc/zmd/deviceid>
sudo
rm -f /etc/zmd/secretFor SUSE Linux Enterprise 12, execute the following commands:
>
sudo
SUSEConnect --de-register>
sudo
SUSEConnect --cleanup>
sudo
rm -f /etc/SUSEConnect>
sudo
rm -rf /etc/zypp/credentials.d/*>
sudo
rm -rf /etc/zypp/repos.d/*>
sudo
rm -f /etc/zypp/services.d/*
Log in to the SMT server.
Check if the client has successfully been deregistered by listing all client registrations:
>
sudo
smt-list-registrationsIf the client's host name is still listed in the output of this command, get the client's
Unique ID
from the first column. (The client might be listed with multiple IDs.)Delete the registration for this client:
>
sudo
smt-delete-registration -g UNIQUE_IDIf the client is listed with multiple IDs, repeat the step above for each of its unique IDs.
Check if the client has now successfully been deregistered by re-running:
>
sudo
smt-list-registrations
3.12 Changes in AutoYaST profiles from SLE 12 to 15 #
To learn how to migrate your AutoYaST profiles, see Appendix D, Differences between AutoYaST profiles in SLE 12 and 15.
3.13 Upgrading a Subscription Management Tool (SMT) server #
A server running SMT requires a special upgrade procedure. Please refer to Chapter 3, Migrate from SMT to RMT in the Repository Mirroring Tool Guide.
3.14 Temporarily disabling kernel multiversion support #
SUSE Linux Enterprise Server allows installing multiple kernel versions by enabling the
respective settings in /etc/zypp/zypp.conf
. Support for
this feature needs to be temporarily disabled to upgrade to a service pack.
When the update has successfully finished, multiversion support can be
re-enabled. To disable multiversion support, comment the respective lines in
/etc/zypp/zypp.conf
. The result should look similar to:
#multiversion = provides:multiversion(kernel) #multiversion.kernels = latest,running
To re-activate this feature after a successful update, remove the comment signs. For more information about multiversion support, refer to Section 27.1, “Enabling and configuring multiversion support”.
3.15 Adjust the resume
boot parameter #
On systems that have been installed with SUSE Linux Enterprise Server 12 or older, the default kernel command
line in /etc/default/grub
may contain a resume
parameter using a device node name such as /dev/sda1
to refer to the
hibernation ('suspend-to-disk') device. As device node names are not persistent and may
change between reboots, it is strongly recommended to fix this, otherwise the upgraded system
may hang on reboot.
Find the hibernation device:
>
sudo
grep resume /etc/default/grub
GRUB_CMDLINE_LINUX_DEFAULT="resume=/dev/sda1 splash=silent quiet showopts"The hibernation device is
/dev/sda1
. If the command returns nothing, hibernation is not configured.Get the UUID for
/dev/sda1
:>
sudo
blkid /dev/vda1
/dev/vda1: UUID="a1d1f2e0-b0ee-4be2-83d5-78a98c585827" TYPE="swap" PARTUUID="000134b5-01"The UUID for
/dev/sda1
isa1d1f2e0-b0ee-4be2-83d5-78a98c585827
.Edit
/etc/default/grub
and adjust the resume parameter. Replace/dev/sda1
withUUID=a1d1f2e0-b0ee-4be2-83d5-78a98c585827
. The result will look like this:GRUB_CMDLINE_LINUX_DEFAULT="resume=UUID=a1d1f2e0-b0ee-4be2-83d5-78a98c585827 splash=silent quiet showopts"
Update the configuration of the grub boot manger:
>
sudo
grub2-mkconfig -o /boot/grub2/grub.cfg
If the system does not use hibernation, you can simply remove the resume parameter and update the boot configuration.
3.16 Upgrading on IBM Z #
Upgrading a SUSE Linux Enterprise installation on IBM Z requires the
Upgrade=1
kernel parameter, for example via the parmfile.
See Section 5.5, “The parmfile—automating the system configuration”.
3.17 IBM POWER: Starting an X server #
On SLES 12 for IBM POWER the display manager is configured not to start a local X server by default. This setting was reversed on SLES 12 SP1—the display manager now starts an X server.
To avoid problems during upgrade, the SUSE Linux Enterprise Server setting is not changed
automatically. If you want the display manager to start an X server after
the upgrade, change the setting of
DISPLAYMANAGER_STARTS_XSERVER
in
/etc/sysconfig/displaymanager
as follows:
DISPLAYMANAGER_STARTS_XSERVER="yes"