Skip to content

Commit

Permalink
Merge pull request #395 from phillxnet/379_update_Pre-Install_Best_Pr…
Browse files Browse the repository at this point in the history 
…actice_(PBP)

update Pre-Install Best Practice (PBP) #379
  • Loading branch information
@phillxnet
phillxnet authored Aug 29, 2022
2 parents f5fdcbd + 12cc4d4 commit c94a906
Show file tree
Hide file tree
Showing 4 changed files with 97 additions and 165 deletions.
Binary file removed images/installation/pre-install-howto/run_memory_test.png
View file
Binary file not shown.
Binary file removed images/installation/pre-install-howto/test_this_media.png
View file
Binary file not shown.
Binary file removed images/installation/pre-install-howto/troubleshooting.png
View file
Binary file not shown.
262 changes: 97 additions & 165 deletions installation/pre-install-howto.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,208 +3,140 @@
Pre-Install Best Practice (PBP)
===============================

This howto sets
out to establish **Best Practice** prior to a **Rockstor install**. It has
grown out of a number of suggestions on the `Rockstor forum
<https://forum.rockstor.com/>`_ where problems have been encountered that
might otherwise have been avoided. The basic premise is to first ensure that
the hardware you are to install Rockstor on is fit for purpose and tested
reasonably with the readily available tools.
This how-to sets out to establish **Best Practice** prior to a **Rockstor install**.
It has grown out of a number of suggestions on the
`Rockstor forum <https://forum.rockstor.com/>`_
where problems have been encountered that might otherwise have been avoided.
The basic premise is to first ensure that the hardware you are to install Rockstor on
is fit for purpose and tested with readily available tools.

.. _memory_test:

Memory Test (memtest86+)
------------------------

The `memtest86+ <https://www.memtest.org/>`_ program is actually derived from
the linux kernel itself, the core of the operating system that Rockstor is
built on. Memtest86+ is licensed under the GPL.
The `memtest86+ <https://www.memtest.org/>`_ program is derived from the linux kernel itself,
the core of the operating system that Rockstor is built on.
Memtest86+ v6 is licensed under the GPL v2.
This project has more recently undergone a re-write under the v6 version.
V6's code base was originally named PCMemTest, which was in turn based on memtest86+ v5.
Technical reference: `GitHub memtest86plus <https://github.com/memtest86plus/memtest86plus/>`_.

Memtest86+ Cautionary Note
^^^^^^^^^^^^^^^^^^^^^^^^^^

Memtest86+ can place a very intense load on your system, especially if run in
the new Multithreaded mode (version 5.01 and onwards via F2 on initial start)
but a sufficiently cooled system should be able to execute this test
indefinitely; however, if your system has cooling issues then it may lockup
or even sustain damage. Please take care to monitor your system's temperatures
during this test. Version 5.01 and on have a built-in CPU temperature monitor.
If you find that your version of the Rockstor installer doesn't include the 5
.01 or newer version of memtest86+, or any version at all (Rockstor 4) then
download a `Pre-Compiled Bootable ISO <https://www.memtest.org/#downiso>`_
from the project's official page and write it to a USB key in exactly the same
way you do for a Rockstor install ISO.
Memtest86+ can place a very intense load on your system,
especially if run in the new multi-threaded mode (version 5.01 and newer via F2 on initial start)
but a sufficiently cooled system should be able to execute this test indefinitely.

N.B. This memory test system will **continue indefinitely** until you either
turn off the system, which is safe to do, or press the **ESC Key**. It is
recommended that 2 full test cycles be completed, however a single full pass of
all available tests is better than no memory testing at all.
.. warning::
If your system has cooling issues then it may lockup or even sustain damage.
Please take care to monitor your system's temperatures during this test.
Version 5.01 and newer have a built-in CPU temperature monitor.

An effective memory test is likely not to be complete in less than a few
hours, though this depends on the speed of the hardware involved and how many
passes one is content with.
N.B. This memory test will **continue indefinitely** until you either:

Our legacy Rockstor 3 installer (inherited from the upstream CentOS
installer) has a `memtest86+ <https://www.memtest.org/>`_ boot option built
into the *Troubleshooting* installer menu.
1. turn off the system (which is safe to do)
2. press the **ESC Key**

First select the **Troubleshooting** menu item on the initial boot screen of
the installer:-
It is **recommended that two full test cycles** be completed.
But a single full pass of all available tests is better than no memory testing at all!

