Jump to content

Initramfs/Inspecting: Difference between revisions

From postmarketOS Wiki
Intgr (talk | contribs)
To enable functionality from initramfs-extra, run the following commands in the shell
Jakko (talk | contribs)
Enabling initramfr debug shell seems to be button "Volume Up", not "Volume Down".
 
(30 intermediate revisions by 21 users not shown)
Line 1: Line 1:
{{note|This is considered a '''security hole'''. Only use it for debugging, and uninstall the debug-shell hook afterwards.}}
{{subpages|Initramfs}}


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 enabling the '''debug-shell'''. 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 ===


<source lang="shell-session">
The debug shell can be enabled by adding <code>pmos.debug-shell</code> to the kernel cmdline, or by holding {{button|Volume Up}} during boot. If using the button method, you must wait until after the device bootloader finishes and Linux has started booting (usually the display flickering or displaying the tux penguins is a good indicator of this). If using a device with a keyboard, you may also press {{button|Left ctrl}}, though this has been reported to be somewhat unreliable due to when the keyboard drivers load.
$ pmbootstrap initfs hook_add debug-shell
 
$ pmbootstrap flasher boot # or however you flash/boot the kernel
If your device doesn't boot yet, and you're building an Android <code>boot.img</code>, this can be done by adding <code>deviceinfo_kernel_cmdline="pmos.debug-shell"</code> (or editing the existing option) to the deviceinfo file in pmaports and running <code>pmbootstrap flasher boot</code>.
(wait until the device booted up and you are connected to it)
 
For devices booting with GRUB or systemd-boot, hold {{button|e}} during boot to get to a prompt to edit the cmdline.
 
==== For all devices ====
 
In the device rootfs (either on a shell on your real device, or via <code>pmbootstrap chroot -r</code> [[Installation/Using_pmbootstrap|after building an image]], edit <code>/etc/deviceinfo</code>, uncomment <code>deviceinfo_kernel_cmdline_append</code> and add <code>pmos.debug-shell</code>, it should look something like the following:
 
<syntaxhighlight lang="shell-session">
/ # cat /etc/deviceinfo
# Override settings from /usr/share/deviceinfo/deviceinfo with this file.
# After modifying: Some settings require running "mkinitfs" as root and/or
# a reboot to apply.
# Reference: https://postmarketos.org/deviceinfo
 
# Examples:
deviceinfo_kernel_cmdline_append="pmos.debug-shell PMOS_NOSPLASH"
# deviceinfo_usb_network_function="ncm.usb0"
</syntaxhighlight>
 
Make sure you run <code>mkinitfs</code> after editing the file!
 
=== Using the debug shell ===
 
The debug shell will spawn a getty (an interactive shell) on all available/enabled consoles, if your device has a working USB port, it will also create a serial gadget device in addition to the usual network gadget. On Linux this can be accessed via any serial monitor, but picocom is suggested (it should be available via your package manager). Check <code>sudo dmesg -w</code> on your host PC and look for the most recently appeared '''ttyACM''' device, likely '''ttyACM0''', then connect as follows:
 
<syntaxhighlight lang="shell-session">
$ picocom -b 115200 /dev/ttyACM0
 
postmarketOS debug shell
https://postmarketos.org/debug-shell
 
  Device: QEMU amd64 (qemu-amd64)
  Kernel: 6.9.5-0-edge
  OS ver: edge
  initrd: 3.1.0-r1
 
Run 'pmos_continue_boot' to continue booting.
</syntaxhighlight>
 
You may also connect via telnet:
 
<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 14: Line 55:
Escape character is '^]'.
Escape character is '^]'.


Type 'pmos_continue_boot' to continue booting:
 
# echo "hello world"
postmarketOS debug shell
hello world
https://postmarketos.org/debug-shell
# pmos_continue_boot
 
Connection closed by foreign host.
  Device: QEMU amd64 (qemu-amd64)
</source>
  Kernel: 6.9.5-0-edge
  OS ver: edge
  initrd: 3.1.0-r1
 
Run 'pmos_continue_boot' to continue booting.
</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> can be made available by also installing the debug-shell hook (the <code>postmarketos-mkinitfs-hook-debug-shell</code> package) (see {{MR|1358}}).
To step through the boot process, you can execute commands in order listed in [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/blob/master/main/postmarketos-initramfs/init.sh postmarketos-initramfs/init.sh], starting with the line <code>mount_subpartitions</code> and below (everything above it was already executed before entering debug-shell). Make sure the commands are available, see the first 2 commands in the next section.
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 shell:
To enable functionality from <code>initramfs-extra</code>, run the following commands in the telnet shell:
<source lang="shell-session">
<syntaxhighlight lang="shell-session">
. init_functions.sh
# . /usr/share/misc/source_deviceinfo
mount_boot_partition
# mount_boot_partition /boot
extract_initramfs_extra $initramfs_extra
Mount boot partition (/dev/dm-0)
</source>
# extract_initramfs_extra /boot/initramfs-extra
Extract /boot/initramfs-extra
24128 blocks
</syntaxhighlight>
 
=== Disable the debug shell ===
 
If you added the debug-shell hook and are rebuilding the initramfs on your PC, uninstall it with


=== Additional programs ===
<syntaxhighlight lang="shell-session">
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}}).
$ pmbootstrap initfs hook_del debug-shell
$ pmbootstrap flasher flash_kernel
</syntaxhighlight>
 
