Distribution update from 15.4 to 15.5 - howto #467

Based on our existing 15.3 to 15.4 distribution update How-to.
Includes version revisions, and the addition of the OpenH264 repo.
Additionally we now specify a minimum Rockstor version prior to
embarking on this distribution update.

howtos.rst

@@ -8,6 +8,7 @@ How-tos & Guides
    howtos/stable_kernel_backport
    howtos/15-2_to_15-3
    howtos/15-3_to_15-4
+   howtos/15-4_to_15-5
    howtos/rpm_install
    howtos/v3_to_v4
    howtos/reinstall

howtos/15-4_to_15-5.rst

@@ -0,0 +1,170 @@
+.. _154_to_155:
+
+Distribution update from 15.4 to 15.5
+=====================================
+
+Rockstor installs "Build on openSUSE" Leap 15.4 - **End of Life (EOL) December 2023** - should be *distribution updated*.
+This How-to includes instruction on moving an existing 15.4 based install over, **in-place**,
+to the next major version of our base OS.
+Only one major version jump must be attempted at any one time.
+If your Rockstor install is not based on 15.4, consider one of our other "Distribution update ..." How-tos.
+
+- **A minimum Rockstor version of 5.0.9-0 is recommended before attempting this OS update.**
+
+.. note::
+
+    There are always less unknowns for fresh installs.
+    It is advisable to consider a fresh-start via the latest **Recommended** Rockstor installer.
+    See `Downloads <https://rockstor.com/dls.html>`_ for the available options.
+    See also our :ref:`installer_howto`.
+
+    Existing :ref:`pools` and :ref:`config_backup` files remain compatible and importable.
+
+.. warning::
+
+    For both **in-place** and **re-install/import** approaches; always ensure all backups are refreshed.
+    For re-install/import all data on a re-used system disk ('ROOT' Pool) will be irreversibly destroyed.
+    Alternatively use a fresh system disk to provide a fail over of reverting to the original system disk.
+    Do not attach both old and new system disks simultaneously.
+    Only one Rockstor system disk must be attached at any one time.
+
+Before attempting an **in-place** distribution update, be sure that you have applied all regular updates first.
+The :ref:`updating_rockstor` section covers how to do this either via the Web-UI or via the command line.
+
+.. _154_155-overview:
+
+Overview
+--------
+
+This **Distribution Update** procedure is well established in our upstream base OS of openSUSE Leap.
+Below we detail the following steps, each in their own sections:
+
+- Add OpenH264 repo
+- Update repositories
+- Distribution update
+- Reporting issues
+
+See our FAQ entry :ref:`faq_rockstor4_repos` for more context.
+
+.. _154_155-open-h264:
+
+Add OpenH264 repo
+-----------------
+
+As from openSUSE Leap 15.5 there is a default repository to provide
+`Open H264 capabilities <https://news.opensuse.org/2023/01/24/opensuse-simplifies-codec-install>`_.
+Our general policy is to stick as closely as we are able to upstream, with the intention to avoid deviation.
+As such we similarly adopt this newly default Open H264 repo, to account for newer packages assuming its existence.
+
+.. code-block:: console
+
+    zypper --non-interactive addrepo --refresh http://codecs.opensuse.org/openh264/openSUSE_Leap repo-openh264
+
+.. _154_155-update_repos:
+
+Update repositories
+-------------------
+
+Here we stream edit/replace all :code:`15.4` and :code:`15_4` instances with :code:`15.5` and :code:`15_5` respectively via:
+
+.. code-block:: console
+
+    sed -i 's/15_4/15_5/g' /etc/zypp/repos.d/*.repo
+    sed -i 's/15\.4/15\.5/g' /etc/zypp/repos.d/*.repo
+
+.. note::
+
+    This does not change the repository configuration file names themselves.
+    This is not important and can serve as an indicator of a system's history/origin.
+    The filenames for these repositories are cosmetic only.
+
+.. _154_155-distro-update:
+
+Distribution update
+-------------------
+
+**Double check all repositories are as-expected.**
+The following command should output a very similar list of repositories to those indicated.
+:ref:`Rockstor-Testing <testing_channel>` may be replaced by :ref:`Rockstor-Stable <stable_channel>`, or neither may be present;
+depending on your :ref:`update channel selection <update_channels>`
+
+.. code-block:: console
+
+    zypper --releasever=15.5 lr -U
+
+    Warning: Enforced setting: $releasever=15.5
+    Repository priorities in effect:                                                                                                                                                                (See 'zypper lr -P' for details)
+          97 (raised priority)  :  1 repository
+          99 (default priority) :  6 repositories
+         105 (lowered priority) :  1 repository
+
+    #  | Alias                              | Name                                                         | Enabled | GPG Check | Refresh | URI
+    ---+------------------------------------+--------------------------------------------------------------+---------+-----------+---------+----------------------------------------------------------------------------------------
+     8 | repo-openh264                      | repo-openh264                                                | Yes     | ( p) Yes  | Yes     | http://codecs.opensuse.org/openh264/openSUSE_Leap
+     9 | repo-sle-debug-update              | Update repository with debuginfo for updates from SUSE Lin-> | No      | ----      | ----    | http://download.opensuse.org/debug/update/leap/15.5/sle/
+     1 | Leap_15_5                          | Leap_15_5                                                    | Yes     | ( p) Yes  | Yes     | http://download.opensuse.org/distribution/leap/15.5/repo/oss/
+     7 | repo-backports-update              | Update repository of openSUSE Backports                      | Yes     | (r ) Yes  | Yes     | http://download.opensuse.org/update/leap/15.5/backports/
+     6 | repo-backports-debug-update        | Update repository with updates for openSUSE Leap debuginfo-> | No      | ----      | ----    | http://download.opensuse.org/update/leap/15.5/backports_debug/
+    10 | repo-sle-update                    | Update repository with updates from SUSE Linux Enterprise 15 | Yes     | (r ) Yes  | Yes     | http://download.opensuse.org/update/leap/15.5/sle/
+     3 | Rockstor-Testing                   | Rockstor-Testing                                             | Yes     | (r ) Yes  | Yes     | http://updates.rockstor.com:8999/rockstor-testing/leap/15.5
+     4 | home_rockstor                      | home_rockstor                                                | Yes     | (r ) Yes  | Yes     | https://download.opensuse.org/repositories/home:/rockstor/15.5/
+     5 | home_rockstor_branches_Base_System | home_rockstor_branches_Base_System                           | Yes     | (r ) Yes  | Yes     | https://download.opensuse.org/repositories/home:/rockstor:/branches:/Base:/System/15.5/
+     2 | Leap_15_5_Updates                  | Leap_15_5_Updates                                            | Yes     | ( p) Yes  | Yes     | https://download.opensuse.org/update/leap/15.5/oss/
+
+Before the big **Distribution Update**
+we must import all the new repository keys and information from all of the changes made above.
+
+.. code-block:: console
+
+    zypper --releasever=15.5 --non-interactive --gpg-auto-import-keys refresh
+
+And finally the actual base OS update itself.
+Here we instruct zypper to download all packages first.
+This helps to avoid a download failure part-way through this rather sensitive process.
+
+.. code-block:: console
+
+    zypper --releasever=15.5 dup --download-in-advance --allow-vendor-change --no-recommends
+
+We use --allow-vendor-change as some prior openSUSE packages are now supplied directly from SuSE.
+The --no-recommends is to keep to our JeOS (Just enough Operating System) `minimal` origin.
+I.e. don't install things like manuals etc and other 'extra' packages.
+
+The download size plus the extra disk space required will be around 600 MiB.
+So ensure that you have at least 2 GB free on your system disk ('ROOT' Pool), before proceeding.
+
+.. note::
+
+    As we are changing the legs upon which the entire system is running,
+    it is best to have the system under as minimal load as possible.
+    As such it is advisable to close any Rockstor Web-UI browser tabs during this process.
+
+.. warning::
+
+    It is imperative that the system is not rebooted during this process.
+    It is also important to reboot the system after the above
+    "zypper ... dup ..." command has completed.
+    This enables the new legs to be the ones running the show.
+    **Upstream reference**:
+    `SDB:System upgrade to Leap 15.5 <https://en.opensuse.org/SDB:System_upgrade_to_Leap_15.5>`_
+
+To reboot from the command line once the above "zypper ... dup ..." command has finished,
+enter the following commands as root:
+
+.. code-block::
+
+    sync
+    reboot
+
+.. _154_155-report:
+
+Reporting issues
+----------------
+
+As always we welcome feedback to improve what we do.
+So please consider reporting your experience or suggestions on our friendly
+`Community Forum <https://forum.rockstor.com/>`_.
+
+A distribution update is in many ways more complex than an entirely fresh install.
+And given Rockstor's overall size a re-install can be very quick.
+But if you have a complex install an in-place distribution update can be the way to go.