Articles

[HOWTO] Troubleshoot a broken system

How to debug Porteus if something goes wrong

This document describes methods to recover a Porteus installation that was previously working on your system but, for one reason or another, it breaks or starts acting unpredictably or throwing errors. If you are having difficulties getting Porteus installed and running properly in the first place, you can try some of these methods, but resolving hardware issues or bugs inside the default Porteus is outside the scope of this HOWTO.

Many of us have, at one time or another, run into some kind of problem with our systems: A system that used to run flawlessly suddenly won't boot into the desktop, it hangs, something stops working, or the system starts throwing numerous errors. While this can be daunting and frustrating, the good news is that Porteus is well suited to finding these problems and resolving them. This is because Porteus is built out of read-only modules and has a well designed external (meaning non-live) file structure. To better understand the relationship between the live filesystem and the external files that are used to build it, please read this document.

Here are the steps to debug your system:

1. Boot without the 'changes=' cheatcode to check for issues related to saved changes.
2. Boot without loading any of the modules from your /modules directory.
3. Boot without loading anything from your rootcopy directory.
4. Disable magic folders if you are using them.
5. Clear out your trash folder.

A note before we begin:  You can boot your system using 'Always Fresh' mode from the bootloader menu in order to test it without saved changes, extra modules, rootcopy and magic folders all at once, and you may want to try this before following the steps below.  These steps isolate each of these areas where problems are likely to arise for troubleshooting purposes.  If your issues are not resolved by booting into 'Always Fresh' mode, then skip to the end of this document.

Step 1: Boot without the 'changes=' cheatcode to check for issues related to your saved changes.

One of the most common problems users run across are files in the live system that have been modified, overwritten, or deleted accidentally by the user. If you are using the 'changes=' cheatcode (the default boot option under Porteus when installed on writeable media like a flashdrive or hard drive), files that you delete or modify are saved outside of Porteus' base modules (in the /changes directory, a .dat file container or some other location specified by the user), and applied to your system when you boot up. Thus, the first step in debugging a broken system is to boot up without your saved changes to see if the system will function normally without them. To do this, you need start your computer and press the tab key when your boot menu comes up to gain access to the cheatcodes (a line of text will appear at the bottom of your screen). Use your arrow keys to move your cursor and delete the 'changes=(/porteus or /porteus/save.dat)' portion of that line of text, then press enter to start up Porteus. Now, test the behavior that was malfunctioning before. If the problem is resolved, then your saved changes were to blame. If your problem was not resolved, then proceed to Step 2. Otherwise, continue here:

One reason why your saved changes may be causing problems would be a corrupted .dat container. If your .dat container became corrupted, you can try to repair it using the 'Porteus save.dat Manager' tool. If your problem was not related to corruption in your .dat file, you can delete your changes entirely by deleting your .dat file container and creating a new one (or by deleting all of the files and folders in your /changes directory if you are saving your changes to a linux partition and using that directory rather than a .dat container), or you can rename your existing .dat container, create a new one, and selectively copy folders and files that you want to keep. Then reboot to check that you didn't import the file that caused the problem.

In order to access the files in a .dat file container, you can use the mloop command, e.g.:

mloop /mnt/sdb1/porteus/oldsave.dat

Your .dat container will be mounted at /mnt/loop/ and you can copy your files from that location to another temporary location, such as /tmp/oldsave/, then unmount the old container:

uloop

Finally, create a new .dat container, mount it again using mloop:

mloop /mnt/sdb1/porteus/newsave.dat

and copy the files you want to keep from /tmp/oldsave to /mnt/loop/.

If this didn't resolve your problem, then continue booting without saved changes, but proceed on to step 2.

Step 2: Boot without loading any of the modules from your /modules directory.

Sometimes there are conflicts between modules, modules that are out of date (e.g., converted from another OS) or modules that overwrite important files, etc. To minimize your risk of having issues, it is recommended that you use modules from the official Porteus repository, which can be installed via Porteus Package Manager.

