Add Branch Server 4.3 to 5.1 migration guide

Author: aaannz

modules/ROOT/pages/_partials/entities.adoc

@@ -21,6 +21,7 @@
 :kickstart: Kickstart
 :productname:
 :productproxy: {productname} Proxy
+:productbranch: {productname} Branch Server Proxy
 :susemgr: SUSE Manager
 :smr: for Retail
 :uyuni: Uyuni
@@ -87,6 +88,7 @@
 :question: icon:question[role="gray"]
 :star: icon:asterisk[role="none"]
 :salt: Salt
+:saltboot: Saltboot
 :trad: Traditional
 :snippet: `../../modules/ROOT/pages/snippets/`
 

modules/installation-and-upgrade/pages/container-deployment/mlm/migrations/proxy/proxy-mlm-43-51.adoc

@@ -16,15 +16,23 @@ This section describes migrating from Proxy 4.3 using the [command]``mgrpxy`` to
 
 [IMPORTANT]
 ====
-An in-place migration from {productname} 4.3 to {productnumber} is unsupported.
-The host operating system has changed from {sles} 15 SP4 to {sl-micro} {microversion} or {sles} {bci-mlm}.
+An in-place migration from {productname} 4.3 to {productnumber} will change the host operating system from {sles} 15 SP4 to {sl-micro} {microversion} or {sles} {bci-mlm}.
+====
 
+[IMPORTANT]
+====
 The traditional contact protocol is no longer supported in {productname} 5.0 and later.
 Before migrating from {productname} 4.3 to {productnumber}, any existing traditional clients including the traditional proxies must be migrated to {salt}.
 
 For more information about migrating to {salt} clients, see https://documentation.suse.com/suma/4.3/en/suse-manager/client-configuration/contact-methods-migrate-traditional.html
 ====
 
+== Migration workflow overview
+
+//TODO add workflow picture
+
+== Backup existing {productproxy} data
+
 
 
 == Deploy a New {productname} Proxy

modules/retail/pages/migration-from-43.adoc

@@ -0,0 +1,88 @@
+[[retail-migration-from-43]]
+= Migrating from {productbranch} 4.3
+:revdate: 2025-11-12
+:page-revdate: {revdate}
+
+This guide describes a procedure how to migrate one or more {productbranch} Servers from {susemgr} Branch Server 4.3 to the {productbranch} 5.1
+
+== Overview
+
+* Synchronize {productbranch} channels
+* Backup existing {productname} {smr} 4.3 Branch Server Proxy
+* Validate branch objects were created
+* Migrate Branch Server Proxy host
+* Validate proxy functionality
+
+== Backup existing {productbranch} 4.3
+
+{productname} {smr} 5.1.2 includes automated backup-migration procedure for both kinds of {productproxy} variants. This procedure collects all required data and uploads them to the {productname} Server. For {productbranch} this tool also creates and migrates {saltboot} related entities.
+
+There are multiple ways how to initiate {productbranch} 4.3 migration:
+
+* API call [literal]``mgrctl api post proxy.backup id=$proxyid``
+* {salt} call [literal]``salt $proxy proxy.backup``
+
+[IMPORTANT]
+====
+{productbranch} can still be used after backup step as before, however because some formulas were disabled by the backup/migration step, next highstate or image-sync state application will not work properly.
+
+Migrate the server host as soon as possible after backup step is performed.
+====
+
+== Validate branch objects were created for migrated branches
+
+Backup/migration step will create new Saltboot objects:
+
+- [literal]``Saltboot Group`` formula with settings from the original formulas is assigned to the branch group.
+- New cobbler profile is created for the branch group:
++
+[code]
+====
+# mgrctl exec -- cobbler profile report --name $branchid:S:$orgid:$orgname
+====
+- New cobbler systems are created for all assigned terminals:
++
+[code]
+====
+# mgrctl exec -- cobbler system find --kernel-options "MINION_ID_PREFIX=$branchid"
+====
+
+== Migrate {productbranch} host
+
+Create and use AutoYAST profiles to migrate or reinstall proxy host.
+
+=== Prepare autoinstallation distribution based on {sles} 15 SP7
+
+- Download or obtain {sles} 15 SP7 installation ISO to the server host
+- Use [literal]``mgradm distribution copy $path_to_the_iso`` to copy installation files to the container
+- Register the autoinstallation distribution, see see xref:client-configuration:autoinst-distributions.adoc[].
+
+=== Prepare autoinstallation profile
+
+For more information, see xref:client-configuration:autoinst-profiles.adoc[].
+
+- Create an autoinstallation profile based previously created distribution.
+As a profile use profile provided at https://github.com/SUSE/manager-build-profiles/blob/master/AutoYaST/SUSE%20Multi-Linux%20Manager%20Proxy/MLM_RBS-51-SLES-Upgrade.xml
+- Once profile is created, switch to [menuitem]``Variables`` tab and fill in required variables:
++
+[code]
+====
+org='organization_id'
+distrotree='autoinstallation_distribution_label_from_previous_step'
+channel_prefix='clm_channel_prefix' or blank for SCC channels
+registration_key='activation_key_for_post_upgrade'
+====
+- In tab [menuitem]``Autoinstallation File`` you can see complete rendered profile for additional inspection
+
+=== Provision autoinstallation of the proxy
+
+Schedule an autoinstallation on the old {susemgr} Branch Server 4.3 using the profile created in previous step.
+
+- Use Web UI interface [menuitem]``Provisioning`` tab at the [menuitem]``System`` view of migrating branch server
+// TODO add API call option
+
+== Validate proxy functionality
+
+After migration is finished and salt is started first time, backed up proxy configuration is automatically deployed during [literal]``Hardware refresh`` step.
+
+After finishing all onboarding steps, validate required proxy functionality

