.. include:: ../urls.rst

.. _l5_troubleshooting_repairing_broken_installation:

.. meta::

   :keywords: broken byzantium pureos recover


Repairing a broken installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are a few options to recover data and attempt to recover the operating system.

.. caution::
   These instructions are relatively technical in nature and should only be performed by someone comfortable with technical instructions.

Back up any files you need from your device.
You can do this by booting Jumpdrive on the phone and copying your files to a Linux PC using the steps below:


.. _l5_troubleshooting_repairing_broken_installation_back_up:

Back up important files using Jumpdrive
---------------------------------------

Follow the steps to :ref:`mount the Librem 5 storage device on another computer <l5_tips_mount_internal_storage>`.


.. _l5_troubleshooting_repairing_broken_installation_repair:

Try to repair your installation
-------------------------------


.. _l5_troubleshooting_repairing_broken_installation_repair_terminal:

Open a Terminal in the Librem 5 root
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Use ``lsblk`` to see where the root and boot partitions are mounted.
   We mounted root above, GNOME probably mounted boot automatically already.
   On PureOS/Debian, it'll be something like ``/media/<user>/<uuid>``
#. ``cd`` to the root partition.
   If you list with ``ls`` you should see ``bin``, ``dev``, ``boot``, ``etc`` and other directories.


.. _l5_troubleshooting_repairing_broken_installation_repair_mount:

Mount the boot and system directories needed for chroot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Bind-mount the boot partition.
   Use the location found above, and don't forget the ``.`` in ``./boot``.

   .. code:: bash

      sudo mount -o bind /media/<user>/<uuid> ./boot
      sudo mount -o bind /dev ./dev
      sudo mount -o bind /sys ./sys
      sudo mount -o bind /proc ./proc


.. _l5_troubleshooting_repairing_broken_installation_repair_chroot:

``chroot`` into the installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Install these PureOS/Debian packages if you don't already have them:

   .. code:: bash

      qemu qemu-user-static binfmt-support

#. ``chroot`` into the phone OS while still in the Librem 5 root directory:

   .. code:: bash

      sudo chroot .


.. _l5_troubleshooting_repairing_broken_installation_repair_check:

Check for common problems
^^^^^^^^^^^^^^^^^^^^^^^^^

.. important::
   Execute the following commands inside the chroot.

#. Check if your boot partition is full.
   This will sometimes cause an update failure:

   .. code:: bash

      df -h /boot

#. If it has less than 100 MB free space, try to remove dpkg backup initrds:

   .. code:: bash

      rm /boot/initrd*.dpkg-bak

#. Check again:

   .. code:: bash

      `df -h /boot

#. If it still has less than 100 MB free space, try to remove any old kernels.
   This may remove other unreferenced packages if any exist.

   .. code:: bash

      apt autoremove

#. Try to repair any broken packages:

   .. code:: bash

      apt --fix-broken install


.. _l5_troubleshooting_repairing_broken_installation_repair_cleanup:

Clean up
^^^^^^^^

#. Exit the chroot:

   .. code:: bash

      exit

#. While still working from within the chroot directory, unmount partitions from the chroot:

   .. code:: bash

      sudo umount ./{boot,dev,proc,sys}

#. Close the terminal tab or window
#. Unmount the Librem 5 using the eject button in GNOME Files
#. Unplug the USB-C cable from the Librem 5
#. Hold the power button on the phone to power off
#. Try to :ref:`power on the phone <l5_power_on>` again