Skip to content

Commit 0f1de81

Browse files
cwickertcwickert
committed
SLE 16 upgrade: Add DMS customization reference
1 parent ceda5a6 commit 0f1de81

File tree

2 files changed

+224
-5
lines changed

2 files changed

+224
-5
lines changed

‎articles/sle16-upgrade.asm.xml‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,11 +54,9 @@
5454
<description>Finishing the upgrade</description>
5555
</resource>
5656
<!-- References -->
57-
<!--
58-
<resource xml:id="_reference-example" href="../references/reference.xml">
59-
<description>Reference example</description>
57+
<resource xml:id="_reference-sle16-upgrade-distribution-migration-system" href="../references/sle16-upgrade-dms.xml">
58+
<description>DMS configuration reference </description>
6059
</resource>
61-
-->
6260
<!-- Legal -->
6361
<resource href="../common/legal.xml" xml:id="_legal">
6462
<description>Legal Notice</description>
@@ -204,6 +202,11 @@
204202
<title>Preparing the upgrade</title>
205203
</merge>
206204
</module>
205+
<module resourceref="_reference-sle16-upgrade-distribution-migration-system" renderas="section">
206+
<merge>
207+
<title>Customizing the upgrade process</title>
208+
</merge>
209+
</module>
207210
<module resourceref="_task-sle16-upgrade" renderas="section">
208211
<merge>
209212
<title>Performing the upgrade</title>
@@ -214,7 +217,6 @@
214217
<title>Finishing the upgrade</title>
215218
</merge>
216219
</module>
217-
<!-- <module resourceref="_reference-example" renderas="section"/> -->
218220
<module resourceref="_glue-sle16-upgrade-more-info" renderas="section"/>
219221
<!-- <module resourceref="_glue-sle16-upgrade-whats-next" renderas="section"/> -->
220222
<module resourceref="_legal"/>

