4.5. Troubleshooting Installations
The installer is quite reliable, but you may encounter bugs or face external problems such as: network problems, bad mirrors, and insufficient disk space. Because of this, it is quite useful to be able to troubleshoot problems that appear in the installation process.
When the installer fails, it will show you a rather unhelpful screen such as the one shown in Figure 4.26, "Installation Step Failed".
Figure 4.26. Installation Step Failed
At this point, it is good to know that the installer makes use of multiple virtual consoles: the main screen that you see is running either on the fifth console (for the graphical installer, CTRL+ALT+F5) or on the first console (for the classic text-mode installer, CTRL+ALT+F1). In both cases, the fourth console ( CTRL+ALT+F4 ) displays logs of what is happening and you can usually see a more useful error message there, such as the one in Figure 4.27, “The Log Screen of the Installer”, which reveals that the installer has run out of disk space.
Figure 4.27. The Log Screen of the Installer
The second and third consoles ( CTRL+ALT+F2 and CTRL+ALT+F3, respectively) host shells that you can use to investigate the current situation in more detail. Most of the command line tools are provided by BusyBox so the feature set is rather limited, but it is enough to figure out most of the problems that you are likely to encounter.
What Can be Done in the Installer Shell
You can inspect and modify the debconf database with debconf-get and debconf-set. These commands are especially convenient for testing preseeding values.
You can inspect any file (such as the full installation log available in /var/log/syslog) with cat or less. You can edit any file with nano, including all files being installed onto the system. The root file system will be mounted on /target once the partitioning step of the installation process has completed.
Once network access has been configured, you can use wget and nc (netcat) to retrieve and export data over the network.
Once you click Continue from the main installer failure screen ( Figure 4.26, “Installation Step Failed”), you will be returned to a screen that you will normally never see (the Main Menu shown in Figure 4.28, “Main Menu of the Installer”), which allows you to launch one installation step after another. If you managed to fix the problem through the shell access (congratulations!) then you can retry the step that failed.
Figure 4.28. Main Menu of the Installer
If you are unable to resolve the problem, you might want to file a bug report. The report must then include the installer logs, which you can retrieve with the main menu's "Save debug logs" function. It offers multiple ways to export the logs, as shown in Figure 4.29, "Save Debug Logs (1/2)".
Figure 4.29. Save Debug Logs (1/2)
The most convenient method, and the one that we recommend, is to let the installer start a web server hosting the log files (Figure 4.30, "Save Debug Logs (2/2)"). You can then launch a browser from another computer on the same network and download all the log files and screenshots that you have taken with the button available on each screen.
Figure 4.30. Save Debug Logs (2/2)
