refactor password reset

howtos/reset-root-password-v3.rst

@@ -0,0 +1,86 @@
+
+.. _rootpwreset_legacy:
+
+Resetting root password on Rockstor Legacy V3.x
+===============================================
+
+.. warning::
+   Rockstor version 3.x built on CentOS has been deprecated. Please see
+   :ref:`rootpwreset` for the newer version of this document based on
+   OpenSUSE.
+
+The **root** user is created during Rockstor OS install. You may remember setting root
+password in one of the install screens. After a while, it's possible that you
+forgot the password and would like to reset it. To do that is a straight
+forward process as described in this howto.
+
+
+Step 1: Boot up with install CD/DVD/USB-drive
+---------------------------------------------
+
+Resetting password requires shutting down the system and booting it up with
+Rockstor install CD/DVD or USB-drive as you have done it during install. If you
+are unsure, see :ref:`osinstall`.
+
+On the splash screen, scroll down to **Troubleshooting** and hit enter to go to
+the Troubleshooting screen.
+
+.. image:: /images/howtos/reset-root-password/splash_screen.png
+   :scale: 80%
+   :align: center
+
+Step 2: Go to Rescue Shell
+--------------------------
+
+In the **Troubleshooting** screen, scroll down to **Rescue and Rockstor
+System** and hit enter to go to the **Rescue** screen.
+
+.. image:: /images/howtos/reset-root-password/troubleshooting_screen.png
+   :scale: 80%
+   :align: center
+
+In the **Rescue** screen, use the Tab key to highlight the **Continue** button
+and hit enter.
+
+.. image:: /images/howtos/reset-root-password/rescue_screen.png
+   :scale: 80%
+   :align: center
+
+Hit Enter key again on the next two screens to be dropped into the Shell.
+
+.. image:: /images/howtos/reset-root-password/rescue_shell.png
+   :scale: 80%
+   :align: center
+
+Step 3: Reset password
+----------------------
+
+Once you are in the rescue shell, change the filesystem root ::
+
+  sh-4.2# chroot /mnt/sysimage
+
+Now change the password with the *passwd* command ::
+
+  bash-4.2# passwd
+
+Remove autorelabel file ::
+
+  bash-4.2# rm -f /.autorelabel
+
+Get out of chroot with the exit command ::
+
+  bash-4.2# exit
+
+Here's an example image showing execution of above commands.
+
+.. image:: /images/howtos/reset-root-password/reset_pw_commands.png
+   :scale: 80%
+   :align: center
+
+Enter *exit* command again and the system will reboot ::
+
+  sh-4.2# exit
+
+Remove the install CD/DVD or USB-drive and let the system boot up
+completely. You can now login at the terminal and SSH as root using the new
+password.

howtos/reset-root-password.rst

@@ -1,81 +1,128 @@
 
 .. _rootpwreset:
 
-Resetting root password
+Reset the root password
 =======================
 
-root user is created during Rockstor OS install. You may remember setting root
-password in one of the install screens. After a while, it's possible that you
-forgot the password and would like to reset it. To do that is a straight
-forward process as described in this howto.
+The **root** user is created during the Rockstor installation. During one of the
+installation steps the root password was set (and confirmed).
+After a while, it's conceivably possible that the password information is
+lost and needs to be reset. The Rockstor installation media does not contain
+a rescue environment anymore, due to install media size concerns. Therefore,
+a separate rescue disk needs to be downloaded (less than 1 GB in size).
 
+The disk image can be obtained from openSUSEs repositories for the different releases:
 
-Step 1: Boot up with install CD/DVD/USB-drive
----------------------------------------------
+* `Leap 15.5 <https://download.opensuse.org/distribution/leap/15.5/live/>`_
+* `Leap 15.6 <https://download.opensuse.org/distribution/leap/15.6/live/>`_
+* `Tumbleweed <https://download.opensuse.org/tumbleweed/iso/>`_ 
+  (only available for x86_64 architecture)
 
-Resetting password requires shutting down the system and booting it up with
-Rockstor install CD/DVD or USB-drive as you have done it during install. If you
-are unsure, see :ref:`osinstall`.
+In order to quickly narrow down the search, the Search function in the top left can
+be used. Entering the terms **Rescue** followed by the architecture **x86_64** or **aarch64**
+should narrow this down to the relevant image that can then be downloaded. Unfortunately,
+there is no ready image for a Pi architecture:
 
-On the splash screen, scroll down to **Troubleshooting** and hit enter to go to
-the Troubleshooting screen.
-
-.. image:: /images/howtos/reset-root-password/splash_screen.png
-   :scale: 80%
+.. image:: /images/howtos/reset-root-password/pw01_search_rescue_disk.png
+   :scale: 100%
    :align: center
