Jump to content

Netboot: Difference between revisions

From postmarketOS Wiki
Resizing a netboot image: Add note about sector size in losetup command
m fix pages using deprecated source tags
Line 5: Line 5:
Make sure your kernel has the necessary kernel config options for netboot.
Make sure your kernel has the necessary kernel config options for netboot.


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap kconfig check --netboot $kernel-package-name
$ pmbootstrap kconfig check --netboot $kernel-package-name
</source>
</syntaxhighlight>


If not you need to [[Kernel_configuration|adjust your kernel config]] otherwise netboot won't work.
If not you need to [[Kernel_configuration|adjust your kernel config]] otherwise netboot won't work.
Line 15: Line 15:
First prepare a rootfs for your device. It is advisable to use the <code>--extra-space</code> argument to increase the size of your rootfs (in the example you will get 1000MB of extra space) as no image resize will happen at runtime.  Also, some devices are configured to be flashed with a sparse image, but that is not compatible with netboot currently.
First prepare a rootfs for your device. It is advisable to use the <code>--extra-space</code> argument to increase the size of your rootfs (in the example you will get 1000MB of extra space) as no image resize will happen at runtime.  Also, some devices are configured to be flashed with a sparse image, but that is not compatible with netboot currently.


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap --extra-space 1000 install --no-sparse
$ pmbootstrap --extra-space 1000 install --no-sparse
</source>
</syntaxhighlight>


Then prepare your boot.img and flash it to the device:
Then prepare your boot.img and flash it to the device:


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap initfs hook_add netboot
$ pmbootstrap initfs hook_add netboot
$ pmbootstrap flasher boot # or however you flash/boot the kernel
$ pmbootstrap flasher boot # or however you flash/boot the kernel
</source>
</syntaxhighlight>


After booting the device a network interface should appear over USB networking.
After booting the device a network interface should appear over USB networking.
Line 30: Line 30:
Finally you need to start the netboot server on your computer with the following command:
Finally you need to start the netboot server on your computer with the following command:


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap netboot serve
$ pmbootstrap netboot serve
</source>
</syntaxhighlight>


Make sure to open up tcp port 9999 on your computer's firewall so the phone can connect to your netboot service.
Make sure to open up tcp port 9999 on your computer's firewall so the phone can connect to your netboot service.
Line 44: Line 44:
You can replace the persisted rootfs image with a fresh image from <code>pmbootstrap install</code>:
You can replace the persisted rootfs image with a fresh image from <code>pmbootstrap install</code>:


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap netboot serve --replace
$ pmbootstrap netboot serve --replace
</source>
</syntaxhighlight>


=== Deleting all netboot images ===
=== Deleting all netboot images ===
Line 52: Line 52:
You can delete all persisted rootfs images:
You can delete all persisted rootfs images:


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap zap --netboot
$ pmbootstrap zap --netboot
</source>
</syntaxhighlight>


=== Resizing a netboot image ===
=== Resizing a netboot image ===
Line 61: Line 61:
The following example increases the size of the image <code>fairphone-fp4.img</code> by 1 GiB.
The following example increases the size of the image <code>fairphone-fp4.img</code> by 1 GiB.


<source lang="shell-session">
<syntaxhighlight lang="shell-session">
$ cd ~/.local/var/pmbootstrap/images_netboot/
$ cd ~/.local/var/pmbootstrap/images_netboot/
$ sudo bash -c "dd if=/dev/zero bs=1M count=1000 >> ./fairphone-fp4.img"
$ sudo bash -c "dd if=/dev/zero bs=1M count=1000 >> ./fairphone-fp4.img"
Line 72: Line 72:
$ sudo resize2fs /dev/loop0p2
$ sudo resize2fs /dev/loop0p2
$ sudo losetup --detach /dev/loop0
$ sudo losetup --detach /dev/loop0
</source>
</syntaxhighlight>


=== See also ===
=== See also ===

Revision as of 10:00, 19 March 2024

Netboot describes the means of booting a device when the rootfs is not on the device but accessed via network, in this implementation via USB networking.

Preparations

Make sure your kernel has the necessary kernel config options for netboot.

$ pmbootstrap kconfig check --netboot $kernel-package-name

If not you need to adjust your kernel config otherwise netboot won't work.

Usage

First prepare a rootfs for your device. It is advisable to use the --extra-space argument to increase the size of your rootfs (in the example you will get 1000MB of extra space) as no image resize will happen at runtime. Also, some devices are configured to be flashed with a sparse image, but that is not compatible with netboot currently.

$ pmbootstrap --extra-space 1000 install --no-sparse

Then prepare your boot.img and flash it to the device:

$ pmbootstrap initfs hook_add netboot
$ pmbootstrap flasher boot # or however you flash/boot the kernel

After booting the device a network interface should appear over USB networking.

Finally you need to start the netboot server on your computer with the following command:

$ pmbootstrap netboot serve

Make sure to open up tcp port 9999 on your computer's firewall so the phone can connect to your netboot service.

If you've never used netboot for the current device, then the image from the previous pmbootstrap install will get copied to $pmbootstrap_work/images_netboot/ and will persist normal pmbootstrap zap calls as you will probably have data in your rootfs.

Note: For android devices, you may need to run fastboot erase dtbo before flashing/booting the kernel. If you are running an a/b slot device, make sure to add the correct suffix (dtbo_a or dtbo_b).

Replacing persisted rootfs

You can replace the persisted rootfs image with a fresh image from pmbootstrap install:

$ pmbootstrap netboot serve --replace

Deleting all netboot images

You can delete all persisted rootfs images:

$ pmbootstrap zap --netboot

Resizing a netboot image

When you run out of space in your netbooted rootfs, you can increase the size of the image! The following example increases the size of the image fairphone-fp4.img by 1 GiB.

$ cd ~/.local/var/pmbootstrap/images_netboot/
$ sudo bash -c "dd if=/dev/zero bs=1M count=1000 >> ./fairphone-fp4.img"
$ sudo parted ./fairphone-fp4.img
(parted) resizepart 2 100%
(parted) quit
$ # If your device has deviceinfo_rootfs_image_sector_size set to e.g. 4096, add "--sector-size 4096" to the losetup command, otherwise the next commands will fail
$ sudo losetup --find --show --partscan ./fairphone-fp4.img
$ sudo e2fsck -f /dev/loop0p2 # verify that you will be operating on the correct loop device!
$ sudo resize2fs /dev/loop0p2
$ sudo losetup --detach /dev/loop0

See also

Troubleshooting

As of 01/31/2022, there are a couple known issues:

  • The initfs netboot hook currently expects a boot sector size of 512 bytes, but many android devices may be configured with a sector size of 4096 using the deviceinfo_rootfs_image_sector_size property. This will give an error like "unable to find boot partition". Using debug-shell (add to install with pmbootstrap initfs hook_add debug-shell) to modify the /etc/postmarketos-mkinitfs/hook/netboot.sh file and setting the nbd-client sector size to 4096 should fix this.
  • Some android devices may set deviceinfo_flash_sparse to true and this causes the generated block device to be unusable by netboot. You can pass "--no-sparse" to your pmbootstrap install command to override this.