Merge pull request #510 from phillxnet/509-Minor-tidy-re-use-of-'open…

…SUSE'

Minor tidy re use of 'openSUSE' #509

howtos/centos_to_opensuse.rst

@@ -1,19 +1,25 @@
 .. _centos_to_opensuse:
 
-Migrating from Legacy V3 on CentOS to "Built on openSUSE" versions
-==================================================================
+Migrating Legacy v3 (CentOS) to "Built on openSUSE"
+===================================================
 
 Rockstor v3 was based on CentOS 7 and is no longer supported.
 Last updates per channel:
 
 - Stable (3.9.2-57) - April 2020
 - Testing (3.9.1-16) - November 2017
 
-Starting with v4, openSUSE has become the basis for the Rockstor appliance.
-Our `downloadable <https://rockstor.com/dls.html>`_ installers aim to have the most
-recent Stable channel release pre-installed.
-Below is a non-exhaustive list of notes, recommendations and warnings for those planning on
-going through the upgrade process.
+*Starting with v4, Rockstor is "Built on openSUSE".*
+See: `openSUSE:Trademark guidelines <https://en.opensuse.org/openSUSE:Trademark_guidelines>`_.
+
+Our `downloadable <https://rockstor.com/dls.html>`_ installers aim to have late stable release candidate (RC),
+or first published stable channel 'rockstor' packages pre-installed.
+Below is a non-exhaustive list of notes,
+recommendations,
+and warnings for those planning on going through the upgrade process.
+
+Migration overview
+------------------
 
 .. note::
 
@@ -27,10 +33,11 @@ going through the upgrade process.
 
 .. note::
 
-    In the openSUSE versions the system pool is auto-labeled as "ROOT" in line with the JeOS upstream.
-    Prior to v4, installs use the label "rockstor_rockstor".
-    Starting with v4 the inadvertent (as seen in v3) appearance of the "root"
-    share (subvolume) has also been removed .
+    As from 5.0.9 "Built on openSUSE" versions no longer auto-import the system pool.
+    This is intended to discourage the use of the system Pool for data storage.
+    But when imported (advanced users only) this pool is labeled "ROOT".
+    Prior to v4 the system Pool was labeled "rockstor_rockstor".
+    Starting with v4 the inadvertent appearance of the "root" share/subvolume has also been removed.
 
 .. warning::
 
@@ -57,13 +64,13 @@ then copy it to a dedicated data pool share first.
 Ideally one with redundancy.
 It is always best to avoid creating and using shares on the system disk.
 There is currently no redundancy options btrfs-wise and it complicates re-install,
-or major updates such as this one with moving from CentOS to openSUSE versions.
+or major updates such as this one with moving from CentOS to "Built on openSUSE" versions.
 Try to avoid this in the future.
 
 .. _rockons_root_on_system:
 
-Rock-ons 'root' on system disk
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Rock-ons root on system disk
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 One common pragmatic setup in small to medium-sized Rockstor installs
 is the use of the system pool for the :ref:`rockons_root` share.
@@ -81,12 +88,11 @@ recreating the Rock-ons root share after upgrade.
 Use a new system disk
 ---------------------
 
-If at all possible it is highly advisable to install the new openSUSE-based version onto
-a fresh system disk.
+It is highly advisable to install the "Built on openSUSE" version onto a fresh system disk.
 This leaves open the possibility of re-attaching the old v3 system disk in case of any difficulties.
-Do not leave an old v3 system disk attached while installing a new openSUSE version, unless of course,
-the same system disk is reused (not advised but entirely possible).
-An openSUSE version install is significantly faster and simpler than a v3 install,
+Do not leave an old v3 system disk attached while installing a "Built on openSUSE" version;
+unless the same system disk is reused (not advised but entirely possible).
+The :ref:`installer_howto` is significantly faster and simpler than a v3 install,
 but will destroy all data on the target disk.
 Hence the advise here to preserve the original system disk and to detach it prior to the new install.
 
@@ -102,58 +108,67 @@ Hence the advise here to preserve the original system disk and to detach it prio
 Disconnect all Data disks
 -------------------------
 
-As a purely precautionary measure, it is highly advisable that all data disks be detached
-prior to the new install.
+As a purely precautionary measure,
+it is highly advisable that all data disks be detached prior to the new install.
 Take careful note of their connections to the host system.
 This connection concern relates to potential hardware compatibility of these interconnects.
-Btrfs, our underlying file system and device manager, is not normally concerned with such changes,
-but the existing hardware pairings, assuming prior function, are best noted nevertheless.
-Just in case, after the last shutdown of v3, while attaching the new system disk,
+Btrfs,
+our underlying file system and device manager,
+is not normally concerned with such changes,
+but the existing hardware pairings,
+assuming prior function,
+are best noted nevertheless.
+Just in case,
+after the last shutdown of v3,
+while attaching the new system disk,
 be sure to unplug all prior disks.
-This is simply to avoid an accidental selection of a data pool member for the fresh install.
+This is simply to avoid an accidental selection of a data pool member for the fresh installs' system disk.
 
-.. warning::
+.. _migration_openSUSE_installer:
 
