This book guides you through upgrades and updates of SUSE Linux Enterprise Server. Different approaches are described, for example upgrading from an installation DVD, via network boot, or a running system.
- About This Guide
- 1 Upgrade Paths and Methods
- 2 Life Cycle and Support
- 3 Preparing the Upgrade
- 3.1 Make Sure the Current System Is Up-To-Date
- 3.2 Read the Release Notes
- 3.3 Make a Backup
- 3.4 Listing Installed Packages and Repositories
- 3.5 Disable the LTSS Extension
- 3.6 Upgrading from SUSE Linux Enterprise Server 11 SP4
- 3.7 Migrate Your PostgreSQL Database
- 3.8 Shut Down Virtual Machine Guests
- 3.9 Adjusting your SMT client setup
- 3.10 Disk Space
- 3.11 Changes in AutoYaST Profiles from SLE 12 to 15
- 3.12 Upgrading a Subscription Management Tool (SMT) Server
- 3.13 Temporarily Disabling Kernel Multiversion Support
- 3.14 Adjust the
resume
boot parameter - 3.15 Upgrading on IBM Z
- 3.16 IBM POWER: Starting an X Server
- 4 Upgrading Offline
- 5 Upgrading Online
- 5.1 Conceptual Overview
- 5.2 Service Pack Migration Workflow
- 5.3 Canceling Service Pack Migration
- 5.4 Upgrading with the Online Migration Tool (YaST)
- 5.5 Upgrading with Zypper
- 5.6 Upgrading with Plain Zypper
- 5.7 Rolling Back a Service Pack
- 5.8 Upgrading with SUSE Manager
- 5.9 Upgrading from openSUSE Leap to SUSE Linux Enterprise Server
- 6 Backports of Source Code
- A GNU licenses
Copyright © 2006–2024 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.
About This Guide #
There are different ways to upgrade SUSE Linux Enterprise Server. It is impossible to cover all combinations of boot, or installation server, automated installations or deploying images. This manual should help with selecting the appropriate method of upgrading your installation.
- Book “Upgrade Guide”
This part will give you some background information on terminology, SUSE product lifecycles and Service Pack releases, and recommended upgrade policies.
1 Available documentation #
- Online documentation
Our documentation is available online at https://documentation.suse.com. Browse or download the documentation in various formats.
Note: Latest updatesThe latest updates are usually available in the English-language version of this documentation.
- SUSE Knowledgebase
If you have run into an issue, also check out the Technical Information Documents (TIDs) that are available online at https://www.suse.com/support/kb/. Search the SUSE Knowledgebase for known solutions driven by customer need.
- Release notes
For release notes, see https://www.suse.com/releasenotes/.
- In your system
For offline use, the release notes are also available under
/usr/share/doc/release-notes
on your system. The documentation for individual packages is available at/usr/share/doc/packages
.Many commands are also described in their manual pages. To view them, run
man
, followed by a specific command name. If theman
command is not installed on your system, install it withsudo zypper install man
.
2 Improving the documentation #
Your feedback and contributions to this documentation are welcome. The following channels for giving feedback are available:
- Service requests and support
For services and support options available for your product, see https://www.suse.com/support/.
To open a service request, you need a SUSE subscription registered at SUSE Customer Center. Go to https://scc.suse.com/support/requests, log in, and click .
- Bug reports
Report issues with the documentation at https://bugzilla.suse.com/.
To simplify this process, click the
icon next to a headline in the HTML version of this document. This preselects the right product and category in Bugzilla and adds a link to the current section. You can start typing your bug report right away.A Bugzilla account is required.
- Contributions
To contribute to this documentation, click the
icon next to a headline in the HTML version of this document. This will take you to the source code on GitHub, where you can open a pull request.A GitHub account is required.
Note:only available for EnglishThe
icons are only available for the English version of each document. For all other languages, use the icons instead.For more information about the documentation environment used for this documentation, see the repository's README.
You can also report errors and send feedback concerning the documentation to <doc-team@suse.com>. Include the document title, the product version, and the publication date of the document. Additionally, include the relevant section number and title (or provide the URL) and provide a concise description of the problem.
3 Documentation conventions #
The following notices and typographic conventions are used in this document:
/etc/passwd
: Directory names and file namesPLACEHOLDER: Replace PLACEHOLDER with the actual value
PATH
: An environment variablels
,--help
: Commands, options, and parametersuser
: The name of a user or grouppackage_name: The name of a software package
Alt, Alt–F1: A key to press or a key combination. Keys are shown in uppercase as on a keyboard.
AMD/Intel This paragraph is only relevant for the AMD64/Intel 64 architectures. The arrows mark the beginning and the end of the text block.
IBM Z, POWER This paragraph is only relevant for the architectures
IBM Z
andPOWER
. The arrows mark the beginning and the end of the text block.Chapter 1, “Example chapter”: A cross-reference to another chapter in this guide.
Commands that must be run with
root
privileges. You can also prefix these commands with thesudo
command to run them as a non-privileged user:#
command
>
sudo
command
Commands that can be run by non-privileged users:
>
command
Commands can be split into two or multiple lines by a backslash character (
\
) at the end of a line. The backslash informs the shell that the command invocation will continue after the line's end:>
echo
a b \ c dA code block that shows both the command (preceded by a prompt) and the respective output returned by the shell:
>
command
outputNotices
Warning: Warning noticeVital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.
Important: Important noticeImportant information you should be aware of before proceeding.
Note: Note noticeAdditional information, for example about differences in software versions.
Tip: Tip noticeHelpful information, like a guideline or a piece of practical advice.
Compact Notices
Additional information, for example about differences in software versions.
Helpful information, like a guideline or a piece of practical advice.
4 Support #
Find the support statement for SUSE Linux Enterprise Server and general information about technology previews below. For details about the product lifecycle, see https://www.suse.com/lifecycle.
If you are entitled to support, find details on how to collect information for a support ticket at https://documentation.suse.com/sles-15/html/SLES-all/cha-adm-support.html.
4.1 Support statement for SUSE Linux Enterprise Server #
To receive support, you need an appropriate subscription with SUSE. To view the specific support offers available to you, go to https://www.suse.com/support/ and select your product.
The support levels are defined as follows:
- L1
Problem determination, which means technical support designed to provide compatibility information, usage support, ongoing maintenance, information gathering and basic troubleshooting using available documentation.
- L2
Problem isolation, which means technical support designed to analyze data, reproduce customer problems, isolate a problem area and provide a resolution for problems not resolved by Level 1 or prepare for Level 3.
- L3
Problem resolution, which means technical support designed to resolve problems by engaging engineering to resolve product defects which have been identified by Level 2 Support.
For contracted customers and partners, SUSE Linux Enterprise Server is delivered with L3 support for all packages, except for the following:
Technology previews.
Sound, graphics, fonts, and artwork.
Packages that require an additional customer contract.
Some packages shipped as part of the module Workstation Extension are L2-supported only.
Packages with names ending in -devel (containing header files and similar developer resources) will only be supported together with their main packages.
SUSE will only support the usage of original packages. That is, packages that are unchanged and not recompiled.
4.2 Technology previews #
Technology previews are packages, stacks, or features delivered by SUSE to provide glimpses into upcoming innovations. Technology previews are included for your convenience to give you a chance to test new technologies within your environment. We would appreciate your feedback. If you test a technology preview, please contact your SUSE representative and let them know about your experience and use cases. Your input is helpful for future development.
Technology previews have the following limitations:
Technology previews are still in development. Therefore, they may be functionally incomplete, unstable, or otherwise not suitable for production use.
Technology previews are not supported.
Technology previews may only be available for specific hardware architectures.
Details and functionality of technology previews are subject to change. As a result, upgrading to subsequent releases of a technology preview may be impossible and require a fresh installation.
SUSE may discover that a preview does not meet customer or market needs, or does not comply with enterprise standards. Technology previews can be removed from a product at any time. SUSE does not commit to providing a supported version of such technologies in the future.
For an overview of technology previews shipped with your product, see the release notes at https://www.suse.com/releasenotes.
1 Upgrade Paths and Methods #
SUSE® Linux Enterprise (SLE) allows upgrading an existing system to a later version or service pack. No new installation is needed. Existing data, such as home and data directories and system configuration, is kept intact. You can update from a local CD or DVD drive or from a central network installation source.
This chapter explains how to manually upgrade your SUSE Linux Enterprise system, be it by DVD, network, an automated process, or SUSE Manager.
1.1 Upgrading versus Fresh Installation #
Upgrades between two major releases of SUSE Linux Enterprise Server are supported by SUSE. Whether it is better to upgrade or perform a fresh installation depends your specific scenario. While upgrades promise less work, fresh installations ensure you benefit from all new features of a release such as disk layout changes, specific filesystem features, and other improvements. To get the most out of your system, SUSE therefore recommends fresh installations in most scenarios.
In both cases—upgrade as well as a fresh installation— customers will have to check if system settings and default values still fit their requirements.
For updates from one service pack of a specific release to another one of the same codestream, SUSE recommends to do it in-place, and not to perform a fresh installation. Nevertheless there may be reasons and scenarios for a customer to perform a fresh installation in this case, too. The decision what is more suitable can only be made by the customer.
1.2 Supported Upgrade Paths to SLES 15 SP2 #
Before you perform any migration, read Chapter 3, Preparing the Upgrade.
Cross-architecture upgrades, such as upgrading from a 32-bit version of SUSE Linux Enterprise Server to the 64-bit version, or upgrading from big endian to little endian are not supported!
Specifically, SLE 11 on POWER (big endian) to SLE 15 SP2 on POWER (new: little endian!) is not supported.
Also, since SUSE Linux Enterprise 15 is 64-bit only, upgrades from any 32-bit SUSE Linux Enterprise 11 systems to SUSE Linux Enterprise 15 and later are not supported.
To make a cross-architecture upgrade, you need to perform a new installation.
The easiest upgrade path is consecutively installing all service packs. For the SUSE Linux Enterprise 15 product line (GA and the subsequent service packs) it is also supported to skip one service pack when upgrading. For example, upgrading from SLE 15 GA to 15 SP2 or from SLE 15 SP1 to 15 SP3 is supported.
The upgrade paths described here apply only to SUSE Linux Enterprise as the operating system of a machine, not to all applications it runs. If you have workloads such as PostgreSQL or MariaDB databases, intermediate OS upgrades may be required in order to upgrade your databases.
Before upgrading the operating system, consult the Release Notes for information about database versions. If a new major version is shipped, refer to Chapter 3, Preparing the Upgrade for upgrade instructions.
- Upgrading from SUSE Linux Enterprise Server 11 GA / SP1 / SP2 / SP3 / SP4
Upgrading from SLES 11 SP4 or older service packs directly is not supported. You need at least SLES 11 SP4 with LTSS before you can proceed to SLES 15 SP2.
If you cannot do a fresh installation, first upgrade your installed SLES 11 service pack to SLES 11 SP4 LTSS. This upgrade is described in the SLES 11 SP4 Deployment Guide.
- Upgrading from SUSE Linux Enterprise Server 11 SP4 with LTSS
Upgrading from SLES 11 SP4 with LTSS is only supported via an offline upgrade. Refer to Section 1.3, “Online and Offline Upgrade” for details.
- Upgrading from SUSE Linux Enterprise Server 12 GA / SP1 / SP2 / SP3 / SP4
Upgrading from SLES 12 SP4 or older service packs directly is not supported. You need at least SLES 12 SP5 before you can proceed to SLES 15 SP2.
If you cannot do a fresh installation, first upgrade your installed SLES 12 service pack to SLES 12 SP5. This upgrade is described in the SLES 12 SP5 Deployment Guide.
- Upgrading from SUSE Linux Enterprise Server12 SP4 with LTSS
Upgrading from SLES 12 SP4 with LTSS is only supported via an offline upgrade. Refer to Section 1.3, “Online and Offline Upgrade” for details.
- Upgrading from SUSE Linux Enterprise Server 12 SP5
Upgrading from SLES 12 SP5 is only supported via an offline upgrade. Refer to Section 1.3, “Online and Offline Upgrade” for details.
- Upgrading from SUSE Linux Enterprise Server 15 GA / SP1
Upgrading from SLES 15 GA or SP1 is supported both online and offline. Refer to the following for details:
- Upgrading SUSE Linux Enterprise Public Cloud Guests
For instructions on upgrading SLE guests in public clouds, see Using the SUSE Distribution Migration System.
- Upgrading from openSUSE Leap 15
Upgrading from openSUSE Leap 15 is supported. See Section 5.9, “Upgrading from openSUSE Leap to SUSE Linux Enterprise Server”. Only the server installation of Leap is supported for an upgrade.
For some products, SUSE offers Extended Service Pack Overlap Support (ESPOS) under the same conditions as LTSS. For more information about ESPOS, refer to the documentation of the respective SUSE Linux Enterprise product and the Product Lifecycle Support Policies webpage.
1.3 Online and Offline Upgrade #
SUSE supports the following upgrade and migration methods. For more information about the terminology, see Section 2.1, “Terminology”. The methods are:
- Online
Upgrades that are executed from the running operating system itself (system up and running state). Examples: online update with Zypper or YaST, connected through SUSE Customer Center or Repository Mirroring Tool (RMT), Salt Policy via SUSE Manager.
For details, see Chapter 5, Upgrading Online.
When migrating between Service Packs of the same major release, we suggest following Section 5.4, “Upgrading with the Online Migration Tool (YaST)” or Section 5.5, “Upgrading with Zypper”.
- Offline
Upgrading offline implies that the operating system to be upgraded is not running (system down state). Instead, the installer for the target operating system is booted (for example, from the installation media, via network or via local boot loader), and performs the upgrade.
For details, see Chapter 4, Upgrading Offline.
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/.
2 Life Cycle and Support #
This chapter provides background information on terminology, SUSE product lifecycles and Service Pack releases, and recommended upgrade policies.
2.1 Terminology #
This section uses several terms. To understand the information, read the definitions below:
- Backporting
Backporting is the act of adapting specific changes from a newer version of software and applying it to an older version. The most commonly used case is fixing security holes in older software components. Usually it is also part of a maintenance model to supply enhancements or (less commonly) new features.
- Delta RPM
A delta RPM consists only of the binary diff between two defined versions of a package, and therefore has the smallest download size. Before being installed, the full RPM package is rebuilt on the local machine.
- Downstream
A metaphor of how software is developed in the open source world (compare it with upstream). The term downstream refers to people or organizations like SUSE who integrate the source code from upstream with other software to build a distribution which is then used by end users. Thus, the software flows downstream from its developers via the integrators to the end users.
- Extensions, Add-On Products
Extensions and third party add-on products provide additional functionality of product value to SUSE Linux Enterprise Server. They are provided by SUSE and by SUSE partners, and they are registered and installed on top of the base product SUSE Linux Enterprise Server.
- LTSS
LTSS is the abbreviation for Long Term Service Pack Support, which is available as an extension for SUSE Linux Enterprise Server.
- Major Release, General Availability (GA) Version
The major release of SUSE Linux Enterprise (or any software product) is a new version which brings new features and tools, decommissions previously deprecated components and comes with backward-incompatible changes. Major releases for example are SUSE Linux Enterprise 12 or 15.
- Migration
Updating to a Service Pack (SP) by using the online update tools or an installation medium to install the respective patches. It updates all packages of the installed system to the latest state.
- Migration Targets
Set of compatible products to which a system can be migrated, containing the version of the products/extensions and the URL of the repository. Migration targets can change over time and depend on installed extensions. Multiple migration targets can be selected, for example SLE 15 SP1 and SES 6.
- Modules
Modules are fully supported parts of SUSE Linux Enterprise Server with a different life cycle. They have a clearly defined scope and are delivered via online channel only. Registering at the SUSE Customer Center, RMT (Repository Mirroring Tool), or SUSE Manager is a prerequisite for being able to subscribe to these channels.
- Package
A package is a compressed file in
rpm
format that contains all files for a particular program, including optional components like configuration, examples, and documentation.- Patch
A patch consists of one or more packages and may be applied by means of delta RPMs. It may also introduce dependencies to packages that are not installed yet.
- Service Packs (SP)
Combines several patches into a form that is easy to install or deploy. Service packs are numbered and usually contain security fixes, updates, upgrades, or enhancements of programs.
- Upstream
A metaphor of how software is developed in the open source world (compare it with downstream). The term upstream refers to the original project, author or maintainer of a software that is distributed as source code. Feedback, patches, feature enhancements, or other improvements flow from end users or contributors to upstream developers. They decide if the request will be integrated or rejected.
If the project members decide to integrate the request, it will show up in newer versions of the software. An accepted request will benefit all parties involved.
If a request is not accepted, it may be for different reasons. Either it is in a state that is not compliant with the project's guidelines, it is invalid, it is already integrated, or it is not in the interest or roadmap of the project. An unaccepted request makes it harder for upstream developers as they need to synchronize their patches with the upstream code. This practice is generally avoided, but sometimes it is still needed.
- Update
Installation of a newer minor version of a package, which usually contains security or bug fixes.
- Upgrade
Installation of a newer major version of a package or distribution, which brings new features. For a distinction between the upgrade options, see Section 1.3, “Online and Offline Upgrade”.
2.2 Product Life Cycle #
SUSE has the following lifecycle for products:
SUSE Linux Enterprise Server has a 13-year lifecycle: 10 years of general support and three years of extended support.
SUSE Linux Enterprise Desktop has a 10-year lifecycle: seven years of general support and three years of extended support.
Major releases are made every four years. Service packs are made every 12-14 months.
SUSE supports previous service packs for six months after the release of the new service pack. Figure 2.1, “Major Releases and Service Packs” depicts some mentioned aspects.
If you need additional time to design, validate and test your upgrade plans, Long Term Service Pack Support can extend the support you get by an additional 12 to 36 months in 12-month increments. This gives you a total of 2 to 5 years of support on any service pack. For details, see Figure 2.2, “Long Term Service Pack Support”.
For more information refer to https://www.suse.com/products/long-term-service-pack-support/.
Refer to https://www.suse.com/lifecycle for more information about lifecycles, release frequency, and the overlay support period.
2.3 Module Dependencies and Lifecycles #
For a list of modules, their dependencies, and lifecycles, see the Article “Modules and Extensions Quick Start”.
2.4 Generating Periodic Lifecycle Report #
SUSE Linux Enterprise Server can regularly check for changes in the support status of all
installed products and send the report via e-mail in case of changes. To
generate the report, install the zypper-lifecycle-plugin
with zypper in zypper-lifecycle-plugin
.
Enable the report generation on your system with systemctl
:
>
sudo
systemctl
enable lifecycle-report.timer
The recipient and subject of the report e-mail, and the report
generation period can be configured in the file
/etc/sysconfig/lifecycle-report
with any text editor.
The settings MAIL_TO
and MAIL_SUBJ
define the mail recipient and subject, while DAYS
sets the
interval at which the report is generated.
The report displays changes in the support status after the change
occurred and not in advance. If the change occurs right after the generation
of the last report, it can take up to 14 days until you are notified of
the change. Take this into account when setting the DAYS
option.
Change the following configuration entries to fit your requirements:
MAIL_TO='root@localhost' MAIL_SUBJ='Lifecycle report' DAYS=14
The latest report is available in the file /var/lib/lifecycle/report
.
The file contains two sections. The first section informs about the end of
support for used products. The second section lists packages with their
support end dates and update availability.
2.5 Support Levels #
The range for extended support levels starts from year 10 and ends in year 13. These contain continued L3 engineering level diagnosis and reactive critical bug fixes. With these support levels, you will receive updates for trivially exploitable root exploits in the kernel and other root exploits directly executable without user interaction. Furthermore, they support existing workloads, software stacks, and hardware with limited package exclusion list. Find an overview in Table 2.1, “Security Updates and Bug Fixes”.
General Support for Most Recent Service Pack (SP) |
General Support for Previous SP, with LTSS |
Extended Support with LTSS | |||
---|---|---|---|---|---|
Feature |
Year 1-5 |
Year 6-7 |
Year 8-10 |
Year 4-10 |
Year 10-13 |
Technical Services |
Yes |
Yes |
Yes |
Yes |
Yes |
Access to Patches and Fixes |
Yes |
Yes |
Yes |
Yes |
Yes |
Access to Documentation and Knowledge Base |
Yes |
Yes |
Yes |
Yes |
Yes |
Support for Existing Stacks and Workloads |
Yes |
Yes |
Yes |
Yes |
Yes |
Support for New Deployments |
Yes |
Yes |
Limited (Based on partner and customer requests) |
Limited (Based on partner and customer requests) |
No |
Enhancement Requests |
Yes |
Limited (Based on partner and customer requests) |
Limited (Based on partner and customer requests) |
No |
No |
Hardware Enablement and Optimization |
Yes |
Limited (Based on partner and customer requests) |
Limited (Based on partner and customer requests) |
No |
No |
Driver updates via SUSE SolidDriver Program (formerly PLDP) |
Yes |
Yes |
Limited (Based on partner and customer requests) |
Limited (Based on partner and customer requests) |
No |
Backport of Fixes from Recent SP |
Yes |
Yes |
Limited (Based on partner and customer requests) |
N/A |
N/A |
Security Updates1 |
All |
All |
All |
Critical only |
Critical only |
Defect Resolution |
Yes |
Yes |
Limited (Severity Level 1 and 2 defects only) |
Limited (Severity Level 1 and 2 defects only) |
Limited (Severity Level 1 and 2 defects only) |
1 For further information on the SUSE Linux Enterprise Update Policy, refer to the following knowledgebase article.
2.6 Registering and Deregistering Machines with SUSEConnect #
On registration, the system receives repositories from the SUSE Customer Center (see
https://scc.suse.com/) or a local registration proxy like SMT.
The repository names map to specific URIs in the customer center. To list
all available repositories on your system, use zypper
as
follows:
#
zypper
repos -u
This gives you a list of all available repositories on your system. Each
repository is listed by its alias, name and whether it is enabled and will
be refreshed. The option -u
gives you also the URI from
where it originated.
To register your machine, run SUSEConnect, for example:
#
SUSEConnect
-r REGCODE
To deregister your machine, you can use SUSEConnect too:
#
SUSEConnect
--de-register
To check your locally installed products and their status, use the following command:
#
SUSEConnect
-s
2.7 Enabling LTSS support #
Long Term Service Pack Support
(LTSS) extends the
lifecycle of SUSE Linux Enterprise Server. It is available as an extension. For more
information about LTSS, refer to https://www.suse.com/products/long-term-service-pack-support/
To enable the LTSS extension, perform the following steps:
Make sure your system is registered with a subscription that is eligible for LTSS. If the system is not yet registered, run:
>
sudo
SUSEConnect -r REGISTRATION_CODE -e EMAIL_ADDRESS
Make sure the LTSS extension is available for your system:
>
sudo
SUSEConnect --list-extensions | grep LTSS
SUSE Linux Enterprise Server LTSS 15 SP2 x86_64 Activate with: SUSEConnect -p SLES-LTSS/15.2/x86_64 -r ADDITIONAL REGCODEActivate the module as instructed:
>
sudo
SUSEConnect -p SLES-LTSS/15.2/x86_64 -r REGISTRATION_CODE
2.8 Identifying the SLE Version #
If you need to identify the version of an SLE installation, check the
content of the file /etc/os-release
.
A machine readable XML output is available with zypper
:
>
zypper --no-remote --no-refresh --xmlout --non-interactive products -i
<?xml version='1.0'?> <stream> <product-list> <product name="SLES" version="15" release="0" epoch="0" arch="x86_64" vendor="SUSE" summary="SUSE Linux Enterprise Server 15" repo="@System" productline="sles" registerrelease="" shortname="SLES15" flavor="" isbase="true" installed="true"><endoflife time_t="0" text="0"/><registerflavor/><description>SUSE Linux Enterprise offers [...]</description></product> </product-list> </stream>
3 Preparing the Upgrade #
Before starting the upgrade procedure, make sure your system is properly prepared. Among others, preparation involves backing up data and checking the release notes. The following chapter guides through these steps.
3.1 Make Sure the Current 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
.
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.
Check the release notes to see whether:
your hardware needs special considerations;
any used software packages have changed significantly;
special precautions are necessary for your installation.
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 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 with 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.5 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.6 Upgrading from SUSE Linux Enterprise Server 11 SP4 #
If you are using MySQL, PostgreSQL or Java MD5-based certificates on SUSE Linux Enterprise Server 11 SP4, prepare your system as described in the following sections. In addition, make sure to check the other sections of this chapter for further required preparations.
3.6.1 Migrate Your PostgreSQL Database #
If you are using a PostgreSQL database on SUSE Linux Enterprise Server 11, you need to upgrade your database. For more information, see Section 3.7, “Migrate Your PostgreSQL Database”.
3.6.2 Migrate Your MySQL 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:
Log in to your SUSE Linux Enterprise 11 machine.
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://dev.mysql.com/doc/refman/5.5/en/mysqldump.html.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.6.3 Create Non-MD5 Server Certificates for Java Applications #
During the update from SP1 to SP2, MD5-based certificates were disabled as part of a security fix. 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.7 Migrate Your PostgreSQL Database #
SUSE Linux Enterprise Server 15 SP2 ships with the PostgreSQL database versions 10 and 12. While Version 12 is the default, version 10 is still provided 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 & 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/postgres12/
for version 12.
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 9.6 to 10. 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 of the new PostgreSQL major version. For SLE 15 SP2 this means to install postgresql10-server and all the packages it depends on.
Install the package postgresql10-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 very long!):VACUUM FULL
Stop the PostgreSQL server with either:
#
/usr/sbin/rcpostgresql
stopor
#
systemctl stop postgresql.service(depending on the SLE version you use 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 use 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/
, the new versions can be found in/var/lib/pgsql/data
.Note that just 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/postgresql96/bin/" \ --new-bindir "/usr/lib/postgresql10/bin/"Start your new database instance with either:
#
/usr/sbin/rcpostgresql
startor
#
systemctl start postgresql.service(depending on the SLE version you use 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 postgresql96 | xargs zypper rm -u#
rm
-rf /var/lib/pgsql/data.old
For more information about upgrading databases or using alternative methods such logical replication, refer to the official PostgreSQL documentation at https://www.postgresql.org/docs/10/upgrading.html.
3.8 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.9 Adjusting your SMT client setup #
If the machine you want to upgrade is registered as a client against an SMT server, take care of 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, de-register 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 de-registered 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 de-registered by re-running:
>
sudo
smt-list-registrations
3.10 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.10.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.10.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 Book “Storage Administration Guide”, Chapter 1 “Overview of File Systems in Linux”, 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.
If you use Btrfs as 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 are only freed after new RPMs are installed.
For Btrfs with snapshots, you need at minimum as much free space as your current installation takes. We recommend to have 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.11 Changes in AutoYaST Profiles from SLE 12 to 15 #
To learn how to migrate your AutoYaST profiles, see Book “AutoYaST Guide”, .
3.12 Upgrading a Subscription Management Tool (SMT) Server #
A server running SMT requires a special upgrade procedure. Please refer to Book “Repository Mirroring Tool Guide”, Chapter 2 “Migrate from SMT to RMT” in the Repository Mirroring Tool Guide.
3.13 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 Book “Deployment Guide”, Chapter 23 “Installing Multiple Kernel Versions”, Section 23.1 “Enabling and Configuring Multiversion Support”.
3.14 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.15 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 Book “Deployment Guide”, Chapter 5 “Installation on IBM Z and LinuxONE”, Section 5.5 “The Parmfile—Automating the System Configuration”.
3.16 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"
4 Upgrading Offline #
This chapter describes how to upgrade an existing SUSE Linux Enterprise installation using YaST which is booted from an installation medium. The YaST installer can, for example, be started from a DVD, over the network, or from the hard disk the system resides on.
4.1 Conceptual Overview #
Before upgrading your system, read Chapter 3, Preparing the Upgrade first.
To upgrade your system, boot from an installation source, as you would do for a fresh installation. However, when the boot screen appears, you need to select
(instead of ). The upgrade can be started from:Removable Media. This includes media such as CDs, DVDs or USB mass storage devices. For more information, see Section 4.2, “Starting the Upgrade from an Installation Medium”.
Network Resource. You can either boot from the local medium and then select the respective network installation type, or boot via PXE. For more information, see Section 4.3, “Starting the Upgrade from a Network Source”.
4.2 Starting the Upgrade from an Installation Medium #
The procedure below describes booting from a DVD, but you can also use another local installation medium like an ISO image on a USB mass storage device. The medium and boot method to select depends on the system architecture and on whether the machine has a traditional BIOS or UEFI.
Select and prepare a boot medium, see Book “Deployment Guide”.
Insert the Unified Installer DVD for SUSE Linux Enterprise Server 15 SP2 and boot your machine. A screen is displayed, followed by the boot screen.
(Optional) To force the installer to only install packages from the DVD and not from network sources, add the boot option
media_upgrade=1
.Start up the system by selecting Upgrade in the boot menu.
Proceed with the upgrade process as described in Section 4.4, “Upgrading SUSE Linux Enterprise”.
4.3 Starting the Upgrade from a Network Source #
To start an upgrade from a network installation source, make sure that the following requirements are met:
- Network Installation Source
A network installation source is set up according to Book “Deployment Guide”, Chapter 16 “Setting Up a Network Installation Source”.
- Network Connection and Network Services
Both the installation server and the target machine must have a functioning network connection. Required network services are:
Domain Name Service
DHCP (only needed for booting via PXE, IP can be set manually during setup)
OpenSLP (optional)
- Boot Medium
A bootable SUSE Linux Enterprise DVD, ISO image or functioning PXE setup. For details about booting via PXE, see Book “Deployment Guide”, Chapter 17 “Preparing Network Boot Environment”, Section 17.4 “Preparing the Target System for PXE Boot”. Refer to Book “Deployment Guide”, Chapter 11 “Remote Installation” for in-depth information on starting the upgrade from a remote server.
4.3.1 Manually Upgrading via Network Installation Source—Booting from DVD #
This procedure describes booting from a DVD as an example, but you can also use another local installation medium like an ISO image on a USB mass storage device. The way to select the boot method and to start up the system from the medium depends on the system architecture and on whether the machine has a traditional BIOS or UEFI. For details, see the links below.
Insert the Unified Installer DVD for SUSE Linux Enterprise Server 15 SP2 and boot your machine. A screen is displayed, followed by the boot screen.
Select the type of network installation source you want to use (FTP, HTTP, NFS, SMB, or SLP). Usually you get this choice by pressing F4, but in case your machine is equipped with UEFI instead of a traditional BIOS, you may need to manually adjust boot parameters. For details, see Book “Deployment Guide”, Chapter 7 “Boot Parameters” and Book “Deployment Guide”, Chapter 8 “Installation Steps”.
Proceed with the upgrade process as described in Section 4.4, “Upgrading SUSE Linux Enterprise”.
4.3.2 Manually Upgrading via Network Installation Source—Booting via PXE #
To perform an upgrade from a network installation source using PXE boot, proceed as follows:
Adjust the setup of your DHCP server to provide the address information needed for booting via PXE. For details, see Book “Deployment Guide”, Chapter 17 “Preparing Network Boot Environment”, Section 17.1.1 “Dynamic Address Assignment”.
Set up a TFTP server to hold the boot image needed for booting via PXE. Use the Installer DVD for SUSE Linux Enterprise Server 15 SP2 for this or follow the instructions in Book “Deployment Guide”, Chapter 17 “Preparing Network Boot Environment”, Section 17.2 “Setting Up a TFTP Server”.
Prepare PXE Boot and Wake-on-LAN on the target machine.
Initiate the boot of the target system and use VNC to remotely connect to the installation routine running on this machine. For more information, see Book “Deployment Guide”, Chapter 11 “Remote Installation”, Section 11.3 “Monitoring Installation via VNC”.
Proceed with the upgrade process as described in Section 4.4, “Upgrading SUSE Linux Enterprise”.
4.4 Upgrading SUSE Linux Enterprise #
Before you upgrade your system, read Chapter 3, Preparing the Upgrade first. To perform an automated migration, proceed as follows:
If the system you want to upgrade is registered with the SUSE Customer Center, make sure to have an Internet connection during the following procedure.
After you have booted (either from an installation medium or the network), select the
entry on the boot screen.Warning: Wrong Choice May Lead to Data LossMake sure you selected
at this point. If you select by mistake, your data partition will be overwritten with a fresh installation.YaST starts the installation system.
On the
screen, choose and . Proceed with .YaST checks your partitions for already installed SUSE Linux Enterprise systems.
On the
screen, select the partition to upgrade and click .YaST mounts the selected partition and displays the license agreement for the upgraded product. To continue, accept the license.
On the
screen, adjust the status of the repositories. By default all repositories are removed. If you have not added any custom repositories, do not change the settings. The packages for the upgrade will be installed from DVD, and you can optionally enable the default online repositories in the next step.If you have custom repositories, you have two choices:
Leave the repository in state Removed. Software that was installed from this repository will be removed during the upgrade. Use this method if no version of the repository that matches the new release is available.
Update and enable the repository if it matches the new release. Change its URL by clicking the repository in the list, and then click
. Enable the repository by checking until it is set to .
Do not keep repositories from the previous release, as the system may be unstable or not work at all. Then proceed by clicking
.The next step depends on whether the upgraded system is registered with the SUSE Customer Center or not.
If the system is not registered with the SUSE Customer Center, YaST displays a pop-up message suggesting using a second installation medium, the SLE-15-SP2-Full-ARCH-GM-media1.iso image.
If you do not have that medium, the system cannot be upgraded without registration.
If the system is registered with the SUSE Customer Center, YaST will show possible migration targets and a summary.
Select one migration target from the list and proceed with
.
In the next dialog you can optionally add an additional installation medium. If you have additional installation media, activate the
option and specify the media type.Review the
for the upgrade.If all settings are according to your wishes, start the installation and removal procedure by clicking
.Tip: Upgrade Failure on SMT ClientsIf the machine to upgrade is an SMT client, and the upgrade fails, see Procedure 3.1, “De-registering a SUSE Linux Enterprise Client from an SMT Server” and restart the upgrade procedure afterward.
After the upgrade process has finished successfully, perform post-upgrade checks as described in Section 4.4.1, “Post-upgrade Checks”.
4.4.1 Post-upgrade Checks #
Check for any “orphaned packages”. During an upgrade procedure, packages may be renamed, removed, merged, or split. As a result, certain packages can become orphaned and unsupported. Orphaned packages are not automatically removed. The following command gives you a list of these:
>
zypper packages --orphaned --unneededUse the list to determine which packages are still needed and which packages can be safely removed.
Check for any
*.rpmnew
and*.rpmsave
files, examine their content, and possibly merge desirable changes. When an upgrade includes changes to a default configuration file, instead of overwriting the configuration file, the package will write one of these file types. While*.rpmnew
contains the new default configuration and leaves your original file untouched,*.rpmsave
is a copy of your original configuration that has been replaced by the new default file.You do not need to search the whole file system for
*.rpmnew
and*.rpmsave
files, the most important are stored in the/etc
directory. Use the following command to list them:>
find /etc -print | egrep "rpmnew$|rpmsave$"
4.5 Upgrading with AutoYaST #
The upgrade process can be executed automatically. For details, see Book “AutoYaST Guide”, Chapter 4 “Configuration and Installation Options”, Section 4.10 “Upgrade”.
4.6 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.
With SUSE Manager you can perform a system upgrade. With the integrated AutoYaST technology, upgrades from one major version to the next are possible.
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/.
4.7 Updating Registration Status after Rollback #
When performing a service pack upgrade, it is necessary to change the configuration on the registration server to provide access to the new repositories. If the upgrade process is interrupted or reverted (via restoring from a backup or snapshot), the information on the registration server is inconsistent with the status of the system. This may lead to you being prevented from accessing update repositories or to wrong repositories being used on the client.
When a rollback is done via Snapper, the system will notify the registration server to ensure access to the correct repositories is set up during the boot process. If the system was restored with another method, or the communication with the registration server failed, trigger the rollback on the client manually. An example for manually triggering a rollback can be that the server was not accessible because of network issues. To do a rollback, execute:
>
sudo
snapper
rollback
We suggest always checking that the correct repositories are set up on the system, especially after refreshing the service using:
>
sudo
zypper
ref -s
This functionality is available in the rollback-helper package.
4.8 Registering Your System #
If the system was not registered before running the upgrade you can register your system at any time using the
module in YaST.Registering your systems has these advantages:
Eligibility for support
Availability of security updates and bug fixes
Access to SUSE Customer Center
Start YaST and select
› to open the dialog.Provide the https://scc.suse.com/) to create one.
address associated with the SUSE account you or your organization uses to manage subscriptions. In case you do not have a SUSE account yet, go to the SUSE Customer Center home page (Enter the SUSE Linux Enterprise Server.
you received with your copy ofIf one or more local registration servers are available on your network, you can choose one of them from a list.
To start the registration, proceed with
.After successful registration, YaST lists extensions, add-ons, and modules that are available for your system. To select and install them, proceed with Book “Deployment Guide”, Chapter 22 “Installing Modules, Extensions, and Third Party Add-On Products”, Section 22.1 “Installing Modules and Extensions from Online Channels”.
5 Upgrading Online #
SUSE offers an intuitive graphical and a simple command line tool to upgrade a running system to a new service pack. They provide support for “rollback” of service packs and more. This chapter explains how to do a service pack upgrade step by step with 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
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 1, Upgrade Paths and Methods.
Use the offline migration to upgrade to a new major release. For details, see Chapter 4, Upgrading Offline.
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:
Find possible migration targets on your registered systems.
Select one migration target.
Request and enable new repositories.
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:
Until the package upgrade starts, there are only minimal changes on the system, like for services and repositories. Restore
/etc/zypp/repos.d/*
to revert to the former state.After the package upgrade starts, you can revert to the former state by using a Snapper snapshot (see Book “Administration Guide”, Chapter 7 “System Recovery and Snapshot Management with Snapper”).
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
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.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, add the parameter --no-recommends
to your command line.
To start the service pack migration, do the following:
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.
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).
Run YaST online update to get the latest package updates for your system.
Install the package yast2-migration and its dependencies (in YaST under › ).
Restart YaST, otherwise the newly installed module will not be shown in the control center.
In YaST, choose SUSE Linux Enterprise Server that you are upgrading from, this module is categorized under either or ). 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.
(depending on the version ofSelect one migration target from the list and proceed with
.In case the migration tool offers update repositories, it is recommended to proceed with
.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
that are not specific to a product version or service pack. If necessary, you can manually check the repository configuration after the migration.Check the summary and proceed with the migration by clicking
. Confirm with .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.
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, add the parameter --no-recommends
to your command line.
To start the service pack migration, do the following:
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).
Register your SUSE Linux Enterprise machine if you have not done so:
>
sudo
SUSEConnect
--regcode YOUR_REGISTRATION_CODEStart 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 tozypper
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.
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 Shift–Page ↑ or Shift–Page ↓ keys to scroll in your shell.
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.
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.
This migration path requires you to provide the installation sources for the new service pack in a place that can be accessed by the machine you are going to migrate. This can for example be achieved 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.
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).
Update the package management tools with the old SUSE Linux Enterprise repositories:
>
sudo
zypper
patch --updatestack-onlyGet 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 --orphanedCarefully 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.
Get a list of all repositories that the system is currently subscribed to by running:
>
sudo
zypper repos -uUpdate each repository URL so that its product version number is
15-SP2
. For example, if the URL of a repository ishttp://rmt.example.com/repo/SUSE/Products/SLE-15-SP1-Product-SLES/x86_64/product/
change it to
http://rmt.example.com/repo/SUSE/Products/SLE-15-SP2-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:
Using
› › . Select a repository and click to make the required change. Repeat this for all repositories.Using Zypper. Remove the old repository by running
>
sudo
zypper removerepo OLD_REPO_IDfollowed by adding the corresponding new repository by running
>
sudo
zypper addrepo -f URL NAME-15-SP2By editing repository configuration files in
/etc/zypp/repos.d
. Each repository is represented by one configuration file. Changing the value for thebaseurl
parameter is required in each file.
Review your changes by running
zypper repos -u
and update the repositories by running:>
sudo
zypper refresh -f -sIn 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 -sagain, to make sure all repositories are up-to-date.
Before starting the migration it is recommended do a test run first:
>
sudo
zypper dup -D --no-allow-vendor-change --no-recommendsThe 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.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 --orphanedCompare 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 PACKAGESYou 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 Book “Administration Guide”, Chapter 7 “System Recovery and Snapshot Management with Snapper” for details.
Get a list of all Snapper snapshots:
>
sudo
snapper listReview the output to locate the snapshot that was created immediately before the service pack migration was started. The column
contains a corresponding statement and the snapshot is marked asimportant
in the column . Memorize the snapshot number from the column and its date from the column .Reboot the system. From the boot menu, select 15 SP2 and boot it.
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 SLESThe 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 rollbackReboot afterward. On the boot screen, choose the default boot entry to reboot into the reinstated system.
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.
Refresh services and repositories by running
>
sudo
zypper ref -fsGet a list of active repositories by running
>
sudo
zypper lrCarefully 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 SP2 to SLES15 GA, the list must contain the
SLES15-GA
repositories, and not theSLES15-SP2
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 2.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.)
Last, check the registration status for all products installed by running
>
sudo
SUSEConnect --statusAll 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 SP2).
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/.
5.9 Upgrading from openSUSE Leap to SUSE Linux Enterprise Server #
You can upgrade an openSUSE installation online to SUSE Linux Enterprise Server. The procedure is analogous to Section 5.5, “Upgrading with Zypper”, but some additional steps are required. Before executing this procedure on a production system, we recommend to first run it on a test system that replicates your production setup.
To see for which openSUSE Leap versions a migration is supported, read Section 1.2, “Supported Upgrade Paths to SLES 15 SP2”.
The openSUSE repositories provide more packages than are available in the SUSE Linux Enterprise Server repositories. If you have any of these packages installed, they will no longer receive updates after the migration. These packages will be removed when following the procedure below.
Make sure that all packages you need for operating your system are available in the SUSE Linux Enterprise Server repository. You can also check if the packages are available in the SUSE Package Hub repository. For details, see Book “Deployment Guide”, Chapter 22 “Installing Modules, Extensions, and Third Party Add-On Products”, Section 22.3 “SUSE Package Hub”.
To migrate from openSUSE Leap, execute the following procedure:
Switch to a TTY, for example by pressing Ctrl–Alt–F1. Then log in as
root
.Install SUSEConnect.
#
zypper in SUSEConnect
Register at SCC to get the SUSE Linux Enterprise Server repositories.
#
SUSEConnect -r REGISTRATION_CODE -p SLES/15.2/x86_64
List and disable all openSUSE repositories on your system.
#
zypper lr
#
zypper mr -d REPO_IDS
Replace REPO_IDS with a space character separated list of all enabled openSUSE repositories.
Now add the modules you need for your installation.
#
SUSEConnect --list-extensions
#
SUSEConnect -p sle-module-basesystem/15.2/x86_64
To have replacements for most Leap packages, we recommend to enable the Basesystem, Desktop Applications, Server Applications and Legacy modules. Additionally, we recommend to enable the SUSE Package Hub.
Migrate installed packages to the SUSE Linux Enterprise Server repositories.
#
zypper dup --force-resolution
Remove orphaned packages.
#
zypper rm $(zypper --no-refresh packages --orphaned | gawk '{print $5}' | tail -n +5)
Finally, reboot the system.
6 Backports of Source Code #
SUSE extensively uses backports, for example for the migration of current software fixes and features into released SUSE Linux Enterprise packages. The information in this chapter explains why it can be misleading to compare version numbers to judge the capabilities and the security of SUSE Linux Enterprise software packages. This chapter also explains how SUSE keeps the system software secure and current while maintaining compatibility for your application software on top of SUSE Linux Enterprise products. You will also learn how to check which public security issues actually are addressed in your SUSE Linux Enterprise system software, and the current status of your software.
6.1 Reasons for Backporting #
Upstream developers are primarily concerned with advancing the software they develop. Often they combine fixing bugs with introducing new features which have not yet received extensive testing and which may introduce new bugs.
For distribution developers, it is important to distinguish between:
bugfixes with a limited potential for disrupting functionality; and
changes that may disrupt existing functionality.
Usually, distribution developers do not follow all upstream changes when a package has become part of a released distribution. Usually they stick instead with the upstream version that they initially released and create patches based on upstream changes to fix bugs. This practice is known as backporting.
Distribution developers generally will only introduce a newer version of software in two cases:
when the changes between their packages and the upstream versions have become so large that backporting is no longer feasible, or
for software that inherently ages badly, like anti-malware software.
SUSE uses backports extensively as we strike a good balance between several concerns for enterprise software. The most important of them are:
Having stable interfaces (APIs) that software vendors can rely on when building products for use on SUSE's enterprise products.
Ensuring that packages used in the release of SUSE's enterprise products are of the highest quality and have been thoroughly tested, both in themselves and as part of the whole enterprise product.
Maintaining the various certifications of SUSE's enterprise products by other vendors, like certifications for Oracle or SAP products.
Allowing SUSE's developers to focus on making the next product version, rather than spreading their focus thinly across a wide range of releases.
Keeping a clear view of what is in a particular enterprise release, so that our support can provide accurate and timely information about it.
6.2 Reasons against Backports #
It is a general policy rule that no new upstream versions of a package are introduced into our enterprise products. This rule is not an absolute rule however. For certain types of packages, in particular anti-virus software, security concerns weigh heavier than the conservative approach that is preferable from the perspective of quality assurance. For packages in that class, occasionally newer versions are introduced into a released version of an enterprise product line.
Sometimes also for other types of packages the choice is made to introduce a new version rather than a backport. This is done when producing a backport is not economically feasible or when there is a very relevant technical reason to introduce the newer version.
6.3 The Implications of Backports for Interpreting Version Numbers #
Because of the practice of backporting, one cannot simply compare version numbers to determine whether a SUSE package contains a fix for a particular issue or has had a particular feature added to it. With backporting, the upstream part of a SUSE package's version number merely indicates what upstream version the SUSE package is based on. It may contain bug fixes and features that are not in the corresponding upstream release, but that have been backported into the SUSE package.
One particular area where this limited value of version numbers when backporting is involved can cause problems is with security scanning tools. Some security vulnerability scanning tools (or particular tests in such tools) operate solely on version information. These tools and tests are therefore prone to generating “false positives” (when a piece of software is incorrectly identified as vulnerable) when backports are involved. When evaluating reports from security scanning tools, always check whether an entry is based on a version number or on an actual vulnerability test.
6.4 Checking for Fixed Bugs and Backported Features #
There are several locations where information regarding backported bug fixes and features are stored:
The package's changelog:
>
rpm -q --changelog name-of-installed-package>
rpm -qp --changelogpackagefile.rpmpackagefile.rpm
The output briefly documents the change history of the package.
The package changelog may contain entries like
bsc#1234
(“BugzillaSuse. Com”) that refer to bugs in SUSE's Bugzilla tracking system or links to other bugtracking systems. Because of confidentiality policies, not all such information may be accessible to you.A package may contain a
/usr/share/doc/PACKAGENAME /README.SUSE
file which contains general, high-level information specific to the SUSE package.The RPM source package contains the patches that were applied during the building of the regular binary RPMs as separate files that can be interpreted if you are familiar with reading source code. See Book “Administration Guide”, Chapter 6 “Managing Software with Command Line Tools”, Section 6.1.3.5 “Installing or Downloading Source Packages” for installing sources of SUSE Linux Enterprise software. See Book “Administration Guide”, Chapter 6 “Managing Software with Command Line Tools”, Section 6.2.5 “Installing and Compiling Source Packages” for building packages on SUSE Linux Enterprise. See the Maximum RPM book for details about software package builds for SUSE Linux Enterprise.
For security bug fixes, consult the SUSE security announcements. These often refer to bugs through standardized names like
CAN-2005-2495
which are maintained by the Common Vulnerabilities and Exposures (CVE) project.
A GNU licenses #
This appendix contains the GNU Free Documentation License version 1.2.
GNU Free Documentation License #
Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
0. PREAMBLE #
The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS #
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
2. VERBATIM COPYING #
You may copy and distribute the Document in any medium, either commercially or non-commercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY #
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS #
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS #
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS #
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS #
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
8. TRANSLATION #
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
9. TERMINATION #
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE #
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents #
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.