Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc updates to install, migration, and after migration sections #268

Merged
merged 1 commit into from
Jul 18, 2023
Merged

Doc updates to install, migration, and after migration sections #268

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 38 additions & 9 deletions doc/adoc/user_guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,13 @@ If your system is not configured for it, it is recommended that at least
one of the users on the system has a `~/.ssh/authorized_keys` file with a
private key accessible by the person executing the system upgrade.

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

== Upgrade Pre-Checks
The suse-migration-pre-checks package contains the `suse-migration-pre-checks`
script that checks for possible incompatibilities when doing a migration.
Expand Down Expand Up @@ -138,19 +145,16 @@ For data center customers it is recommended to continue to use the
documented offline distribution upgrade using the next distribution
version installation media.

To install the distribution migration system run:

[listing]
tux > sudo zypper in SLES15-Migration

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

Option 1 - Trigger via run_migration::

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

The `run_migration` uses `kexec` to boot into the kernel delivered with the
upgrade image delivered by the SLES15-Migration package. Once this system
Expand All @@ -159,6 +163,19 @@ started. However, `kexec` is not supported and does not function in certain
conditions. The `run_migration` utility does not work in Xen based
environments.

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

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

Option 2 - Trigger via reboot::

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

Starting the migration via reboot after installing the
suse-migration-sle15-activation package covers the Xen use case but does
not work in cases where there is no direct access to the root file system
Expand Down Expand Up @@ -284,19 +301,24 @@ independent initrd can be created by setting
build_host_independent_initrd: true|false

== Run the Migration
Migration can be triggered either via run_migration or via reboot.

Option 1 - Running Migration via run_migration::
After the install of the `SLES15-Migration` package, start the migration
by calling the following command:
process by calling the following command:

[listing]
tux > sudo run_migration

Option 2 - Running Migration via reboot::
[NOTE]
If the `suse-migration-sle15-activation` package was installed,
start the migration by a reboot of the system as follows:
If using the `reboot` method to start migration, reboot the system:

[listing]
tux > sudo reboot

After Migration has been triggered via either method::
[NOTE]
After the upgrade has started, the only way to access the system during the
upgrade process is via ssh with a user called `migration`:

Expand All @@ -314,6 +336,13 @@ Whether the upgrade succeeded or not, a log file is available in
upgrade process. If the upgrade failed, the file `/etc/issue` will contain
a pointer to the respective log file.

In addition, the distribution migration RPM packages `SLES15-Migration`
and `suse-migration-sle15-activation` will be removed.
This is to prevent the migration from being run multiple times and causing
a failure loop.
To start the migration again, the RPMs will need to be reinstalled following
the commands from the Installation Section of this document.

== Caveats and Unsupported Conditions
* Configuration files that have been modified in the original system will
not be overwritten by the upgrade process. The new version of the respective
Expand Down