Jump to content

Initramfs/Inspecting: Difference between revisions

From postmarketOS Wiki
Susurrus (talk | contribs)
m Highlighting improvements and update <source> tags
Susurrus (talk | contribs)
Add method for using the debug shell when only flashing rootfs, reorganize the page to be more readable
Line 3: Line 3:
This page explains how to connect to your device when it has booted to the [[Initramfs-development|initramfs]] by installing the '''debug-shell''' hook. This is useful if you want to know more about the boot process, simply inspect the initramfs or if you want to debug why something doesn't work.
This page explains how to connect to your device when it has booted to the [[Initramfs-development|initramfs]] by installing the '''debug-shell''' hook. This is useful if you want to know more about the boot process, simply inspect the initramfs or if you want to debug why something doesn't work.


It is possible to enable a telnet daemon that gives you a shell this way:
=== Enable the debug shell ===


For devices that the kernel is flashed separately do the following:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap initfs hook_add debug-shell
$ pmbootstrap initfs hook_add debug-shell
$ pmbootstrap flasher flash_kernel # or however you flash/boot the kernel
$ pmbootstrap flasher flash_kernel # or however you flash/boot the kernel
(wait until the device booted up and you are connected to it)
</syntaxhighlight>
 
If you only need to flash <code>rootfs</code> for your device (e.g. you use <code>lk2nd</code>) do the following instead:
<syntaxhighlight lang="shell-session">
$ pmbootstrap install --add postmarketos-mkinitfs-hook-debug-shell
$ pmbootstrap flasher flash_rootfs
</syntaxhighlight>
 
=== Using the debug shell ===
<syntaxhighlight lang="shell-session">
$ telnet 172.16.42.1
$ telnet 172.16.42.1
Trying 172.16.42.1...
Trying 172.16.42.1...
Line 15: Line 25:


Type 'pmos_continue_boot' to continue booting:
Type 'pmos_continue_boot' to continue booting:
# echo "hello world"
hello world
# pmos_continue_boot
Connection closed by foreign host.
</syntaxhighlight>
</syntaxhighlight>


If the telnet command does not work out of the box, read [[connect via USB Networking in the Initramfs]].
If the telnet command does not work out of the box, read [[connect via USB Networking in the Initramfs]].
In the debug shell, the additional programs <code>evtest</code>, <code>fftest</code> and <code>fbdebug</code> are available (see {{github|1358}}).
To step through the boot process, you can execute commands in order listed in [https://gitlab.com/postmarketOS/pmaports/-/blob/master/main/postmarketos-initramfs/init.sh postmarketos-initramfs/init.sh], starting with the line <code>mount_boot_partition /boot</code> and below (everything above it was already executed before entering debug-shell).
To continue the boot process as normal, run the <code>pmos_continue_boot</code> command. This will close the telnet connection and continue the boot process.


=== Enable initramfs-extra ===
=== Enable initramfs-extra ===


To enable functionality from initramfs-extra, run the following commands in the telnet shell:
To enable functionality from <code>initramfs-extra</code>, run the following commands in the telnet shell:
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
# . /usr/share/misc/source_deviceinfo
# . /usr/share/misc/source_deviceinfo
Line 36: Line 48:
</syntaxhighlight>
</syntaxhighlight>


In general, while inspecting the initramfs, you can execute commands in order listed in [https://gitlab.com/postmarketOS/pmaports/-/blob/master/main/postmarketos-initramfs/init.sh postmarketos-initramfs/init.sh], starting with the line <code>mount_boot_partition /boot</code> and below (everything above it was already executed before entering debug-shell).
=== Disable the debug shell ===


=== Additional programs ===
For devices that flash the kernel partition separately:
After installing the <code>debug-shell</code> initramfs hook, the <code>evtest</code>, <code>fftest</code> and <code>fbdebug</code> programs are available in the initramfs ({{github|1358}}).


=== Deleting the debug shell ===
<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="text">
$ pmbootstrap initfs hook_del debug-shell
pmbootstrap initfs hook_del debug-shell
$ pmbootstrap flasher flash_kernel
</syntaxhighlight>
</syntaxhighlight>
For devices that only need to flash the <code>rootfs</code> re-run <code>pmbootstrap install</code> without adding the <code>postmarketos-mkinitfs-hook-debug-shell</code> package.


=== Tips and tricks ===
=== Tips and tricks ===

Revision as of 19:21, 26 October 2023

Note This is considered a security hole. Only use it for debugging, and uninstall the debug-shell hook afterwards.
Note TODO: add description about pmbootstrap initfs hooks_ls

This page explains how to connect to your device when it has booted to the initramfs by installing the debug-shell hook. This is useful if you want to know more about the boot process, simply inspect the initramfs or if you want to debug why something doesn't work.

Enable the debug shell

For devices that the kernel is flashed separately do the following:

$ pmbootstrap initfs hook_add debug-shell
$ pmbootstrap flasher flash_kernel # or however you flash/boot the kernel

If you only need to flash rootfs for your device (e.g. you use lk2nd) do the following instead:

$ pmbootstrap install --add postmarketos-mkinitfs-hook-debug-shell
$ pmbootstrap flasher flash_rootfs

Using the debug shell

$ telnet 172.16.42.1
Trying 172.16.42.1...
Connected to 172.16.42.1.
Escape character is '^]'.

Type 'pmos_continue_boot' to continue booting:

If the telnet command does not work out of the box, read connect via USB Networking in the Initramfs.

In the debug shell, the additional programs evtest, fftest and fbdebug are available (see #1358).

To step through the boot process, you can execute commands in order listed in postmarketos-initramfs/init.sh, starting with the line mount_boot_partition /boot and below (everything above it was already executed before entering debug-shell).

To continue the boot process as normal, run the pmos_continue_boot command. This will close the telnet connection and continue the boot process.

Enable initramfs-extra

To enable functionality from initramfs-extra, run the following commands in the telnet shell:

# . /usr/share/misc/source_deviceinfo
# . /init_functions.sh
# mount_boot_partition /boot
Mount boot partition (/dev/dm-0)
# extract_initramfs_extra /boot/initramfs-extra
Extract /boot/initramfs-extra
24128 blocks

Disable the debug shell

For devices that flash the kernel partition separately:

$ pmbootstrap initfs hook_del debug-shell
$ pmbootstrap flasher flash_kernel

For devices that only need to flash the rootfs re-run pmbootstrap install without adding the postmarketos-mkinitfs-hook-debug-shell package.

Tips and tricks