Merge pull request #90 from sunnyflunk/troubleshoot

Provide some generic troubleshooting information

troubleshooting/boot-management/en.md

@@ -0,0 +1,43 @@
+# Boot management
+
+## Bring up the boot menu with no timeout set?
+
+By default, EFI installs will not show the boot menu and boot directly into Solus. By hitting space bar (repeatedly) during boot, the boot menu will appear (it may take a couple of goes to get the timing right).
+
+## Appending kernel parameters to Solus boot
+
+Kernel parameters can be appended to boot via creating a file for `clr-boot-manager` to use when updating kernels. For example, to add `nomodeset` to boot options, you would create the file `/etc/kernel/cmdline` (as sudo):
+
+```
+echo 'nomodeset' | sudo tee /etc/kernel/cmdline
+```
+
+The settings should be on one line with a space between them. You will need to run `sudo clr-boot-manager update` for the options to be appended to boot.
+
+## Displaying the Solus boot menu by default on boot
+
+The following command will set the timeout of the boot loader so that it appears by default.
+
+```
+sudo clr-boot-manager set-timeout 5 && sudo clr-boot-manager update
+```
+
+## Installing an alternative kernel
+
+By default from `Solus 3`, the ISO ships with the `linux-current` kernel. The separate kernel branches can be added by installing the `linux-lts` or `linux-current` packages. Note that each kernel has separate module packages, so if you use these kernel modules, you'll need to install the one related to the kernel you are adding.
+
+|linux-lts               |linux-current                   |
+|------------------------|--------------------------------|
+|bbswitch                |bbswitch-current                |
+|broadcom-sta            |broadcom-sta-current            |
+|linux-lts-headers       |linux-current-headers           |
+|nvidia-304-glx-driver   |nvidia-304-glx-driver-current   |
+|nvidia-340-glx-driver   |nvidia-340-glx-driver-current   |
+|nvidia-glx-driver       |nvidia-glx-driver-current       |
+|razer-drivers           |razer-drivers-current           |
+|v4l2loopback            |v4l2loopback-current            |
+|vhba-module             |vhba-module-current             |
+
+### Change the default kernel branch to boot
+
+After successfully booting into a kernel from the `current` or `lts` branches running `sudo clr-boot-manager update` will make the booted kernel branch the default boot option going forward.

troubleshooting/general-troubleshooting/en.md