.. image:: /images/installation/pre-install-howto/troubleshooting.png
:width: 100%
:align: center
A single test cycle may well take several hours,
depending on the speed of the hardware involved and the size of memory tested.

Use the **Cursor Keys** and then the **Enter Key** to select this entry.

The following options should then be displayed:

.. image:: /images/installation/pre-install-howto/run_memory_test.png
:width: 100%
:align: center

Then select the **Run a memory test** option to boot the machine into the
**memtest86+** system.
Download
^^^^^^^^

The official website has `Pre-Compiled Bootable ISO images <https://www.memtest.org>`_.
Along with advise on creating a bootable USB key.

.. _wiping_disks:

Wiping Disks (DBAN)
-------------------

A popular tool to securely erase HDDs prior to their deployment or disposal is
`Darils Boot and Nuke <https://dban.org/>`_. This tools essentially writes
to every part of a
disks surface and in the process exercises the drive across it's entire
working area. This like the :ref:`memory_test` will stress the system; in this
case the drives selected for wiping. The purpose here is to first remove all
data on the existing drives and second to test that the drive is able to
write to all it's available sectors, it is often the case that a drive is
unaware of an issue with itself, via the built in SMART system, until it
attempts to write to a faulty sector. In fact this can trigger a drives build
in ability to allocate spare sectors reserved for this very purpose.

Note that the zero fill *fast* option is probably sufficient for testing
purposes but that there are many official options available. All options will
take a considerable amount of time to complete, ie in the region of a few
hours per drive.

It is **not** strongly recommended that any drives be tested this way prior to
using them for Rockstor but is included here as an advisory procedure if you
suspect a drive of having hardware issues.

DBAN Cautionary Note
^^^^^^^^^^^^^^^^^^^^

The DBAN program / procedure will **Irreversibly Erase all data**. Use with
caution and disconnect any drives that you wish not to be affected prior to
booting into DBAN. Due to the comparatively limited write cycles of earlier
generation SSD's further consideration should be given prior to running DBAN
on these devices due to it's write heavy nature.


.. _check_md5sum:

Check Integrity of Downloaded ISO File
--------------------------------------

If the original download is corrupt then all else that follows is likely to have
problems. ISO is computer slang short for ISO9660 which is the
`International Organization for Standardization
<https://www.iso.org/home.html>`_ official definition of the structure of
data on a CD/DVD. If this structure is wrong or the data contained within it is
corrupt then problems are bound to follow. To avoid this there is a simple
command that can be executed once the download of the Rockstor iso file is
complete: that of checking it's checksum.

A checksum is a mathematical
abstraction of a data set, in this case our file, that is unique (near enough
anyway). As a result of this it is possible to establish file corruption by
comparing the published checksum of the official file with that calculated from
the downloaded file. This in effect verifies the downloaded file as legitimate
/ free from corruption. Note however though that if you used the BitTorrent
download option to acquire your install image then this check has already been
done by way of the internal workings of the BitTorrent system. No harm in
double checking though. If however you acquired your image by any other means
then it is highly recommended that you check it's md5sum. In the following
operating system specific sections it is assumed that you have downloaded your
Rockstor ISO file into the *Downloads* directory and have opened a system
terminal ready to execute the appropriate command.
Wiping Disks
------------

.. _check_md5sum_linux:
There are limited instances where Rockstors Web-UI may falter, or be confused by a pre-used disks format.
Rendering the capability to first wipe these disks via the Web-UI's :ref:`wipedisk` inaccessible.
On these rare occasions one can simply resource the linux command line tool "wipefs" to achieve the same.
Behind the scenes Rockstor's partition and/or disk wipe procedure executes a "wipefs -a dev-name-here".
Pre-used mdraid members may require additional mdraid configuration removal.

On a Linux system
^^^^^^^^^^^^^^^^^
.. warning::
As with all mass delete functions, be extremely certain that you are doing the right thing.
This requirement has not now been reported for some time.
So do first consider/research carefully if such a command line approach is in fact required.

The following built-in command is how to get the md5sum of your downloaded file
on almost any linux system.
.. note::
Past instances of this command line approach to removing pre-use partitioning and formatting
has been associated with prior mdraid use and some LVM configurations.
Neither of which are supported by Rockstor's Web-UI.

::
.. _dban:

md5sum ~/Downloads/Rockstor-3.8-11.iso
DBAN
^^^^

