===============
System Recovery
===============

Even though OSDx tries, for the most part, to warn about configurations that could leave the
system unresponsive or "bricked", recovering the system from one of these unwanted states may 
prove necessary at some point. This article describes three staggered
ways of recovering a "broken" system.

Some of these methods may be accessed via :ref:`CLI <intro/cli:CLI Overview>` or 
the :ref:`management/recovery/index:Boot menu`.

Boot menu
=========

OSDx has a bootloader menu that allows users to restore the default configuration, 
re-apply factory settings, boot into any image previously installed, and reset the device 
using tftp. The OSDx Boot Menu is only accessible through a serial connection. See 
:ref:`intro/cli:Accessing the CLI` for more information.

Depending on the device, the bootloader menu may look different. In proprietary ``arm64``
and ``armhf`` devices the boot menu will look like this:

.. figure:: boot_menu_uboot.png
  :width: 400px

  *OSDx Boot Menu in proprietary arm64 and armhf devices*

Meanwhile, on standard ``amd64/x86`` systems the boot menu will look like this:

.. figure:: boot_menu_grub.png
  :width: 400px

  *OSDx Boot Menu in standard amd64/x86 systems*

In both cases, the ``Up`` or ``Down`` arrow keys on the keyboard may be used to select 
the desired menu entry and the ``Enter`` key to confirm the selection.

1. Default configuration
========================

The first method to restore the system is simply to return it to a configuration
that works, such as the default configuration. 

Before restoring the default configuration, you may want to save your current
configuration.

*Example:*

.. code-block:: none

  admin@osdx$ show running | file running://old-config
  Command's output saved under "old-config"
  Filesize: 372.000 B

The default configuration can be restored from the CLI or the boot menu.

CLI
---

From the CLI, run the ``load factory-config`` configuration command followed by ``commit``.

*Example:*

.. code-block:: none

  admin@osdx# load factory-config
  admin@osdx# commit
  admin@osdx# save

Finally, reboot the system.

Boot menu
----------

.. important::

    This method will have no effect on OSDx versions older than ``v3.9.1.2``. If the 
    ``(default config)`` boot menu entry shows an older version, change the default boot 
    image to OSDx version ``v3.9.1.2`` or a newer one using the 
    ``image boot`` operational command. See :ref:`image-boot-command` for more information.
    
Reboot the system, navigate over to the ``Run OSDx (vX.X.X.X) (default) (default config)`` 
or ``OSDx (vX.X.X.X) (default config)`` option in the boot menu and press ``Enter``. 
OSDx will automatically boot and restore the default configuration. If the issues 
persist, proceed to the next section 
:ref:`Factory reset <management/recovery/index:2. Factory reset>`.

2. Factory reset
================

Factory resetting a device returns it to its original state, both in terms of version and
configuration.

.. warning::

    This will erase all files and the current image configuration.

The factory reset can be performed from the CLI or the boot menu.


CLI
---

The ``factory-reset`` command allows you to factory reset the device from the OSDx CLI.

*Example:*

.. code-block:: none

  admin@osdx$ factory-reset
  This will destroy all data in the current image and restore factory settings.
  Continue? (Yes/No) [No]: yes
  Removing current data
  Rebooting...

If you have physical access to the device, in some devices you can also trigger a factory 
reset by pressing the reset button until a LED, usually marked as ``SYS``, starts 
blinking.

Boot menu
----------

.. important::

    This method will have no effect on OSDx versions older than ``v3.9.1.2``. If the 
    ``(FACTORY RESET)`` boot menu entry shows an older version, change the default boot 
    image to OSDx version ``v3.9.1.2`` or a newer one using the 
    ``image boot`` operational command. See :ref:`image-boot-command` for more information.
    

Reboot the system, navigate over to the ``Run OSDx (vX.X.X.X) (default) (FACTORY RESET)`` 
or ``OSDx (vX.X.X.X) (FACTORY RESET)`` option in the boot menu and press ``Enter``. OSDx 
will automatically boot and restore the device to its original state.


3. Software recovery
====================

If none of the above methods were successful in recovering the device, a different OSDx
version may need to be installed through the bootloader.

.. warning::

    This will erase all files, configurations, and images on the device.

To install OSDx on SDE devices, refer to the :doc:`Bare metal installation guide
</intro/setting_up/installing/bare_metal/index>`. For other devices, continue reading.

.. danger::

    This procedure could leave your device unusable, be extremely careful!


In order to reset the device, you will need to set up a tftp server at IP address
``192.168.3.1``, with the OSDx image file available at ``192.168.3.1/<model>/os.img``.
where ``<model>`` is the device model (e.g., ``RS420``).

Reboot the device
--------------------

During the boot sequence, you will see the following menu:

.. figure:: boot_menu_uboot.png
  :width: 400px

  *OSDx Boot Menu*

Here, you may press the up or down arrow keys on your keyboard to increase the
timeout before the device automatically boots.

Reset the device
-------------------

Navigate over to the ``Reset OSDx device using tftp`` option and press the ``Enter``
key. The image will start downloading from the tftp server and will be installed on
the device:

.. figure:: tftp_reset.png
  :width: 400px

  *TFTP reset start*

If successful, you should see the following output after a couple of minutes:

.. figure:: tftp_finish.png
  :width: 400px

  *TFTP reset end*

The device should then boot into the installed image and be operational.