1Android Overlayfs integration with adb remount 2============================================== 3 4Introduction 5------------ 6 7Users working with userdebug or eng builds expect to be able to 8remount the system partition as read-write and then add or modify 9any number of files without reflashing the system image, which is 10understandably efficient for a development cycle. 11Limited memory systems that chose to use readonly filesystems like 12*squashfs*, or *Logical Resizable Android Partitions* which land 13system partition images right-sized, and with filesystem that have 14been deduped on the block level to compress the content; means that 15either a remount is not possible directly, or when done offers 16little or no utility because of remaining space limitations or 17support logistics. 18 19*Overlayfs* comes to the rescue for these debug scenarios, and logic 20will _automatically_ setup backing storage for a writable filesystem 21as an upper reference, and mount overtop the lower. These actions 22will be performed in the **adb disable-verity** and **adb remount** 23requests. 24 25Operations 26---------- 27 28### Cookbook 29 30The typical action to utilize the remount facility is: 31 32 $ adb root 33 $ adb disable-verity 34 $ adb reboot 35 $ adb wait-for-device 36 $ adb root 37 $ adb remount 38 39Followed by one of the following: 40 41 $ adb stop 42 $ adb sync 43 $ adb start 44 $ adb reboot 45 46*or* 47 48 $ adb push <source> <destination> 49 $ adb reboot 50 51Note that the sequence above: 52 53 $ adb disable-verity 54 $ adb reboot 55 56*or* 57 58 $ adb remount 59 60can be replaced in both places with: 61 62 $ adb remount -R 63 64which will not reboot if everything is already prepared and ready 65to go. 66 67None of this changes if *overlayfs* needs to be engaged. 68The decisions whether to use traditional direct filesystem remount, 69or one wrapped by *overlayfs* is automatically determined based on 70a probe of the filesystem types and space remaining. 71 72### Backing Storage 73 74When *overlayfs* logic is feasible, it will use either the 75**/cache/overlay/** directory for non-A/B devices, or the 76**/mnt/scratch/overlay** directory for A/B devices that have 77access to *Logical Resizable Android Partitions*. 78The backing store is used as soon as possible in the boot 79process and can occur at first stage init, or at the 80mount_all init rc commands. 81 82This early as possible attachment of *overlayfs* means that 83*sepolicy* or *init* itself can also be pushed and used after 84the exec phases that accompany each stage. 85 86Caveats 87------- 88 89- Space used in the backing storage is on a file by file basis 90 and will require more space than if updated in place. As such 91 it is important to be mindful of any wasted space, for instance 92 **BOARD_<partition>IMAGE_PARTITION_RESERVED_SIZE** being defined 93 will have a negative impact on the overall right-sizing of images 94 and thus free dynamic partition space. 95- Kernel must have CONFIG_OVERLAY_FS=y and will need to be patched 96 with "*overlayfs: override_creds=off option bypass creator_cred*" 97 if kernel is 4.4 or higher. 98 The patch is available on the upstream mailing list and the latest as of 99 Feb 8 2019 is https://lore.kernel.org/patchwork/patch/1009299/. 100 This patch adds an override_creds _mount_ option to overlayfs that 101 permits legacy behavior for systems that do not have overlapping 102 sepolicy rules, principals of least privilege, which is how Android behaves. 103- *adb enable-verity* will free up overlayfs and as a bonus the 104 device will be reverted pristine to before any content was updated. 105 Update engine does not take advantage of this, will perform a full OTA. 106- Update engine may not run if *fs_mgr_overlayfs_is_setup*() reports 107 true as adb remount overrides are incompatible with an OTA resources. 108- For implementation simplicity on retrofit dynamic partition devices, 109 take the whole alternate super (eg: if "*a*" slot, then the whole of 110 "*system_b*"). 111 Since landing a filesystem on the alternate super physical device 112 without differentiating if it is setup to support logical or physical, 113 the alternate slot metadata and previous content will be lost. 114- If dynamic partitions runs out of space, resizing a logical 115 partition larger may fail because of the scratch partition. 116 If this happens, either fastboot flashall or adb enable-verity can 117 be used to clear scratch storage to permit the flash. 118 Then reinstate the overrides and continue. 119- File bugs or submit fixes for review. 120