‎references/sle16-upgrade-dms.xml‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
3+
<!-- This file can be edited downstream. -->
4+
<!DOCTYPE topic
5+
[
6+
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
7+
%entities;
8+
]>
9+
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
10+
<!-- point back to this document with a similar comment added to your legacy doc piece -->
11+
<!-- refer to README.md for file and id naming conventions -->
12+
<!-- metadata is dealt with on the assembly level -->
13+
<topic xml:id="reference-sle16-upgrade-distribution-migration-system"
14+
role="reference" xml:lang="en"
15+
xmlns="http://docbook.org/ns/docbook" version="5.2"
16+
xmlns:its="http://www.w3.org/2005/11/its"
17+
xmlns:xi="http://www.w3.org/2001/XInclude"
18+
xmlns:xlink="http://www.w3.org/1999/xlink"
19+
xmlns:trans="http://docbook.org/ns/transclusion">
20+
<info>
21+
<title>Reference</title>
22+
<!--add author's email address-->
23+
<meta name="maintainer" content="[email protected]" its:translate="no"/>
24+
<abstract><!-- can be changed via merge in the assembly -->
25+
<para>
26+
Introductory text
27+
</para>
28+
</abstract>
29+
</info>
30+
<section xml:id="reference-example-section">
31+
<title>Section title</title>
32+
<para>
33+
A paragraph of text.
34+
</para>
35+
<para>
36+
The upgrade live image is pre-configured to run without any further setup. The migration
37+
system reads a custom configuration file from the system to be upgraded. The content of this
38+
file modifies the behavior of the upgrade process. Prior to the start of the upgrade process,
39+
create the following file if a change of the default behavior is needed:
40+
</para>
41+
<screen>&prompt.sudo; <command>ssh</command> INSTANCE_USER@IP_OF_INSTANCE touch <filename>/etc/sle-migration-service.yml'</filename></screen>
42+
<para>
43+
The custom config file supports the following settings:
44+
</para>
45+
<variablelist>
46+
<varlistentry>
47+
<term>Control Zypper Installation Mode</term>
48+
<listitem>
49+
<para>
50+
If the upgrade process is used on systems that are not registered or for which the
51+
repository server has no upgrade path, it is required to switch off the use of the
52+
migration workflow.
53+
</para>
54+
<screen>use_zypper_migration: true|false</screen>
55+
<note>
56+
<para>
57+
The use of the migration workflow is the default behavior. If the migration workflow is
58+
not used, the setup of the repositories must be performed manually. Once done, the
59+
upgrade process uses <command>zypper dup</command> and expects all required repositories to be
60+
setup correctly.
61+
</para>
62+
</note>
63+
</listitem>
64+
</varlistentry>
65+
<varlistentry>
66+
<term>Specify Migration Product</term>
67+
<listitem>
68+
<para>
69+
By default the system will be migrated to SLES15 SP3. This default
70+
target can be changed via the <literal>migration_product</literal> setting.
71+
The product must be specified with the triplet <literal>name/version/arch</literal>
72+
found in <filename>/etc/products.d/baseproduct</filename> of the target product,
73+
for example:
74+
</para>
75+
<screen>migration_product: SLES/15.3/x86_64</screen>
76+
<warning>
77+
<para>
78+
Changing the default product leads to unsupported territory and
79+
is not tested nor covered by the SUSE support offering !
80+
The specified product name must be supported by the repository
81+
server used for the migration. If the given product does not
82+
exist or the repository server cannot calculate an upgrade
83+
path, an error message from the repository server will be
84+
logged in the migration log file. Also see:
85+
<link xlink:href="https://documentation.suse.com/sles/15-SP6/html/SLES-all/cha-upgrade-background.html">Lifecycle and support</link>
86+
</para>
87+
</warning>
88+
</listitem>
89+
</varlistentry>
90+
<varlistentry>
91+
<term>Preserve System Data</term>
92+
<listitem>
93+
<para>
94+
Preserve custom data file(s) e.g. udev rules from the system
95+
to be migrated into the upgrade live system and make sure
96+
they will become effective.
97+
</para>
98+
<para>
99+
The <literal>preserve</literal> section has three subsections that govern file
100+
preservation and system actions:
101+
</para>
102+
<itemizedlist>
103+
<listitem>
104+
<para>
105+
<literal>static</literal>: Files in this subsection are copied into the DMS
106+
directly, with no further processing.
107+
</para>
108+
</listitem>
109+
<listitem>
110+
<para>
111+
<literal>rules</literal>: If this subsection contains files, they are preserved, and
112+
the DMS reloads udev to make these rules effective.
113+
</para>
114+
</listitem>
115+
<listitem>
116+
<para>
117+
<literal>sysctl</literal>: Preserving these files triggers sysctl --system to apply
118+
the configuration changes.
119+
</para>
120+
<screen>preserve:
121+
rules:
122+
- /etc/udev/rules.d/a.rules
123+
- /etc/udev/rules.d/b.rules
124+
static:
125+
- /etc/sysconfig/proxy
126+
- /path/to/be/preserved/*.suffix</screen>
127+
<note>
128+
<para>
129+
udev rules that require custom drivers will not have the desired effect
130+
as the migration system will not include these drivers and therefore
131+
execution of those rules will fail. Rules with such properties should
132+
not be listed.
133+
</para>
134+
</note>
135+
<note>
136+
<para>
137+
The DMS provides a set of default preservable files that vary based on
138+
the target version and architecture. User-defined values will supplement
139+
this default list.
140+
</para>
141+
</note>
142+
</listitem>
143+
</itemizedlist>
144+
</listitem>
145+
</varlistentry>
146+
<varlistentry>
147+
<term>Enable Debug Mode</term>
148+
<listitem>
149+
<para>
150+
If enabled, prevents the upgrade system from rewinding the setup
151+
steps and rebooting due to a failed upgrade, allowing the issue to
152+
be debugged.
153+
</para>
154+
<screen>debug: true|false</screen>
155+
</listitem>
156+
</varlistentry>
157+
<varlistentry>
158+
<term>Configure Reboot Method</term>
159+
<listitem>
160+
<para>
161+
By default, the migration system uses <literal>kexec</literal> to boot back into the host
162+
system once migration is complete. If this is in any way problematic,
163+
a regular <literal>reboot</literal> can be requested by setting <literal>soft_reboot: false</literal>.
164+
</para>
165+
<screen>soft_reboot: true|false</screen>
166+
</listitem>
167+
</varlistentry>
168+
<varlistentry>
169+
<term>Enable verbosity for zypper migration</term>
170+
<listitem>
171+
<para>
172+
If enabled, it will run the zypper migration plugin with increased verbosity.
173+
</para>
174+
<screen>verbose_migration: true|false</screen>
175+
</listitem>
176+
</varlistentry>
177+
<varlistentry>
178+
<term>Enable the fix option for pre_checks</term>
179+
<listitem>
180+
<para>
181+
If enabled (default), the run_pre_checks systemd process will use the <literal>--fix</literal>
182+
option to automatically remediate applicable issues before the migration
183+
is started.
184+
</para>
185+
<screen>pre_checks_fix: true|false</screen>
186+
</listitem>
187+
</varlistentry>
188+
<varlistentry>
189+
<term>Configure Make initrd Method</term>
190+
<listitem>
191+
<para>
192+
The live system may not contain all necessary tools to create an initrd that
193+
meets the need of the system being upgraded. Building a host independent
194+
initrd will create an initrd in a way that contains the tools and
195+
modules available on the system being upgraded. If this is needed, a host
196+
independent initrd can be created by setting
197+
<literal>build_host_independent_initrd: True</literal>.
198+
</para>
199+
<screen>build_host_independent_initrd: true|false</screen>
200+
</listitem>
201+
</varlistentry>
202+
<varlistentry>
203+
<term>Configure Dependency Solver Test Case Generation</term>
204+
<listitem>
205+
<para>
206+
It is possible that during the migration packages get installed that were not
207+
on the system previously and are pulled in because of dependencies. This
208+
setting will setup the migration such that a solver test case is generated.
209+
The information form the test case can then be used to understand why a
210+
given package was installed.
211+
</para>
212+
<screen>debug_solver: true|false</screen>
213+
</listitem>
214+
</varlistentry>
215+
</variablelist>
216+
</section>
217+
</topic>

0 commit comments

Comments
 (0)