+
+The downloaded image needs to be used to create bootable media, on a USB stick, 
+CD-ROM/DVD disk, or, if using Rockstor on a virtual machine, the downloaded
+*iso* file can be mounted directly. For USB one can use the same approach
+described for :ref:`makeusbinstalldisk`.
 
-Step 2: Go to Rescue Shell
---------------------------
+Once that's completed, below are the instructions:
 
-In the **Troubleshooting** screen, scroll down to **Rescue and Rockstor
-System** and hit enter to go to the **Rescue** screen.
 
-.. image:: /images/howtos/reset-root-password/troubleshooting_screen.png
-   :scale: 80%
+Step 1: Boot up with an OpenSUSE rescue CD
+------------------------------------------
+
+To reset the password shut down the Rockstor system and boot it up with
+the above created rescue media. Like with the original Rockstor installation,
+it might require to adjust the boot device sequence (in the BIOS, or, if
+available, during the boot process by pressing Function Keys like **<F12>**,
+depending on the motherboard manufacturer).
+
+On the splash screen, select the **Failsafe** option and hit <Enter>. This will
+boot the system into the command line. If, by accident, it boots into the first
+option with a graphical UI, either reset the machine and try again, or attempt to
+open a terminal window on the desktop and proceed from there with the command
+line-based process.
+
+.. image:: /images/howtos/reset-root-password/pw01_splash_screen.png
+   :scale: 50%
    :align: center
 
-In the **Rescue** screen, use the Tab key to highlight the **Continue** button
-and hit enter.
 
-.. image:: /images/howtos/reset-root-password/rescue_screen.png
+Step 2: Log in and mount relevant devices and partitions
+--------------------------------------------------------
+
+After the boot completes the login prompt should appear (the screenshot
+is from a virtual machine, hence the *vbox* login). Right above the network
+interfaces are listed, though they won't be needed for this activity.
+
+.. image:: /images/howtos/reset-root-password/pw01_rescue_shell.png
    :scale: 80%
    :align: center
 
-Hit Enter key again on the next two screens to be dropped into the Shell.
+To log into the system, just type :code:`root` for the user and hit <Enter>.
+Now that the login is complete, a device and a few partitions need to be 
+mounted for the password reset to work.
+
+First, identify the device that houses the Rockstor Operating System, using:
 
-.. image:: /images/howtos/reset-root-password/rescue_shell.png
+.. code-block: console
+   lsblk
+   
+to identify all devices connected to the machine, and then, identify
+the one that's the system device (likely the one that has the smallest size).
+Here is a sample output, it will look different on every user's machine:
+
+.. image:: /images/howtos/reset-root-password/pw01_lsblk_output.png
    :scale: 80%
    :align: center
 
-Step 3: Reset password
-----------------------
-
-Once you are in the rescue shell, change the filesystem root ::
+In the above example **/dev/sda4** is the system device (largest partition on
+*sda*).
 
-  sh-4.2# chroot /mnt/sysimage
+Next mount that device:
 
-Now change the password with the *passwd* command ::
+.. code-block: console
+   
+   vbox:~# mount -o rw /dev/sda4 /mnt
+   
+Then create a few bind mounts, change the filesystem root directory for the 
+running process and finally mount these, so that the system can use them
+for the next step:
 
-  bash-4.2# passwd
+.. code-block:: console
+   
+   vbox:~# mount -o bind /proc /mnt/proc
+   vbox:~# mount -o bind /sys /mnt/sys
+   vbox:~# mount -o bind /dev /mnt/dev
+   vbox:~# chroot /mnt
+   vbox:~# mount -a
 
-Remove autorelabel file ::
+Step 3: Reset password
+----------------------
 
-  bash-4.2# rm -f /.autorelabel
+Now change the password with the *passwd* command ::
 
-Get out of chroot with the exit command ::
+.. code-block:: console
 
-  bash-4.2# exit
+   vbox:~# passwd
 
-Here's an example image showing execution of above commands.
+Enter the new password. The system will ask for confirmation
+through retyping it. Then the new password is set.
 
-.. image:: /images/howtos/reset-root-password/reset_pw_commands.png
-   :scale: 80%
-   :align: center
+Get out of chroot with the exit command ::
 
-Enter *exit* command again and the system will reboot ::
+.. code-block:: console
+   
+   vbox:~# exit
 
-  sh-4.2# exit
+Shut down the system and remove the rescue disk.
 
-Remove the install CD/DVD or USB-drive and let the system boot up
-completely. You can now login at the terminal and SSH as root using the new
-password.
+Boot the system back up and a login using the root password should
+once again be possible.