modules/retail/pages/retail-components.adoc

@@ -92,7 +92,9 @@ You can use default settings for formulas, or edit them to make them more specif
 
 For more information about formulas, see xref:retail:retail-formulas-intro.adoc[].
 
+=== Cobbler
 
+{productname} {smr} uses Cobbler to manage and prepare boot configuration for the POS terminals.
 
 === {saltboot}
 

modules/retail/pages/retail-install-setup.adoc

@@ -59,11 +59,11 @@ After POS image is successfully built and inspected by {productname}, you can va
 ----
 mgrctl exec cobbler distro list
 ----
-. Your POS image should be listed with organization number before image name
+. Your POS image should be listed with an organization name appended after it.
 
 == Branch Identification
 
-For every branch server choose [systemitem]``branch id``.
+For every branch server choose its [systemitem]``branch id``.
 
 As a [systemitem]``branch id`` select any alphanumerical string with up to 64 characters.
 
@@ -94,7 +94,7 @@ Navigate to menu:Systems[System Groups] and click btn:[Create System Group].
 
 For more information about system groups, see xref:reference:systems/system-groups.adoc[].
 
-During terminal bootstrap terminal automatically joins:
+During terminal bootstrap, terminal automatically joins:
 
 - branch system group based on received [systemitem]``branch_id``. This will make branch group formulas available to the terminal.
 - HWType group based on SMBios information received from terminal. This will make {saltboot} partitioning pillar available to the terminal.
@@ -156,7 +156,7 @@ For this to work [systemitem]``DHCP`` service for the network terminal is connec
        next-server <IP address of branch server proxy>;
     }
     else {
-      filename "pxelinux.0";
+      filename "grub/grub.0";
       next-server <IP address of branch server proxy>;
     }
   }

modules/retail/pages/retail-network-arch.adoc

@@ -51,7 +51,7 @@ In this configuration, external routers provide DHCP and DNS services to the bra
 image::retail_external_network.png[scaledwidth=60%]
 
 
-=== Dedicated Network Architecture (using 4.3 branch server)
+=== Dedicated Network Architecture
 The branch servers are in the same network as the {productname} Server, and terminals use an isolated branch network.
 In this configuration, the branch servers are in the corporate network, and provide all DHCP, DNS, PXE, HTTP and TFTP services to the terminals in the branch networks.