-    As stated above, the new openSUSE install will wipe all prior data on the target disk selected.
-    A simple quick mistake at the initial :ref:`installer_select_disk` step could inadvertently
-    destroy a pool member's data.
+Revised Installer
+-----------------
 
-.. _openSUSE_installer:
+See :ref:`installer_howto` for a step-by-step explanation and guide.
 
-OpenSUSE Installer
-------------------
+.. warning::
 
-See :ref:`installer_howto` for a step-by-step explanation and guide.
-And again, great care should be taken on the early :ref:`installer_select_disk` (intended target system disk)
-choice.
-If the above advise is followed, there will only be one newly attached proposed system disk anyway.
+    The :ref:`installer_howto` will wipe all prior data on the target disk selected.
+    A simple quick mistake at the initial :ref:`installer_select_disk` step could inadvertently destroy a pool member's data.
 
-Once the new install is in place, it is advisable to apply all upstream updates.
+If the prior :ref:`disconnect_data_disks` section's advise is followed,
+there will only be one attached proposed system disk anyway.
+
+Once the new install is in place,
+it is advisable to apply all upstream updates.
 See: :ref:`updaterockstorwebui`.
 Take care to ensure these have all been applied prior to rebooting.
 The Dashboard can help to determine this by observing the network and CPU activity.
 *There is an outstanding bug where our 'wifi-like' busy indicator does not last the duration of the installs.*
 
-Ensure that the system does reboot and return as expected before re-attaching all prior pool members,
-connected as before, perform the pool import and then optionally a config restore.
-
+Ensure that the system reboots and returns as expected before re-attaching all prior data Pool/s members.
+Be sure to re-connected prior Pool members as before,
+prior to Pool/s import.
+And only attempt config restore after having successfully imported any prior data Pools.
 
 .. _openSUSE_import_notes:
 
-OpenSUSE versions Pool/s import
--------------------------------
+V3 Pool/s import
+----------------
 
-Under the OpenSUSE version, the Pool import is performed the same as under v3, initiated via the :ref:`disks` overview page.
+The newer Pool import feature,
+although improved,
+is compatible with importing Pools created under a v3 (and earlier) Rockstor version.
 See: :ref:`import_data`.
 
 .. warning::
 
     See also :ref:`btrfsunwellimport` in case a pool requires special mount options.
 
-OpenSUSE versions config restore
---------------------------------
+V3 Config save files
+--------------------
 
-Under openSUSE versions, the config restore is as per v3. See: :ref:`config_backup`.
+"Built on openSUSE" versions can restore v3 config saves. See: :ref:`config_backup`.
 
 .. note::
 
@@ -176,34 +191,37 @@ Many bug fixes
 ^^^^^^^^^^^^^^
 
 In the process of moving from a CentOS base to a "Built on openSUSE" one,
-the developers have found and fixed a large number of bugs, and inherited such things as our
+the developers have found and fixed a large number of bugs,
+and inherited such things as our
 `Rockstor 4 Installer Recipe <https://github.com/rockstor/rockstor-installer>`_
 that trivially enables highly customised installer creation.
-Also, there is now ARM64 (e.g. Pi4/Ten64) compatibility, baring some Rock-ons,
+There is also now ARM64 (e.g. Pi4/Ten64) compatibility,
+baring some Rock-ons,
 courtesy of openSUSE's extreme heritage in ARM support.
 
-Also note the following, Rockstor has moved past the `Jump <https://en.opensuse.org/Portal:Jump>`_
-initiative:
+Also note the following,
+Rockstor has moved past the `Jump <https://en.opensuse.org/Portal:Jump>`_ initiative:
 
 - In v3 the upstream of CentOS had in turn its upstream of RedHat's RHEL.
 - openSUSE has in turn its binary compatible upstream of SuSE SLES.
 
-So, if the prior v3 install has a customization involving a CentOS/RHEL compatibility, that should
-also be used on the openSUSE based version, check first for an openSUSE equivalent and then
-for a SLES equivalent (note that sometimes packages are not named exactly the same, so it might
-require some detective work to find the matching package to install).
-This most likely only affects advanced users and should not be a concern when using Rocksto's
-built-in capabilities.
+If the prior v3 install has a customization involving a CentOS/RHEL compatibility,
+that should also be used on the "Built on openSUSE" version,
+check first for an openSUSE equivalent,
+and then for a SLES equivalent.
+Note that often packages are named differently between linux distributions,
+so it may require some detective work to find the matching package to install.
+This most likely only affects advanced users and should not be a concern when using Rockstor's built-in capabilities.
 
 
 .. _Users_default_groups:
 
 Users and default group
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Since the underlying OS has changed between v3 and v4 onwards, there are other more subtle
-differences that may only come to light in time.
+Since the underlying OS has changed between v3 and v4 onwards,
+there are other more subtle differences that may only come to light in time.
 One such difference is the default use of the "users" group in openSUSE for newly added users.
 Our prior CentOS base defaulted to individual user group creation named after the user concerned.
-It is thought that the newer default is more suited to a shared resource, though this difference
-may come as a surprise to prior v3 administrators.
+It is thought that the newer default is more suited to a shared resource,
+though this difference may come as a surprise to prior v3 administrators.