Adds doc to repair failed installation; adds new target refs. (#455)

* Adds repair of failed installation. Adds, revises target refs where needed.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Adds repair of failed installation. Adds, revises target refs where needed.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Add cross-ref to swupd-guide per feedback.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Incorporate reviewer feedback; reset refs for includes to `-beta`.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Revise per reviewer feedback on PR.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

source/clear-linux/get-started/bare-metal-install-beta/bare-metal-install-beta.rst

@@ -37,6 +37,8 @@ Preliminary steps
 
    * :ref:`bootable-usb`
 
+.. _install-on-target-start:
+
 Install from live image
 ***********************
 
@@ -60,6 +62,8 @@ USB drive, follow these steps.
 
 #. Reboot the target system.
 
+.. _install-on-target-end:
+
 Launch the installer
 ====================
 

source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst

@@ -36,8 +36,6 @@ Look for the :file:`clear-[version number]-installer.img.xz` file.
 
 #. After downloading the image, verify and decompress the file per your OS.
 
-.. _install-on-target:
-
 Install |CL| on your target system
 **********************************
 

source/clear-linux/get-started/virtual-machine-install/vmw-player.rst

@@ -202,8 +202,8 @@ Install |CL| into the new VM
 
       Figure 9: VMware Workstation 14 Player - Power on virtual machine
 
-#. Follow the :ref:`install-on-target` guide to complete the installation of
-   |CL|.
+#. Follow the :ref:`install-on-target-start` guide to complete the
+   installation of |CL|.
 
 #. After the installation completes, reboot the VM. This reboot restarts the
    |CL| installer.

source/clear-linux/get-started/virtual-machine-install/vmware-esxi-install-cl.rst

@@ -203,7 +203,7 @@ Install |CL| into the new VM
 
           Figure 11: VMware ESXi - Navigator > Virtual Machines > Power on VM
 
-#.  Follow the :ref:`install-on-target` guide to complete the installation of 
+#.  Follow the :ref:`install-on-target-start` guide to complete the installation of 
     |CL|.
 #.  After the installation is complete, follow the |CL| instruction to reboot it.  
     This will restart the installer again. 

source/clear-linux/guides/maintenance/fix-broken-install.rst

@@ -0,0 +1,79 @@
+.. _fix-broken-install:
+
+Fix a broken installation of |CL-ATTR|
+######################################
+
+This guide explains how to fix a broken installation of |CL| using a live
+desktop image on a USB. It's assumed you already installed |CL| on a
+target system, but your operating system does not boot or function properly.
+
+This process can only verify and fix files that :ref:`swupd<swupd-guide>`
+owns in :file:`/usr`. Files outside of this path, such as /home/, /etc,
+/var, etc., cannot be repaired by this process.
+
+Prerequisites
+*************
+
+* :ref:`Download and install the live desktop image on a USB <bare-metal-install-beta>`
+
+Boot a live desktop image to fix target system
+**********************************************
+
+#. Boot the |CL| live desktop image.
+
+.. include:: ../../get-started/bare-metal-install-beta/bare-metal-install-beta.rst
+   :start-after: install-on-target-start:
+   :end-before: install-on-target-end:
+
+Mount root partition, verify, and fix
+*************************************
+
+#. Open a Terminal window.
+
+#. Assure the system is connected to the network.
+
+#. Mount the system’s root partition.
+
+   #. To find the root partition, run:
+
+      .. code-block:: bash
+
+         lsblk
+
+      We'll use `/dev/sda3/` as the root partition example.
+
+   #. Next, mount it.
+
+      .. code-block:: bash
+
+         sudo mount /dev/sda3 /mnt
+
+#. Verify that you mounted the correct root partition by checking the list
+   of bundles that you installed on it.
+
+   .. code-block:: bash
+
+      ls /usr/share/clear/bundles
+
+#. Next, run swupd to fix any issues on the target system.
+
+   .. code-block:: bash
+
+      sudo swupd verify --fix --picky --path=/mnt
+
+   :ref:`Learn more about how swupd works <swupd-guide>`.
+
+#. After the process is complete, unmount the root partition:
+
+   .. code-block:: bash
+
+      sudo umount /mnt
+
+#. Reboot the system, remove the live desktop USB drive,
+   and boot into the repaired system.
+
+   .. code-block:: bash
+
+      sudo reboot
+
+**Congratulations!** You successfully restored |CL|.