Special installation aspects (#358)

howtos.rst

@@ -13,6 +13,8 @@ How-tos & Guides
    howtos/15-3_to_15-4
    howtos/15-4_to_15-5
    howtos/15-5_to_15-6
+   installation/installer-howto
+   installation/special-install-scenarios-howto
    howtos/rpm_install
    howtos/v3_to_v4
    howtos/reinstall

installation/install.rst

@@ -15,6 +15,7 @@ that we have a :ref:`pre_install`.
    quickstart
    pre-install-howto
    installer-howto
+   special-install-scenarios-howto
 
 .. _quickeval:
 

installation/installer-howto.rst

@@ -9,12 +9,12 @@ Thanks
 ------
 
 Rockstor’s developers would like to thank the entire OSS community for making
-any of this possible. Specifically with our recent move / rebase on openSUSE
-Leap, our thanks go to the openSUSE/SuSE organisations and the larger
-community for the extreme generosity we all benefit from in a myriad of seen
-and unseen ways.
+any of this possible.
+Specifically with our recent move / rebase on openSUSE Leap, our thanks go to
+the openSUSE/SuSE organisations and the larger community for the extreme
+generosity we all benefit from in a myriad of seen and unseen ways.
 
-**Please note: Rockstor is in no way affiliated with openSUSE / SuSE and does
+**Please note: Rockstor is in no way affiliated with openSUSE/SuSE and does
 not wish, under any circumstances, to misrepresent these organisations.**
 *Any errors you encounter are most likely our fault and we try, on a current
 volunteer basis, to support our users via our*
@@ -23,13 +23,14 @@ volunteer basis, to support our users via our*
 It is hoped that Rockstor’s ongoing small contribution back to the larger
 community is of value, and if this is so for you please consider either
 subscribing to our Stable Channel updates or taking part in our developer
-orientated Testing Channel. Details of these Rockstor package update services
-are available in our subsection on :ref:`update_channels`. Rockstor’s ongoing
-development is wholly dependent on community support via either of these
-channels and by positively participating in our forum, linked above. It is
-hoped that in time we can contribute back more significantly, and possibly
-financially, as our own community and Stable Channel subscriptions grow. Also
-note that irrespective of Rockstor update channel selection or otherwise,
+orientated Testing Channel.
+Details of these Rockstor package update services are available in our
+subsection on :ref:`update_channels`. Rockstor’s ongoing development is wholly
+dependent on community support via either of these channels and by positively
+participating in our forum, linked above.
+It is hoped that in time we can contribute back more significantly, and possibly
+financially, as our own community and Stable Channel subscriptions grow.
+Also note that irrespective of Rockstor update channel selection or otherwise,
 upstream updates are available by normal command line means and via our Web-UI.
 See :ref:`dash_and_updates` later in this guide for the details.
 
@@ -39,13 +40,13 @@ Our "Built on openSUSE" Kiwi-ng created installer
 -------------------------------------------------
 
 The existence of this installer, and those of many Linux distributions, is down
-in a major part to the Kiwi installer creation tool. I would specifically like
-to thank `Marcus Schafer <https://github.com/schaefi>`_ and David
-`Cassany Viladomat <https://github.com/davidcassany>`_ of openSUSE/SuSE for
+in a major part to the Kiwi installer creation tool.
+I would specifically like to thank `Marcus Schafer <https://github.com/schaefi>`_
+and David `Cassany Viladomat <https://github.com/davidcassany>`_ of openSUSE/SuSE for
 their timely and rapid oem, partition, swap, and btrfs related fixes that were
-required for our initial version of this installer. Please contribute to this
-important multi-distribution upstream project if you have the means and/or
-talent `KIWI - Next Generation <https://github.com/OSInside/kiwi>`_.
+required for our initial version of this installer.
+Please contribute to this important multi-distribution upstream project if you have
+the means and/or talent `KIWI - Next Generation <https://github.com/OSInside/kiwi>`_.
 
 Initial Selection Screen
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -74,14 +75,14 @@ If unsure do not proceed and select <Cancel> via Tab key and then Enter.
    :align: center
 
 Use cursor keys to highlight, then the "Enter" key to select.
-Only devices less than 5000 GB (5 TB) are shown. Larger disks are assumed to be data
-disks.
+Only devices less than 5000 GB (5 TB) are shown.
+Larger disks are assumed to be data disks.
 
 Destroying ALL data on ..., continue ?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Do not proceed if at all unsure. This will wipe the entire contents of the
-indicated drive.
+Do not proceed if at all unsure.
+This will wipe the entire contents of the indicated drive.
 
 .. image:: /images/installation/installer-howto/destroy-all-data.png
    :width: 100%
@@ -132,7 +133,8 @@ The included **rockstor** package is :ref:`rockstor_license`
    :align: center
 
 Use cursor keys or Page-up / Page-down (space bar) to view the entire
-agreement. There are about 3 pages: Enter key to 'Exit' & 'Agree', or cursor
+agreement.
+There are about 3 pages: Enter key to 'Exit' & 'Agree', or cursor
 keys to select 'No' in pop up.
 
 Select Time Zone
@@ -229,8 +231,8 @@ Welcome banner
 ^^^^^^^^^^^^^^
 
 Directly after the initial Rockstor setup the following welcome banner
-introduces the Rockstor package Update Channels. A link to our documentation
-explaining these channels is included:
+introduces the Rockstor package Update Channels.
+A link to our documentation explaining these channels is included:
 
 .. image:: /images/installation/installer-howto/initial_welcome_banner.png
    :align: center
@@ -270,3 +272,8 @@ See our FAQ entry: :ref:`faq_rockstor4_repos`
 
 **NOTE: No Rockstor package update repository is configured until an
 Update Channel is selected.**
+
+
+.. note::
+
+   For advanced installation scenarios see: :ref:`special_install_scenarios`.

installation/special-install-scenarios-howto.rst

@@ -0,0 +1,102 @@
+.. _special_install_scenarios:
+
+Special Installation Scenarios
+==============================
+
+Since Rockstor can accommodate a wide range of hardware configurations, as well
+as virtual machine set ups, there have been instances reported over the years that
+required some specific actions to enable setting up Rockstor on a new system.
+While the friendly `Rockstor forum <https://forum.rockstor.com>`_ contains many more
+scenarios and resolutions that can be searched for, some recurring themes are
+documented below:
+
+Assign static IP address after installation but before WebUI setup
+------------------------------------------------------------------
+
+.. note::
+   The below is meant for setting up a specific connection **before** the installation/configuration is 
+   completed using Rockstor's WebUI.
+   Under most circumstances this should not be necessary, as most routers today offer IP address reservation 
+   that will effectively result in a static IP address assigned to the Rockstor appliance 
+   (which by default uses `DHCP` to automatically obtain an IP address from the gateway).
+
+If during setup the network architecture requires a static IP address on the Rockstor appliance's
+network interface :code:`Network Manager` can be used to force a static IP address on the network interface.
+
+Check Network connection using the command line:
+
+.. code-block:: console
+
+    Rockstorsys:~$ nmcli connection show
+    NAME     UUID                                  TYPE      DEVICE
+    enp0s3   aa44c29f-33e8-358f-879b-e0b8efae27f3  ethernet  enp0s3
+
+In order to make this a static connection, here is an example on how this can be set up using `nmcli`:
+
+.. code-block:: console
+
+   nmcli connection modify 'enp0s3' \
+      connection.autoconnect  yes \
+      ipv4.method manual \
+      ipv4.address 192.168.22.199/24 \
+      ipv4.gateway 192.168.22.1 \
+      ipv4.dns 8.8.8.8, 8.8.4.4.
+
+Upon successful completion of the command the connection will receive a static IP address:
+
+* automatically (i.e. whenever the network management is started)
+* static address with
+* IP address of 192.168.22.199 and
+* Gateway of 192.168.22.1 and
+* DNS1 and DNS2 server 8.8.8.8 and 8.8.4.4 respectively.
+
+To move the connection back to `DHCP` mode, the above settings need to be reverted:
+
+.. code-block:: console
+
+   nmcli con mod "enp0s3" \
+     ipv4.method "auto"
+     ipv4.addresses "" \
+     ipv4.gateway "" \
+     ipv4.dns ""
+
+For either of these changes to take effect run
+
+.. code-block:: console
+
+   nmcli connection up "enp0s3"
+
+or reboot the system.
+
+
+Proxy for private network
+-------------------------
+
+In some network architectures, a proxy is required to be able to manage updates from external sources
+like OpenSUSE upstream packages, or to check for and update to a new version of the `rockstor` package.
+
+This `KB 7006845 <https://www.suse.com/support/kb/doc/?id=000017441>`_ provides some insights into how
+to set up a Proxy using the command line.
+
+VMWare guest tools installation
+-------------------------------
+
+When running Rockstor as a VMWare guest (unsupported),
+consider using **open-vm-tools** to help with various aspects of the host/guest integration.
+Similar guest extensions exist for VirtualBox.
+
+This or any package can be included into a custom installer, making them available during the initial installation.
+For building a custom installer see our `rockstor-installer <https://github.com/rockstor/rockstor-installer>`_ repo.
+The `open-vm-tools` package is already contained in the **rockstor.kiwi** file, albeit commented out.
+
+.. note::
+
+   This is intended for more advanced users that are comfortable creating their own installers with custom content.
+
+To install the package after Rockstor has already been installed on a VMWare Guest instance, go to the command line and run:
+
+.. code:: console
+
+   zypper install open-vm-tools
+
+Subsequent updates to the package will be automatically considered during Rockstor's upstream package checks.