[ASUS ZenFone 8] bnsmb:
How to add additonal files to an TWRP image

The recovery image TWRP is very useful for the maintenance of the Android OS.

It's the Swiss Army knife for maintaining phones running the Android OS but sometimes you might miss some files in the TWRP recovery.

To add additional files to an TWRP image the instructions from the HowTo How to change files in the boot image can be used.

To make sure that the new files are also added to an TWRP installed in the boot partition additional steps are necessary.

To unpack and repack the TWRP image the Magisk binary magiskboot is necessary. This binary is part of TWRP so creating the new image should be done while the phone is booted from the TWRP image.

So to add additional files to an TWRP image do:

# boot into the TWRP image
#
adb reboot bootloader
sudo fastboot boot /data/backup/ASUS_ZENFONE8/twrp/twrp-3.7.0_12-0-I006D.img

Wait until booting the TWRP image is done and open an adb shell

adb shell

Create some directories for the work on the phone:

mkdir -p /data/develop/workdir/twrp/ramdisk

Copy the TWRP image file from your PC to the working directory on the phone

adb push twrp-3.7.0_12-0-I006D.img /data/develop/workdir/twrp

Unpack the image file:

cd /data/develop/workdir/twrp
magiskboot unpack -h twrp-3.7.0_12-0-I006D.img

e.g.

ASUS_I006D:/data/develop/workdir/twrp # magiskboot unpack -h twrp-3.7.0_12-0-I006D.img
Parsing boot image: [twrp-3.7.0_12-0-I006D.img]
HEADER_VER [3]
KERNEL_SZ [18627321]
RAMDISK_SZ [34811448]
OS_VERSION [99.87.36]
OS_PATCH_LEVEL [2099-12]
PAGESIZE [4096]
CMDLINE [twrpfastboot=1]
KERNEL_FMT [gzip]
RAMDISK_FMT [gzip]
VBMETA
ASUS_I006D:/data/develop/workdir/twrp #
ASUS_I006D:/data/develop/workdir/twrp # ls -ltr
total 324223
-rw-rw---- 1 u0_a119 media_rw 100663296 2022-10-12 13:38 twrp-3.7.0_12-0-I006D.img
-rw-r--r-- 1 root root 100663296 2022-10-28 15:55 new-boot.img
-rw-rw-rw- 1 root root 66 2022-10-28 16:14 header
-rw-r--r-- 1 root root 41943552 2022-10-28 16:14 kernel
-rw-r--r-- 1 root root 88384000 2022-10-28 16:14 ramdisk.cpio
drwxrwxrwx 2 root root 3452 2022-10-28 16:15 ramdisk
ASUS_I006D:/data/develop/workdir/twrp #

Unpack the ramdisk from the TWRP image:

cd /data/develop/workdir/twrp/ramdisk
cpio -idm <../ramdisk.cpio

The directory /data/develop/workdir/twrp/ramdisk now contains the contents of the ramdisk used for TWRP.

Now add the new files for the image to the directory /data/develop/workdir/twrp/ramdisk:

In this example we will add the binaries zsh, sqlite3, and vi.

cd /data/develop/workdir/twrp/ramdisk
cp ../../newfiles/sqlite3 ./system/bin/
cp ../../newfiles/zsh ./system/bin/
cp ../../newfiles/vi ./system/bin/

Note:

In case you want to add new binaries :

To check if the binaries will work in TWRP execute the binaries while the phone is booted from the original TWRP image. If the binaries need additional libraries not included in TWRP just also add them to the TWRP image into the directory ./system/lib64 of the image.

The next step is necessary to make sure that TWRP will copy the new files also to a TWRP installation in a boot partition:

For each new file add an entry to the files

./ramdisk-files.sha256sum

./ramdisk-files.txt

in the directory with the contents from the ramdisk.

The file ramdisk-files.txt contains the name and path of the directories files used in the ramdisk for the boot partition and the file ramdisk-files.sha256sum contains the checksum for each of the files for the ramdisk.

Note:

[iupdate 26.11.2023/bs] New directories for the image must also be added to the file ramdisk-files.txt.

If you change an existing file that is mentioned in the file ./ramdisk-files.sha256sum you must also correct the entry in that file.

So do for each new file:

echo <file_with_path_not_starting_with_a_dot_or_slash> >>ramdisk-files.txt ; done

sh256sum <file_with_path_startinge with_a_slash> >>ramdisk-files.sha256sum

e.g:

ASUS_I006D:/data/develop/workdir/twrp/ramdisk # for i in system/bin/sqlite3 system/bin/vi system/bin/zsh ; do sha256sum ./$i >>ramdisk-files.sha256sum ; echo "$i" >>ramdisk-files.txt ; done
ASUS_I006D:/data/develop/workdir/twrp/ramdisk #

Check the result.

ASUS_I006D:/data/develop/workdir/twrp/ramdisk # tail -4 ramdisk-files.sha256sum
8a8ff76cbda445f08ba3552598085089883f9d594cd7716e90f3411a8b82f8a0 ./twres/fonts/DroidSansMono.ttf
09fcec146d9ecba0f2a0b7362b52d2f87607a3c5760c94ba5fcd900e423e16f8 ./system/bin/sqlite3
3a221d10ffc275cadaf79fb1a00c39c9083ce672ea111205301e277091a04b51 ./system/bin/vi
354e415da42503ed4211907adf93ed8bfb14ce2e2d8418fcd7a3227873b4b53f ./system/bin/zsh
ASUS_I006D:/data/develop/workdir/twrp/ramdisk #
ASUS_I006D:/data/develop/workdir/twrp/ramdisk # tail -4 ramdisk-files.txt
twres/fonts/DroidSansMono.ttf
system/bin/sqlite3
system/bin/vi
system/bin/zsh
ASUS_I006D:/data/develop/workdir/twrp/ramdisk #

