Distribution Upgrade and Server Migration

SUSE Multi-Linux Manager 5.0 must be stopped before the upgrade.
SUSE Multi-Linux Manager 5.0 is not supported on top of SL Micro 6.1 & SUSE Linux Enterprise Server 15 SP7 as host OS.

SUSE Multi-Linux Manager server hosts that are hardened for security may restrict execution of files from the /tmp folder. In such cases, as a workaround, export the TMPDIR environment variable to another existing path before running mgradm.

For example:

export TMPDIR=/path/to/other/tmp

In SUSE Multi-Linux Manager updates, tools will be changed to make this workaround unnecessary.

1. Requirements and considerations

1.1. SSL certificates

Starting with SUSE Multi-Linux Manager 5.1, the PostgreSQL database runs in a separate container that requires its own SSL certificate during migration. This is why database certificates are needed even when the server certificate and CA chain are copied from the source.

When migrating, SUSE Multi-Linux Manager uses self-signed certificates by default. To use certificates from an external PKI (certificate authority), you can provide all certificate files when running mgradm upgrade using the --ssl* flags.

Table 1. Quick-reference: which flags are needed for your migration
Migration situation	Flags needed
Self-signed CA, everything unchanged	None
New server certificate (same CA)	`--ssl-server-cert`, `--ssl-server-key`
New database certificate (same CA)	`--ssl-db-cert`, `--ssl-db-key`
New server and database certificates (same CA)	`--ssl-server-cert`, `--ssl-server-key`, `--ssl-db-cert`, `--ssl-db-key`
New server certificate + new CA	`--ssl-server-cert`, `--ssl-server-key`, `--ssl-ca-root`, `--ssl-ca-intermediate`
New database certificate + new CA	`--ssl-db-cert`, `--ssl-db-key`, `--ssl-db-ca-root`, `--ssl-db-ca-intermediate`
Changing CA only (same cert files, different CA chain)	`--ssl-ca-root`, `--ssl-ca-intermediate`, `--ssl-db-ca-root`, `--ssl-db-ca-intermediate`
Full replacement — new certs and CA for both components	See "All certificates from an external PKI" below

Any --ssl* flag not specified uses the corresponding value from the source server. Only provide flags for the files that differ from your current setup.

1.1.1. Flag reference

The following --ssl* flags are supported by mgradm migrate and mgradm upgrade:

Flag Description

Flag	Description
`--ssl-ca-root`	Path to the root CA certificate that signed the server certificate (defaults to source server CA)
`--ssl-ca-intermediate`	Path to an intermediate CA certificate in the chain (can be specified multiple times; defaults to source server)
`--ssl-server-cert`	Path to the server certificate (defaults to source server certificate)
`--ssl-server-key`	Path to the server private key (defaults to source server key)
`--ssl-db-ca-root`	Path to the root CA certificate that signed the database certificate
`--ssl-db-ca-intermediate`	Path to an intermediate CA certificate in the database certificate chain (can be specified multiple times)
`--ssl-db-cert`	Path to the database certificate
`--ssl-db-key`	Path to the database private key

--ssl-ca-root

Path to the root CA certificate that signed the server certificate (defaults to source server CA)

--ssl-ca-intermediate

Path to an intermediate CA certificate in the chain (can be specified multiple times; defaults to source server)

--ssl-server-cert

Path to the server certificate (defaults to source server certificate)

--ssl-server-key

Path to the server private key (defaults to source server key)

--ssl-db-ca-root

Path to the root CA certificate that signed the database certificate

--ssl-db-ca-intermediate

Path to an intermediate CA certificate in the database certificate chain (can be specified multiple times)

--ssl-db-cert

Path to the database certificate

--ssl-db-key

Path to the database private key

The database certificate chain is completely separate from the server certificate chain. The --ssl-db-* flags must be provided even when using the same CA, as the database container requires its own certificates generated during migration.

1.1.2. Certificate requirements

The following requirements apply to all certificate files used with mgradm migrate:

All certificate files must be in PEM format. If your certificates are in DER format, convert them first.
The hostname in the X509v3 Subject Alternative Name section of the certificate must match the fully qualified hostname of the machine the certificates are deployed on.
Database certificates require reportdb and db as Subject Alternative Name (SAN).
Supported key types are RSA and EC (Elliptic Curve).
When a CA chain is used, concatenate the certificates with the server or database certificate first, followed by all intermediate CA certificates in order. The root CA certificate should be provided in its own file. To combine files, you can use the following command:
```
cat server.pem intermediate-ca1.pem intermediate-ca2.pem > combined-server.pem
```

For full details on certificate preparation, see Import SSL Certificates.

1.1.3. Scenario: All certificates from an external PKI

This scenario covers migrating a server where both the web and database components use certificates from a third-party CA. The organization must gather the following certificate files:

Root CA certificate for the web component
Intermediate CA certificate for the web component (if applicable)
Server certificate for the web component
Private key for the web component
Root CA certificate for the database component
Intermediate CA certificate for the database component (if applicable)
Server certificate for the database component (with reportdb and db as SAN)
Private key for the database component

In most deployments, a single CA serves both the server and database components. In that case, the same certificate files are used for both --ssl- and --ssl-db- flags. The example below uses separate file names for clarity.

Listing 1. Example migration command with all --ssl* flags

mgradm upgrade podman <oldserver.fqdn> \
  --ssl-ca-root rootCAweb.pem \
  --ssl-ca-intermediate intermediateCAweb.pem \
  --ssl-server-cert webcert.pem \
  --ssl-server-key webkey.key \
  --ssl-db-ca-root rootCAdb.pem \
  --ssl-db-ca-intermediate intermediateCAdb.pem \
  --ssl-db-cert dbcert.pem \
  --ssl-db-key dbkey.key

Client deployment of external CA certificates

After a successful migration with external PKI certificates, deploy the CA certificate to all clients so they can verify the new server certificates:

mgrctl exec -- 'salt -b 50 * state.apply certs'

1.1.4. Scenario: Mixed external and self-signed certificates

When migrating with a mix of external and self-signed certificates, only replace the CA in a certificate chain when the server or database certificate and its private key are also being replaced in that same chain. For example, when replacing both the server certificate and key with external PKI versions, also provide the corresponding CA certificates. However, when only replacing database certificates, the self-signed CA password is still needed if the original CA is being reused.

For the complete procedure, see the SCC article: SUSE Multi-Linux Manager Server migration fails due to unknown (or lost) CA password.

SUSE Multi-Linux Manager 5.0 peripheral servers are always using third-party SSL certificates. If the hub server has generated the certificates for the peripheral server, it needs to generate the certificate for the peripheral database too. On the hub server, run the following command for each of the peripheral server to migrate.

mgrctl exec -ti -- rhn-ssl-tool --gen-server --dir="/root/ssl-build" --set-country="COUNTRY" \
  --set-state="STATE" --set-city="CITY" --set-org="ORGANIZATION" \
  --set-org-unit="ORGANIZATION UNIT" --set-email="name@example.com" \
  --set-hostname=<hostname>-reportdb --set-cname="example.com" --set-cname=db --set-cname=reportdb

The files to use will be inside the server container and need to be copied to the new peripheral server host:

/root/ssl-build/RHN-ORG-TRUSTED-SSL-CERT as the root CA,
/root/ssl-build/<hostname>-reportdb/server.crt as the db certificate and
/root/ssl-build/<hostname>-reportdb/server.key as the db certificate’s key.

2. Client tools rebranding

SUSE Multi-Linux Manager 5.1 introduces a rebranded set of client tools for all supported operating systems. This transition is seamless, and users performing a new product synchronization should only notice the updated channel names.

Channels named SUSE Manager Client Tools for XYZ, used by clients previously registered with SUSE Multi-Linux Manager 4.3 or 5.0, are no longer available in version 5.1 and will no longer receive updates in 5.1.

Although the legacy channels remain assigned to existing clients after migration, the corresponding repositories have been removed.

To ensure continued updates, users must:

Mirror the new SUSE Multi-Linux Manager Client Tools for XYZ channels for the relevant products and assign them to the appropriate clients.
Unassign the outdated SUSE Manager Client Tools for XYZ channels.

This also means that any CLM projects based on the old client tools must be adjusted accordingly.

For example workflow, see Switch to new client tools channels.

3. SLE Micro 5.5 to SL Micro 6.1

This document provides the tested procedure to upgrade a SLE Micro 5.5 host deployed with SUSE Multi-Linux Manager 5.0 Server to SL Micro 6.1 and migrate to SUSE Multi-Linux Manager 5.1.

3.1. Prerequisites

SUSE Multi-Linux Manager 5.0 is installed and running on SLE Micro 5.5.
System is registered and has active subscriptions with SCC.

3.2. Distribution upgrade and server migration

Procedure: Migration from SUSE Multi-Linux Manager 5.0 to SUSE Multi-Linux Manager 5.1

Verify current product status.
SUSEConnect --status-text
Confirm:

Base OS: SUSE Linux Enterprise Micro 5.5

Extension: SUSE Manager Server 5.0 Extension
Ensure the system is updated.
transactional-update patch
If patches were applied, stop the server and then reboot the system before proceeding to migration:
mgradm stop
reboot
If no updates were found, you can proceed directly to the migration step.
Start the migration.
transactional-update migration --auto-agree-with-licenses --gpg-auto-import-keys
Follow the prompts and select the available migration to SUSE Linux Micro 6.1 and SUSE Multi-Linux Manager Server Extension 5.1.
Stop the server and then reboot to apply changes.
mgradm stop
reboot
Perform post-reboot checks.