In order to keep your extra modules from being activated at startup, you can boot up with the 'base_only' cheatcode.  This cheatcode makes sure that only the base modules, which are included in the Porteus ISO, are loaded into the system.  You can apply this cheatcode in the same manner that you removed the 'changes=' cheatcode in step 1:  press tab at the bootloader menu, and enter 'base_only' (without the quote marks) into the line of text that appears.  You should also remove the 'changes=' cheatcode while you are at it.  Press enter to boot into Porteus and then test to see if your issue has been resolved.  If it has, then a module conflict is to blame.  To sort out which module is to blame, you can start by selectively activating each of the modules in your /porteus/modules directory (starting with the modules you've added most recently), testing for the problem after each module is activated.  Hopefully this will lead you to the problematic module.  If your problem occurred prior to your desktop environment (KDE, LXDE or Xfce) starting up, then you can move all of your modules from your /porteus/modules folder to a different location, and then copy them back into /porteus/modules one by one, rebooting after each module (this time without the 'base_only' cheatcode).  This can be a painstaking process if you have many modules, but by starting with the most recent modules, you should be able to find the problematic module fairly quickly.

If booting with the 'base_only' cheatcode doesn't resolve your problem, then proceed to step 3.

Step 3: Boot without loading anything from your rootcopy directory.

If you're not familiar with the rootcopy folder, it is probably empty, and you can skip this step. To check, navigate to: /mnt/sdXN/porteus/rootcopy and look to see if there are any files there. You should have your file manager set to show hidden files, or use 'ls -a' if you are working from the command line. If you have any files present in your rootcopy, you can reboot using the 'norootcopy' cheatcode.  This will prevent Porteus from loading the files from this directory.

Similar to Step 2, if this resolved your issue, you can move all of the files out of your rootcopy directory into a new location, and then start moving things back into it, a few files at a time and rebooting (this time without the 'norootcopy' cheatcode) to check the system. Often, sorting through the files that you had in rootcopy will help you realize what the problem was.

Reboot and check again for the error. If the error has not been resolved by booting with 'norootcopy', 'base_only' and no saved changes, then proceed to Step 4.

Step 4: Disable magic folders if you are using them.

If you don't know what magic folders  are, then you don't need to worry about this step. Also, if you've renamed or deleted everything from your /rootcopy directory, this will have already disabled your magic folders. That said, if you have been using magic folders to save changes, date, etc., and you still have the configuration files for magic folders in your /rootcopy, you can boot the system with the 'nomagic' cheatcode and your magic folders will not be imported into your live filesystem.

Step 5: Clear out your trash folder.

When you delete files from your storage media from within Porteus, these files get moved to a hidden file in the root of your device, called .Trash-0. Unless you've deleted something on accident and want to recover it now, you should delete everything out of this folder. Navigate to /mnt/sdXN/.Trash-0 (where sdXN is the drive on which Porteus is installed) to find and delete these files. Anecdotally, doing this has seemed to help me at times, though I don't really understand how or why, as these files should not be inserted into your live filesystem. Nonetheless, it can't hurt to clean out these files. If nothing else, it will clear some space on your drive.

If you've followed my instructions to this point, you should be running a completely clean installation of Porteus: no saved changes, no extra modules, and no files other than the modules in the /porteus/base/ directory are being applied. If your problem persists, then it is likely a bug in the system (see HOWTO report a bug), corruption of your storage media or base modules, or a faulty download. If your storage media is formatted with a linux filesystem, you can use fsck to check for corruption. Also try downloading the Porteus ISO again, checking the md5sum (see this link for more info on that), extracting the porteus files again, and putting them on your storage media. You can rename your existing /boot and /porteus files to something like /oldboot and /oldporteus, and if your new install works, you can transfer your saved changes, modules, rootcopy, etc., from the old installation to the new one. If all else fails, you can back up your /boot and /porteus folders on another drive, format your storage media, and start with a fresh installation.

I hope this guide has been clear and helpful, and your issues have been resolved. Please visit our forum at

http://www.porteus.org/forum

if you have any questions or if you've been unable to resolve your issues. For questions or comments related to this document, see this thread on our forum.