@@ -0,0 +1,83 @@
+# General troubleshooting
+
+This guide provides some basic troubleshooting instructions for when you have an issue in Solus. Before reporting bugs, it is important to validate your Solus installation doesn't suffer from missing files or disk corruption. Also ensuring the system is fully up to date as the bug may have already been fixed.
+
+First of all performa a full system update `sudo eopkg up` (or via the Software Center). Then validate that packages are installed correctly and aren't missing files: (run this once, it will take some time and may not show much output)
+
+```
+sudo eopkg check | grep Broken | awk '{print $4}' | xargs sudo eopkg it --reinstall
+```
+
+Then reboot the system to make sure the issue still persists on a clean system.
+
+## Issues with eopkg
+
+### Eopkg won't install updates
+
+If eopkg is interrupted, the database may become corrupted. When updating you will see a message similar to:
+
+`30973, 'BDB0087 DB_RUNRECOVERY: Fatal error, run database recovery - BDB0061 PANIC: Invalid argument'`
+
+To run database recovery, run `sudo eopkg rdb` in the terminal and then updates should function correctly.
+
+### Eopkg check shows broken packages
+
+`eopkg check` checks the sha256sums of files on disk versus what was originally installed by the original .eopkg file. In some cases (for example .pyc files), these files will be modified in the normal operation of Solus. If after reinstalling a package it remains broken, then it's likely nothing to worry about (there are no exceptions made in `eopkg check` for files that are expected to change from use). When reinstalling broken packages, (per above) it only needs to be run once.
+
+## Updated system and having issues
+
+### Boot into previous kernel
+
+`clr-boot-manager` by default retains the latest installed kernel, plus the currently running kernel. This means that when you receive a kernel update, there are two kernels to boot into. Sometimes there are regressions that occur in the kernel, so you are able to boot into the previous kernel if the update has caused any hardware issues (for example failing to suspend when it worked previously). When booting via EFI, the boot menu can be shown by hitting space (repeatedly) during boot.
+
+### Reverting updates
+
+If booting into the previous kernel doesn't solve the issue, there may be an issue with the package updates. It is possible to [revert the updates](https://solus-project.com/articles/package-management/history-and-rollback/en/) (this would also confirm that the issue is in the selected updates).
+
+## Boot Failure
+
+If Solus partially boots, you can generally get to a TTY using `Ctrl+Alt+F2` to login and be able to run commands just like using a terminal. This enables you to run some commands to identify or resolve the issue.
+
+### Display manager won't start
+
+A common cause of not being able to boot is due to installing the nvidia drivers, but not booting into the latest kernel (the only kernel which has the drivers installed). Also ensure you have the correct driver version installed for your kernel. You can check if you have booted into the latest kernel by comparing the installed package with the booted kernel (instructions for both kernels)
+
+```
+eopkg info linux-lts | head -n2; uname -a
+```
+
+```
+eopkg info linux-current | head -n2; uname -a
+```
+
+If the kernel version and release don't match from lines 2 and 3 of the output, then you aren't booting into the latest kernel and this is the likely cause of X not loading (particularly if you just installed the drivers). A couple of common reasons are:
+
+ - On a grub machine, a common cause for not booting the latest kernel is due to Solus not being the boot loader on the MBR. Make sure you are booting via the Solus boot loader (if possible), or update grub on the distro that own the boot loader, see [Legacy/BIOS installation](Link Above).
+
+ - Another possibility is that the `ESP` has run out of space so the kernel cannot be copied over to it. You can debug why this isn't happening via `sudo CBM_DEBUG=1 clr-boot-manager update`. This will output all information on the process, where it may be failing, or that it is working correctly.
+
+If these two steps fail, you can't revert the installation of the drivers via [History and Rollback](https://solus-project.com/articles/package-management/history-and-rollback/en/)
+
+### No Solus boot loader
+
+If the Solus boot loader is not functioning (this has been known to be broken by the odd update of a certain OS), the boot loader can be recreated via [Boot Rescue](https://solus-project.com/articles/repair-and-recovery/boot-rescue/en/)
+
+## Long boot time
+
+There are a number of factors that can contribute to a long boot time. The boot up messages can be viewed to look for any timeouts by looking at the timestamped journal.
+
+```
+sudo journalctl -b
+```
+
+Notable commands to check the boot time are: `systemd-analyze` (note that the firmware time is prior to Solus boot, so outside of our control) and `systemd-analyze critical-chain`.
+
+### Timeout on partition mount (90s)
+
+If information about a device changes (UUID or mount path `/dev/sda`), this can cause systemd to time out for 90 seconds creating a long boot process. Most frequently this happens with the swap file which can be shared across distros. Most of the devices mounted on boot will appear in `/etc/fstab` or be a parameter in a file where configuring resume `cat /etc/kernel/cmdline.d/*`.
+
+`cat /proc/cmdline` will show what parameters the kernel has booted with.
+
+If the devices don't match up with what's listed in `ls /dev/disk/*/*` then it will cause a 90s timeout while it waits to see if it can be found. To fix this, you will need to remove the reference to the UUID or device path that no longer exists, or correct it to the new UUID label.
+
+

troubleshooting/installation-issues/en.md

@@ -0,0 +1,19 @@
+# Installation Issues
+
+## Can't install in EFI mode
+
+The live ISO will attempt to install Solus by the same method it was booted. If it is unable to install the boot loader to the ESP, then it is likely booted in legacy mode. Ensure that the ISO has been created via a [supported method](https://solus-project.com/articles/installation/preparing-to-install/en/) and that an EFI boot is selected from the boot options.
+
+You can check whether the Solus ISO has booted in EFI mode by checking the for the existence of `ls /sys/firmware/efi` (if it's not found, then it's booted in legacy mode).
+
+## I can't boot into Solus after installation!
+
+There are some misunderstandings with how legacy and EFI boot works (usually implemented as UEFI). These sections cover the common misconceptions.
+
+### Legacy/BIOS installation
+
+Legacy installations on Solus use the Grub boot loader on an MBR disk. Only one boot loader can be used on an MBR disk, so if you haven't installed the Solus boot loader on the MBR, you will need to boot into the other OS and update grub prior to being able to boot Solus. This will also be required on each update of the kernel to ensure you're booting in the latest release.
+
+### EFI
+
+EFI allows for multiple boot loaders to be installed, which means you can boot the Solus boot loader directly. To ensure you are booting Solus you need to boot `Linux Boot Manager` from the EFI options. Common keys for bringing up a boot menu or the options during boot are hitting `Esc/F2/F9/F10/F11/F12` during boot (this differs per motherboard). If a boot loader for another OS is not listed in the menu, then it is not correctly registered (and therefore not installed correctly). You can make the Solus boot menu appear via [Displaying the Solus boot menu on boot](https://solus-project.com/articles/troubleshooting/boot-management/en/) which should be able to boot windows (as it's registered with UEFI properly) as well as Solus, but not other systems.