Otherwise, simply remove the <code>pmos.debug-shell</code> argument from your kernel cmdline.


=== Tips and tricks ===
=== Tips and tricks ===
* [http://www.microhowto.info/howto/copy_a_file_from_one_machine_to_another_using_netcat.html copy files to/from the initramfs with <code>nc</code> while it is running]
* [[Initramfs development]] has more generalize information about working with initfs.
* [https://web.archive.org/web/20230924150444/www.microhowto.info/howto/copy_a_file_from_one_machine_to_another_using_netcat.html copy files to/from the initramfs with <code>nc</code> while it is running]
 
[[Category:Guide]]

Latest revision as of 20:03, 13 March 2025

This page explains how to connect to your device when it has booted to the initramfs by enabling the debug-shell. 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

The debug shell can be enabled by adding pmos.debug-shell to the kernel cmdline, or by holding Volume Up during boot. If using the button method, you must wait until after the device bootloader finishes and Linux has started booting (usually the display flickering or displaying the tux penguins is a good indicator of this). If using a device with a keyboard, you may also press Left ctrl, though this has been reported to be somewhat unreliable due to when the keyboard drivers load.

If your device doesn't boot yet, and you're building an Android boot.img, this can be done by adding deviceinfo_kernel_cmdline="pmos.debug-shell" (or editing the existing option) to the deviceinfo file in pmaports and running pmbootstrap flasher boot.

For devices booting with GRUB or systemd-boot, hold e during boot to get to a prompt to edit the cmdline.

For all devices

In the device rootfs (either on a shell on your real device, or via pmbootstrap chroot -r after building an image, edit /etc/deviceinfo, uncomment deviceinfo_kernel_cmdline_append and add pmos.debug-shell, it should look something like the following:

/ # cat /etc/deviceinfo
# Override settings from /usr/share/deviceinfo/deviceinfo with this file.
# After modifying: Some settings require running "mkinitfs" as root and/or
# a reboot to apply.
# Reference: https://postmarketos.org/deviceinfo

# Examples:
deviceinfo_kernel_cmdline_append="pmos.debug-shell PMOS_NOSPLASH"
# deviceinfo_usb_network_function="ncm.usb0"

Make sure you run mkinitfs after editing the file!

Using the debug shell

The debug shell will spawn a getty (an interactive shell) on all available/enabled consoles, if your device has a working USB port, it will also create a serial gadget device in addition to the usual network gadget. On Linux this can be accessed via any serial monitor, but picocom is suggested (it should be available via your package manager). Check sudo dmesg -w on your host PC and look for the most recently appeared ttyACM device, likely ttyACM0, then connect as follows:

$ picocom -b 115200 /dev/ttyACM0

postmarketOS debug shell
https://postmarketos.org/debug-shell

  Device: QEMU amd64 (qemu-amd64)
  Kernel: 6.9.5-0-edge
  OS ver: edge
  initrd: 3.1.0-r1

Run 'pmos_continue_boot' to continue booting.

You may also connect via telnet:

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


postmarketOS debug shell
https://postmarketos.org/debug-shell

  Device: QEMU amd64 (qemu-amd64)
  Kernel: 6.9.5-0-edge
  OS ver: edge
  initrd: 3.1.0-r1

Run '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 can be made available by also installing the debug-shell hook (the postmarketos-mkinitfs-hook-debug-shell package) (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_subpartitions and below (everything above it was already executed before entering debug-shell). Make sure the commands are available, see the first 2 commands in the next section.

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
# 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

If you added the debug-shell hook and are rebuilding the initramfs on your PC, uninstall it with

$ pmbootstrap initfs hook_del debug-shell
$ pmbootstrap flasher flash_kernel

Otherwise, simply remove the pmos.debug-shell argument from your kernel cmdline.

Tips and tricks