example output:
`Darils Boot and Nuke <https://dban.org/>`_
is a popular tool to securely erase HDDs prior to their deployment or disposal.
In brief, this tool writes to every part of a disks surface to exercises the entire storage.
Akin to :ref:`memory_test` this will stress the tested parts of the system;
in this case the drives selected for wiping.

::
DBAN Purpose
^^^^^^^^^^^^

fbb65344b31c7715807750e58e99f788 Rockstor-3.8-11.iso
1. Securely remove all data on a per drive basis.
2. Test the drive/s ability to write to all its available sectors,

.. _check_md5sum_osx:
It is often the case that a drive is 'unaware' of an issue with itself,
via the built in SMART system, until an attempts is made to write to a faulty sector.
Writes can trigger a drives own built-in ability to swap-in spare/redundant sectors.
These spare sectors are a very limited resource, and should not be relied upon.

On an OSX system
^^^^^^^^^^^^^^^^
Note that the zero fill *fast* option is probably sufficient for testing purposes.
There are however many more exotic and official wiping algorithms available.
All options will take a considerable amount of time to complete,
i.e. in the region of a few hours per drive minimum.

Here we see the built-in command to use on an OSX system as used on modern
Apple computers.
It is **not** strongly recommended that drives be DBAN tested prior to using them for Rockstor.
But this tool can be a valuable resource, especially if a drive's hardware is suspect.
Keep in mind however that this test procedure will stress the drive concerned,
and likely its associated cooling.

::

md5 ~/Downloads/Rockstor-3.8-11.iso

example output:

::

MD5 (Rockstor-3.8-11.iso) = fbb65344b31c7715807750e58e99f788

.. _check_md5sum_win:

On an MS Windows system
^^^^^^^^^^^^^^^^^^^^^^^

Using the built-in tool available on MS Windows.

::

CertUtil -hashfile %userprofile%\Downloads\Rockstor-3.8-11.iso MD5

example output:
DBAN Cautionary Note
^^^^^^^^^^^^^^^^^^^^

::
.. warning::
The DBAN program / procedure will **Irreversibly Erase/Overwrite all data**.
Use with extreme caution.
Be sure to disconnect all drives that you wish not to be affected before booting/running DBAN.

MD5 hash of file C:\Users\username\Downloads\Rockstor-3.8-11.iso:
fb b6 53 44 b3 1c 77 15 80 77 50 e5 8e 99 f7 88
CertUtil: -hashfile command completed successfully.
.. note::
Due to the comparatively limited write cycles of earlier generation SSDs
further wear consideration should be given prior to running DBAN on these devices.

.. _check_install_media:
.. _installer_checksum:

Checking the Install Media
--------------------------
Check Integrity of Downloaded installer
---------------------------------------

Once you have created the USB or in deed the CD / DVD by your chosen method:
see :ref:`makeusbinstalldisk` in our :ref:`quickstartguide` guide there is one
final measure one can take to ensure the the install media is as
expected. That is to choose the **Test this media & install Rockstor** option
on the initial boot screen of the installer:-
.. note::
It is highly recommended that you check your downloaded installers integrity.
If the original download is corrupt then all else that follows is likely to have problems.

.. image:: /images/installation/pre-install-howto/test_this_media.png
:width: 100%
:align: center
ISO is computer-slang/short for ISO9660 which is the
`International Organization for Standardization <https://www.iso.org/home.html>`_
official definition of the structure of data on a CD/DVD.
If this structure is wrong, or the data contained within is corrupt, then problems will follow.
The same is true for our non ISO type installers.

Using this option the installer will first check that it can successfully read
the contents of the USB key or CD / DVD and only proceed if the integrity check
of what it reads succeeds. Note that this does take additional time but not
more than a few minutes on modern USB hardware.
The `Rockstor Downloads <https://rockstor.com/dls.html>`_ page has image specific instruction
on how to check each type of installer offered via a single simple linux/OSX command line instruction.
The test is a checksum validation; made against a tiny matching additional download ending in "sha256".

The purpose of this test is two fold as it is not only checking the contents of
the install media but also the computers ability to read that contents.
A checksum is a mathematical abstraction of a data set, in this case our file,
that is unique (near enough anyway).
As a result it is possible to establish file corruption by comparing the published checksum
with that calculated directly from the downloaded file.
This in effect verifies the integrity of the downloaded file and confirms it as free from corruption.

0 comments on commit c94a906

Please sign in to comment.