Verify upgraded OS and SUSE Multi-Linux Manager extension:
cat /etc/os-release
SUSEConnect --status-text
You should see:

PRETTY_NAME="SUSE Linux Micro 6.1"

SUSE Multi-Linux Manager Server 5.1 Extension
Enable root SSH access (if required).

SL Micro 6.1 disables root login via SSH by default.

Edit /etc/ssh/sshd_config.d/sshd.conf:
PermitRootLogin yes
And restart the service:
systemctl restart sshd
For more information, see Remote root login on SL Micro.
Verify SUSE Multi-Linux Manager tools
mgradm --version
Expected output:

Version 5.1.11 or higher

References 5.1.0 or higher
Upgrade server containers.

Risk of Automated Version Downgrade and PTF Loss

Running the mgradm upgrade podman command when no newer upgrade is available will cause the system to automatically revert to the base version. This process removes all currently applied Program Temporary Fixes (PTFs) without a confirmation prompt.

To avoid unintended data or fix loss, verify upgrade availability before execution. Future releases will include a confirmation prompt to prevent this behavior.
mgradm start
mgradm upgrade podman
Follow the prompts to pull and configure the new 5.1.0 containers.
Check the running containers:
podman ps
You should see:

server:5.1.0 or higher

server-postgresql:5.1.0 or higher

Errors for missing services like uyuni-db or saline during upgrade can be ignored if not installed previously.

3.3. Migration complete

The system is now running SUSE Multi-Linux Manager 5.1 on SL Micro 6.1. Validate your setup before resuming production operations. If you have a SUSE Multi-Linux Manager 5.0 proxy connected to this server, proceed to the Proxy Migration from 5.0 to 5.1 guide to upgrade the proxy host.

3.4. Database Backup Volume

Server migration or upgrade with mgradm migration or mgradm upgrade can create a volume with the database backup.

When the PostgreSQL database version is increased, the old database must be stored in a separate location before running the upgrade. For this purpose mgradm dynamically creates the volume var-pgsql-backup. When the migration or upgrade is done and the user has validated that the new system is working as expected, this volume can be removed safely.

4. SUSE Linux Enterprise Server 15 SP6 to 15 SP7

This document provides the tested procedure to upgrade a SUSE Linux Enterprise Server 15 SP6 host deployed with SUSE Multi-Linux Manager 5.0 Server to SUSE Linux Enterprise Server 15 SP7 with SUSE Multi-Linux Manager 5.1.

4.1. Prerequisites

SUSE Multi-Linux Manager 5.0 is installed and running on SUSE Linux Enterprise Server 15 SP6.
The system is registered and has valid subscriptions in SUSE Customer Center (SCC).
Ensure backups are created before proceeding.

4.2. Distribution upgrade and server migration

Procedure: Migration from SUSE Multi-Linux Manager 5.0 to SUSE Multi-Linux Manager 5.1

Verify current product status.
SUSEConnect --status-text
Confirm:

Base OS: SUSE Linux Enterprise Server 15 SP6

Extension: SUSE Manager Server 5.0 Extension
Apply all system patches.
zypper patch
Stop the server, and then reboot if the update stack was updated.
mgradm stop
reboot
Launch the Zypper migration tool.
zypper migration
Zypper will show the possible migration targets with detailed summaries.
Select the appropriate target, and follow the prompts to complete the migration.
After the migration completes, stop the server and then reboot the system.
mgradm stop
reboot
Perform post-reboot checks:

Verify upgraded OS and SUSE Multi-Linux Manager extension.
cat /etc/os-release
SUSEConnect --status-text
You should see:

VERSION="15-SP7"

SUSE Multi-Linux Manager Server 5.1 Extension for SLE
Verify SUSE Multi-Linux Manager tools version.
mgradm --version
Expected output:

Version 5.1.11 or higher

Image tag 5.1.0 or higher
Upgrade the server containers.

Risk of Automated Version Downgrade and PTF Loss

Running the mgradm upgrade podman command when no newer upgrade is available will cause the system to automatically revert to the base version. This process removes all currently applied Program Temporary Fixes (PTFs) without a confirmation prompt.

To avoid unintended data or fix loss, verify upgrade availability before execution. Future releases will include a confirmation prompt to prevent this behavior.
mgradm start
mgradm upgrade podman
Follow prompts to pull the new container images and reconfigure the environment.
Check the running containers.
podman ps
Expected containers:

server:5.1.0 or higher

server-postgresql:5.1.0 or higher

4.3. Migration complete

The system is now running SUSE Multi-Linux Manager 5.1 on SUSE Linux Enterprise Server 15 SP7. Validate your setup before resuming production operations. If you have a SUSE Multi-Linux Manager 5.0 proxy connected to this server, proceed with Proxy Migration from 5.0 to 5.1.

4.4. Database Backup Volume

Server migration or upgrade with mgradm migration or mgradm upgrade can create a volume with the database backup.