Template:RFC Installation guide fastboot-no-lk2nd
Check out all pages using this template and feel free to discuss it in the gitlab issues.
This is an unofficial installation guide template for devices originally running Android with the fastboot flashing interface. It is partially inspired by the auto-generated LineageOS installation guides.
Any parameters are presented at the beginning of the section where they are used.
These are the defaults, which may differ from this preview:
{{RFC Installation guide fastboot-no-lk2nd | custom_vendor_unlock = No unlock codes are needed to enable unlocking on this device. | prebuilts = no | prebuilts_stable = no <!-- if pre-built images are available on the stable channel --> | codename = qemu-aarch64 <!-- except for links to pre-built images, which link to images for all devices by default --> | flash_mode = For instructions to enter your device's flashing mode, please look elsewhere or ask the device maintainer how to get to the flashing mode. | unlock_command = fastboot flashing unlock | ab_partitions = no | dynpart = no | dynpart_retrofit = no | dynpart_unsupported = no | dynpart_metadata = super | default_partition = the <code>userdata</code> partition | flash_dtbo = no | flash_dtbo_conditions = In addition to flashing the rootfs and boot images, you need to erase the DTBO. | flash_extra = | fastboot = yes | launch_installation = To boot into postmarketOS, run the command: $ fastboot reboot | recovery_faulty_usb = If a faulty USB connection is a major concern, reach out on [[Matrix and IRC]] to ask how to recover. | recovery_extra = ... }}
Pre-installation
In this section, you will obtain two partition images comprising a full installation of postmarketOS and prepare your device to be flashed with them.
Read through
Read the pre-installation and installation sections fully before taking any steps. One of the worst things that can happen is being left with no working OS on your device, postmarketOS or otherwise, and no volunteers immediately available on the Matrix and IRC channels. Plan ahead, fully understand the instructions, and decide on the details of your desired installation first.
Back up your data
Your data will be wiped when you lock or unlock your bootloader, and when you install to the userdata partition. Back up any important data somewhere safe.
Additionally, if you wish to use your device regardless of whether you perform a successful installation, be prepared to reinstall your current operating system.
Allow bootloader unlocking
| custom_vendor_unlock = No unlock codes are needed to enable unlocking on this device.
If you already have a custom ROM installed with the bootloader unlocked, skip this section. |
On Android, go to the
page in the Settings app. Click on the build number 7 times to enable developer settings. You will be prompted for your PIN or password.In the Settings main page, go to
, then . Enable .No unlock codes are needed to enable unlocking on this device.
Obtain an installation
A complete installation for this device can be created with pmbootstrap or downloaded from the web.
Obtaining pre-built images
| prebuilts = yes | prebuilts_stable = yes | codename = qemu-aarch64
Find a rootfs and boot image pair that suits your needs from the v23.06 release, or alternatively, from the edge channel.
The images are compressed, so decompress them with xz:
$ xz -d 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64.img.xz $ xz -d 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64-boot.img.xz
Building your own images with pmbootstrap
The pmbootstrap program can be used to create a custom installation when there are no pre-built images to fit your needs. You may wish to install a different UI, boot from netboot, test unfinished features, or install to a testing-category device.
See Pmbootstrap for instructions on how to set up pmbootstrap and prepare an installation for your device. You will be prompted for your sudo password.
Enter flashing mode
| flash_mode = For instructions to enter your device's flashing mode, please look elsewhere or ask the device maintainer how to get to the flashing mode.
For instructions to enter your device's flashing mode, please look elsewhere or ask the device maintainer how to get to the flashing mode.
In flashing mode, connect to your device with a USB cable.
Unlock the bootloader
| unlock_command = fastboot flashing unlock
If you already have a custom ROM installed with the bootloader unlocked, skip this section. |
Before flashing anything, you need to unlock the bootloader with this command:
$ fastboot flashing unlock
Follow the prompts on your device's screen to complete the operation. This will erase your data.
Choose a target partition
| ab_partitions = yes | dynpart = yes | dynpart_retrofit = yes | dynpart_unsupported = no | dynpart_metadata = super | default_partition = the <code>userdata</code> partition
The boot image must always be flashed to the boot
partition.
By default, pmbootstrap installs the rootfs image for your device to
the userdata
partition. The rootfs can be
installed to various places, depending on your needs:
The system
partition
This is a small partition which normally stores read-only system components for an Android-like OS. It is not intended for user data, but can be used for a dual-boot installation.
This partition needs to be flashed in fastbootd instead of the bootloader fastboot. Run this command while in the bootloader to enter fastbootd:
$ fastboot reboot fastboot
The super
partition
This is a small partition which normally contains dynamic partitions like
system
, vendor
, etc.
You cannot use pmbootstrap's built-in flasher for this partition. If you have a rootfs image from pmbootstrap, run:
$ pmbootstrap export
Then use the
/tmp/postmarketOS-export/qemu-aarch64.img
and
/tmp/postmarketOS-export/boot.img
images as prebuilt images.
To flash to this partition, add the --force
option to fastboot
when flashing the rootfs image further down.
The userdata
partition
This uses the majority of your device's internal storage and is normally used to store files for the user on an Android-like OS. Choose this partition if you want to use most of your device's storage.
Choose a target slot
| ab_partitions = yes
Flashing both images to mismatched slots will not prevent postmarketOS from booting, but will limit your opportunities to dual-boot. Before flashing anything, choose the slot that you wish to install to.
If you wish to dual-boot, you should select the opposite slot of the current one, so that you can continue running the most up-to-date version of your Android-like OS.
For example, if the current slot in the flashing interface is b:
$ fastboot getvar current-slot current-slot: b Finished. Total time: 0.013s
flash postmarketOS to slot a:
$ fastboot set_active a
Installation
| flash_extra = === Other partitions === Instructions for flashing to other necessary partitions go here. | recovery_extra = === Other device-specific situations === Any considerable risks that can happen in flashing mode go here. This should be populated to prevent users from getting stranded in flashing mode.
In this section, you will install postmarketOS on your device.
Erase the DTBO
| flash_dtbo = yes | flash_dtbo_conditions = In addition to flashing the rootfs and boot images, you need to flash the DTBO.
The device tree overlay, or DTBO, supplements the kernel's device tree. Android installs this by default.
In addition to flashing the rootfs and boot images, you need to erase the DTBO.
You can erase it with the following command:
$ fastboot erase dtbo
Other partitions
Instructions for flashing to other necessary partitions go here.
Flash the installation
Flashing a pre-built installation
| fastboot = yes
You can flash a pre-built installation with fastboot.
$ fastboot flash system_a 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64.img $ fastboot flash boot_a 19700101-0000-postmarketOS-v23.06-phosh-0.1-qemu-aarch64-boot.img
Flashing an installation created with pmbootstrap
There is a built-in flashing utility included in pmbootstrap. Flash with:
$ pmbootstrap flasher flash_rootfs # You can flash to the default partition $ pmbootstrap flasher flash_rootfs --partition system # or to a custom partition like system
Finally, flash the kernel:
$ pmbootstrap flasher flash_kernel
Launch the installation
| launch_installation = To boot into postmarketOS, run the command: $ fastboot reboot
To boot into postmarketOS, run the command:
$ fastboot reboot
Recovering from a faulty connection
| recovery_faulty_usb = If a faulty USB connection is a major concern, reach out on [[Matrix and IRC]] to ask how to recover.
You should ideally have a reliable USB connection.
If a faulty USB connection is a major concern, reach out on Matrix and IRC to ask how to recover.
Other device-specific situations
Any considerable risks that can happen in flashing mode go here. This should be populated to prevent users from getting stranded in flashing mode.
Maintenance
Updating
As with other distros, keep your system up-to-date with the apk
package manager.
Keeping your installation on a dual-boot setup
| ab_other_updates = yes
Android updates normally make use of both slots to apply updates seamlessly, but you may have postmarketOS installed on one of them.
If you have an Android-like OS installed that publishes regular updates that you want to apply, back up your installation before applying these updates.
Reboot to your Android-like OS, apply the update, and reboot again to complete it.
Then restore your postmarketOS installation on the opposite slot:
$ fastboot flash system_b postmarketOS-rootfs.img $ fastboot flash boot_b postmarketOS-boot.img
This will change the slot of your installation, so keep track of it.