|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | - | - |
| include/ | | 23-Mar-2024 | - | 396 | 158 |
| include_fstab/fstab/ | | 23-Mar-2024 | - | 128 | 81 |
| libdm/ | | 23-Mar-2024 | - | 3,117 | 2,104 |
| libfiemap/ | | 23-Mar-2024 | - | 4,124 | 2,914 |
| libfs_avb/ | | 23-Mar-2024 | - | 5,980 | 4,184 |
| liblp/ | | 23-Mar-2024 | - | 7,124 | 4,895 |
| libsnapshot/ | | 23-Mar-2024 | - | 11,594 | 8,456 |
| libstorage_literals/ | | 23-Mar-2024 | - | 86 | 56 |
| libvbmeta/ | | 23-Mar-2024 | - | 1,132 | 653 |
| tests/ | | 23-Mar-2024 | - | 3,166 | 2,634 |
| tools/ | | 23-Mar-2024 | - | 589 | 501 |
| .clang-format | D | 23-Mar-2024 | 291 | | |
| Android.bp | D | 23-Mar-2024 | 5.3 KiB | 229 | 221 |
| OWNERS | D | 23-Mar-2024 | 61 | 4 | 3 |
| README.overlayfs.md | D | 23-Mar-2024 | 5.6 KiB | 129 | 106 |
| TEST_MAPPING | D | 23-Mar-2024 | 312 | 23 | 22 |
| clean_scratch_files.cpp | D | 23-Mar-2024 | 728 | 23 | 5 |
| clean_scratch_files.rc | D | 23-Mar-2024 | 111 | 3 | 2 |
| file_wait.cpp | D | 23-Mar-2024 | 7.2 KiB | 236 | 174 |
| fs_mgr.cpp | D | 23-Mar-2024 | 81.4 KiB | 2,145 | 1,698 |
| fs_mgr_boot_config.cpp | D | 23-Mar-2024 | 4 KiB | 120 | 78 |
| fs_mgr_dm_linear.cpp | D | 23-Mar-2024 | 10 KiB | 280 | 211 |
| fs_mgr_format.cpp | D | 23-Mar-2024 | 6 KiB | 184 | 127 |
| fs_mgr_fstab.cpp | D | 23-Mar-2024 | 31.7 KiB | 898 | 685 |
| fs_mgr_overlayfs.cpp | D | 23-Mar-2024 | 52 KiB | 1,543 | 1,255 |
| fs_mgr_priv.h | D | 23-Mar-2024 | 4.1 KiB | 107 | 33 |
| fs_mgr_priv_boot_config.h | D | 23-Mar-2024 | 1.2 KiB | 33 | 12 |
| fs_mgr_remount.cpp | D | 23-Mar-2024 | 15.7 KiB | 444 | 363 |
| fs_mgr_roots.cpp | D | 23-Mar-2024 | 5.5 KiB | 192 | 145 |
| fs_mgr_slotselect.cpp | D | 23-Mar-2024 | 2.6 KiB | 77 | 39 |
| fs_mgr_vendor_overlay.cpp | D | 23-Mar-2024 | 5.1 KiB | 138 | 94 |
| fs_mgr_verity.cpp | D | 23-Mar-2024 | 16.6 KiB | 558 | 403 |
README.overlayfs.md
1Android OverlayFS Integration with adb Remount
2==============================================
3
4Introduction
5------------
6
7Users working with userdebug or eng builds expect to be able to remount the
8system partition as read-write and then add or modify any number of files
9without reflashing the system image, which is efficient for a development cycle.
10
11Limited memory systems use read-only types of file systems or logical resizable
12Android partitions (LRAPs). These file systems land system partition images
13right-sized, and have been deduped at the block level to compress the content.
14This means that a remount either isn’t possible, or isn't useful because of
15space limitations or support logistics.
16
17OverlayFS resolves these debug scenarios with the _adb disable-verity_ and
18_adb remount_ commands, which set up backing storage for a writable file
19system as an upper reference, and mount the lower reference on top.
20
21Performing a remount
22--------------------
23
24Use the following sequence to perform the remount.
25
26 $ adb root
27 $ adb disable-verity
28 $ adb reboot
29 $ adb wait-for-device
30 $ adb root
31 $ adb remount
32
33Then enter one of the following sequences:
34
35 $ adb shell stop
36 $ adb sync
37 $ adb shell start
38 $ adb reboot
39
40*or*
41
42 $ adb push <source> <destination>
43 $ adb reboot
44
45Note that you can replace these two lines in the above sequence:
46
47 $ adb disable-verity
48 $ adb reboot
49
50with this line:
51
52 $ adb remount -R
53
54**Note:** _adb remount -R_ won’t reboot if the device is already in the adb remount state.
55
56None of this changes if OverlayFS needs to be engaged.
57The decisions whether to use traditional direct file-system remount,
58or one wrapped by OverlayFS is automatically determined based on
59a probe of the file-system types and space remaining.
60
61### Backing Storage
62
63When *OverlayFS* logic is feasible, it uses either the
64**/cache/overlay/** directory for non-A/B devices, or the
65**/mnt/scratch/overlay** directory for A/B devices that have
66access to *LRAP*.
67It is also possible for an A/B device to use the system_<other> partition
68for backing storage. eg: if booting off system_a+vendor_a, use system_b.
69The backing store is used as soon as possible in the boot
70process and can occur at first stage init, or when the
71*mount_all* commands are run in init RC scripts.
72
73By attaching OverlayFS early, SEpolicy or init can be pushed and used after the exec phases of each stage.
74
75Caveats
76-------
77
78- Backing storage requires more space than immutable storage, as backing is
79 done file by file. Be mindful of wasted space. For example, defining
80 **BOARD_IMAGE_PARTITION_RESERVED_SIZE** has a negative impact on the
81 right-sizing of images and requires more free dynamic partition space.
82- The kernel requires **CONFIG_OVERLAY_FS=y**. If the kernel version is higher
83 than 4.4, it requires source to be in line with android-common kernels.
84 The patch series is available on the upstream mailing list and the latest as
85 of Sep 5 2019 is https://www.spinics.net/lists/linux-mtd/msg08331.html
86 This patch adds an override_creds _mount_ option to OverlayFS that
87 permits legacy behavior for systems that do not have overlapping
88 sepolicy rules, principals of least privilege, which is how Android behaves.
89 For 4.19 and higher a rework of the xattr handling to deal with recursion
90 is required. https://patchwork.kernel.org/patch/11117145/ is a start of that
91 adjustment.
92- _adb enable-verity_ frees up OverlayFS and reverts the device to the state
93 prior to content updates. The update engine performs a full OTA.
94- _adb remount_ overrides are incompatible with OTA resources, so the update
95 engine may not run if fs_mgr_overlayfs_is_setup() returns true.
96- If a dynamic partition runs out of space, making a logical partition larger
97 may fail because of the scratch partition. If this happens, clear the scratch
98 storage by running either either _fastboot flashall_ or _adb enable-verity_.
99 Then reinstate the overrides and continue.
100- For implementation simplicity on retrofit dynamic partition devices,
101 take the whole alternate super (eg: if "*a*" slot, then the whole of
102 "*system_b*").
103 Since landing a filesystem on the alternate super physical device
104 without differentiating if it is setup to support logical or physical,
105 the alternate slot metadata and previous content will be lost.
106- There are other subtle caveats requiring complex logic to solve.
107 Have evaluated them as too complex or not worth the trouble, please
108 File a bug if a use case needs to be covered.
109 - The backing storage is treated fragile, if anything else has
110 issue with the space taken, the backing storage will be cleared
111 out and we reserve the right to not inform, if the layering
112 does not prevent any messaging.
113 - Space remaining threshold is hard coded. If 1% or more space
114 still remains, OverlayFS will not be used, yet that amount of
115 space remaining is problematic.
116 - Flashing a partition via bootloader fastboot, as opposed to user
117 space fastbootd, is not detected, thus a partition may have
118 override content remaining. adb enable-verity to wipe.
119 - Space is limited, there is near unlimited space on userdata,
120 we have made an architectural decision to not utilize
121 /data/overlay/ at this time. Acquiring space to use for
122 backing remains an ongoing battle.
123 - First stage init, or ramdisk, can not be overriden.
124 - Backing storage will be discarded or ignored on errors, leading
125 to confusion. When debugging using **adb remount** it is
126 currently advised to confirm update is present after a reboot
127 to develop confidence.
128- File bugs or submit fixes for review.
129