Correct the entry for the file ramdisk-files.txt in the file ramdisk-files.sha256sum :

cd /data/develop/workdir/twrp/ramdisk

cp ./ramdisk-files.sha256sum ./ramdisk-files.sha256sum.org
NEW_ENTRY="$( sha256sum ./ramdisk-files.txt )" && sed -i -e "s#.*\./ramdisk-files.txt#${NEW_ENTRY}#g" ./ramdisk-files.sha256sum

Check the entries in the file ramdisk-files.sha256sum

sha256sum --status -c ./ramdisk-files.sha256sum ; echo $?

If the output of that command is not 0 use

sha256sum -c ./ramdisk-files.sha256sum | grep -v OK

to get the entry with the invalid checksum. Fix the entry and check again.

Now repack the ramdisk:

cd /data/develop/workdir/twrp/ramdisk
find . | cpio -o >../ramdisk.cpio

And recreate the image file:

cd /data/develop/workdir/twrp
magiskboot repack twrp-3.7.0_12-0-I006D.img

e.g

ASUS_I006D:/data/develop/workdir/twrp # magiskboot repack twrp-3.7.0_12-0-I006D.img
Parsing boot image: [twrp-3.7.0_12-0-I006D.img]
HEADER_VER [3]
KERNEL_SZ [18627321]
RAMDISK_SZ [34811448]
OS_VERSION [99.87.36]
OS_PATCH_LEVEL [2099-12]
PAGESIZE [4096]
CMDLINE [twrpfastboot=1]
KERNEL_FMT [gzip]
RAMDISK_FMT [gzip]
VBMETA
Repack to boot image: [new-boot.img]
HEADER_VER [3]
KERNEL_SZ [18618540]
RAMDISK_SZ [37358888]
OS_VERSION [99.87.36]
OS_PATCH_LEVEL [2099-12]
PAGESIZE [4096]
CMDLINE [twrpfastboot=1]
ASUS_I006D:/data/develop/workdir/twrp #
The file new-boot.img contains the TWRP image with the additional files.:
ASUS_I006D:/data/develop/workdir/twrp # ls -ltr new-boot.img
-rw-r--r-- 1 root root 100663296 2022-10-28 16:28 new-boot.img
ASUS_I006D:/data/develop/workdir/twrp #

To test the image, rename the file, copy the file to an PC and boot the phone from the image:

mv new-boot.img twrp-3.7.0_12-0-I006D-enhanced.img

Execute on the PC:

adb pull /data/develop/workdir/twrp/twrp-3.7.0_12-0-I006D-enhanced.img
adb reboot bootloader
sudo fastboot boot twrp-3.7.0_12-0-I006D-enhanced.img

Connect via adb to the phone booted from the new TWRP image and check the result:

ASUS_I006D:/ # ls -l /system/bin/zsh /system/bin/sqlite3 /system/bin/vi
-rwxr-xr-x 1 root root 1714720 2022-10-28 16:19 /system/bin/sqlite3
-rwxr-xr-x 1 root root 1815152 2022-10-28 16:19 /system/bin/vi
-rwxr-xr-x 1 root root 2004808 2022-10-28 16:19 /system/bin/zsh
ASUS_I006D:/ #
ASUS_I006D:/ # /system/bin/sqlite3 --version
3.39.3 2022-09-05 11:02:23 4635f4a69c8c2a8df242b384a992aea71224e39a2ccab42d8c0b0602f1e826e8
ASUS_I006D:/ #
ASUS_I006D:/ # /system/bin/vi --version | head -1
VIM - Vi IMproved 8.1 (2018 May 18)
ASUS_I006D:/ #
ASUS_I006D:/ # /system/bin/zsh --version
zsh 5.9 (aarch64-unknown-linux-android)
ASUS_I006D:/ #

Advanced Usage

To be able to distinguish the new image from the original one you can change or add values in the file ./default.prop in the ramdisk for the image, e.g.:

# before creating the new ramdisk
cd /data/develop/workdir/twrp/ramdisk
echo "ro.product.type=enhanced" >>default.prop

Then when booted from the image you can check the new property, e.g.:

ASUS_I006D:/ # getprop ro.product.type
enhanced
ASUS_I006D:/ #

Notes:

The file default.prop is not listed in the checksum file ramdisk-files.sha256sum for the image.

Adding new files to ramdisk-files.sha256sum is not mandatory but recommended

To add files to the image that should not be copied to an TWRP installation in a boot partition just add them to the ramdisk but not to the file ramdisk-files.txt.

see also How to install TWRP via script

Update 28.11.2022 /bs

see als How to compile TWRP for the ASUS Zenfone 8

Udpate 26.11.2023 /bs

Added a hint that new directories for the image must also be added to the file ramdisk.txt.

Update 10.01.2024 /bs

If booting the phone from the new TWRP images ends in a ramdump or an endless loop:

It's important to use the correct version of the magiskboot binary to unpack and repack the image file. The magiskboot that is part of the TWRP image is always the correct version so I strongly recommend to create the new image file while the phone is booted from the TWRP image that should be extended.