site  news  contact

Guidelines for debugging EasyOS

August 12, 2020 — BarryK

Making a start on writing this page...

EasyOS boots up from a boot-manager, such as rEFInd or Syslinux, which loads the Linux kernel, file 'vmlinuz', and the tiny complete Linux OS into RAM, file 'initrd'. The 'init' script inside 'initrd' is then run, which does a lot of setting-up, especially creating the aufs layered filesystem, consisting of a read-write folder on top and file 'easy.sfs' on the bottom. There is then a switch_root onto the aufs layers, and hence to the desktop.

The 'initrd' is actually a "initramfs", and the latter is the word you will most likely come across if searching online for help about how it works. It really is a complete tiny Linux OS, commandline only. If anything goes wrong at bootup, or if you want to modify bootup behaviour, you will want to get inside the 'initrd'.

Opening up and editing the 'initrd'

You download EasyOS as a compressed image file, named "easy-<version>[-<language>]-<architecture>.img.gz", for example "easy-2.3.8-amd64.img.gz". This will be uncompressed and written to a drive, most often a USB-stick. In Easy, we have a nice utility to handle this, "easydd", or you could use the "dd" utility. In the target drive, you will find two partitions, a "boot partition" and a "working partition".

The boot-partition contains files 'vmlinuz', 'initrd' and 'easy.sfs', as well as rEFInd and Syslinux boot managers (the former is for booting on UEFI-BIOS firmware PCs, the latter for traditional BIOS PCs). Here is a snapshot of the boot-partition, USB-stick, in this case it is /dev/sdb:


...files 'kbdmap.c32' to 'syslinux.cfg' are all for Syslinux, rEFInd boot manager files are inside the 'EFI' folder.

Opening up and editing the contents of 'initrd' is simplicity itself -- just click on it. You can find some more details here:

You can, for example, edit the 'init' script. Having made changes, just click on 'initrd' and it will be updated.

Debugging the 'initrd' at bootup

Perchance the 'initrd' doesn't do what you want, it is possible to dropout to a shell in the initramfs and poke around. If you examine the 'init' script, you will see that it recognises a kernel boot parameter of the format "qfix=<param1>[,<param2>...]", for example "qfix=nox" (which means bootup to commandline, without X. Note that you can have multiple, comma-separated parameters. At the time of writing, these are the recognised parameters:

Copy session to RAM & unmount all partitions
Copy session to RAM & disable drives
Remove permanent lockdown, normal bootup
Bootup to commandline, no X
Filesystem check of working-partition
Rollback to last snapshot
Rollback to pristine first-bootup
Initrd shell: nothing yet mounted
Initrd shell: boot & wkg partitions mounted
Initrd shell: before recovery & maintenance operations
Initrd shell: before version control
Initrd shell: before setting up SFS layers
Initrd shell: before moving mount points to layered f.s.
Initrd shell: just before switch_root

Any of the parameters can be implemented by appropriate entry in the Syslinux 'syslinux.cfg' or rEFInd 'refind.conf' configuration files. However, they can also be achieved via the Shutdown menu. This assumes you have a working desktop of course:


...this works by a different mechanism -- for Syslinux and rEFInd, you just do the normal bootup, the 'init' script looks for certain files in the boot-partition or working-partition. For example, if you had chosen "Reboot to initrd (developers only)" from the Shutdown menu, a file '.debug.flg' gets created, that the 'init' script will read.

Dropout to a shell in the 'initrd' is extremely useful for debugging the 'initrd' at bootup. If you choose that option in the Shutdown menu, there is a GUI selection-window:


A file .debug.flg will be created, with a parameter between "dropout1" and "dropout6" in it. "Reboot later" may be useful, as you could choose some other reboot option from the menu, such as "Reboot with rollback", and you will then be able to dropout to a shell in the initramfs to debug that mode of bootup.

If perchance X is not running, you can manually create .debug.flg, then reboot.

if the 'init' script hits an error, such that it is unable to continue bootup, it will also dropout to a shell in the initramfs. So, how to poke around inside the initramfs and attempt some debugging?

Debugging aids in the initramfs

the 'initrd' is based on Busybox, plus there are some other utilities, all statically linked. if you type "busybox<ENTER>" in the initramfs shell, you will see the list of applets available from busybox. Other utilities are, in /bin:
capsh, e2fsck, e4crypt, fdisk, hdparm, idump, mksquashfs, mp, shfm

These are binary executables, except for 'shfm' which is a shell script. 'shfm' is particularly interesting, as it is a console file manager, to make it easy to navigate around in the filesystem. Here is a snapshot of 'shfm', running in a terminal emulator on the desktop ('shfm' is also in the main filesystem, after switch-root):


...very simple, probably more accurately described as a "file browser" than a file manager. Keyboard navigation by the arrow keys, "?" for help, "q" to quit, "!" to spawn a shell. Right-arrow or ENTER key on any text file will launch the 'mp' text editor.

Although Busybox has a simple 'vi' editor, 'mp' is way better, with drop-down menus. Here is a snapshot, in a terminal emulator on the desktop ('mp' is also available in the main filesystem):


After having poked around in the initramfs, type "exit" to continue bootup, to the desktop.

Files created by the Shutdown menu

The choices in the Shutdown menu may create a file that the 'init' script will read at bootup. File '.debug.flg' has already been mentioned. Here is a list of all of them:

Exit to shell in initramfs
Copy session to RAM
Filesystem check of working-partition
Recompress 'easy'sfs' with gz

You can examine the 'init' script to see the expected content of these files. 

Tags: dev