Introduction: The Immutable Android Challenge

Modern Android operating systems, particularly those leveraging A/B seamless updates and Project Treble, increasingly rely on an immutable system partition. This design choice enhances security, improves update reliability, and simplifies device management. However, it presents a significant hurdle for advanced users and developers who wish to apply persistent, low-level customizations to their device’s core system files. Modifying files directly on a read-only /system or /system_root partition is either impossible or requires disruptive, often temporary, workarounds.

Enter OverlayFS – a powerful Linux kernel feature that allows you to layer one filesystem over another. It presents a unified view where changes appear to be written to the lower, read-only filesystem, but are actually stored in an upper, writable directory. This article will guide you through the process of leveraging OverlayFS to achieve persistent system customizations on Android, making your modifications survive reboots and even system updates (with careful planning).

Understanding OverlayFS Fundamentals

OverlayFS operates on a simple yet effective principle: it combines multiple filesystems into a single, unified view. At its core, it uses:

• Lower Directory (lowerdir): This is your immutable, read-only system partition (e.g., /system_root). Files here are visible but cannot be modified directly.
• Upper Directory (upperdir): This is a writable directory, typically on a persistent storage location like /data. All modifications, additions, and deletions appear here.
• Work Directory (workdir): A temporary, empty directory also on a writable filesystem, required by OverlayFS for internal operations. It must be empty when the mount is performed.
• Merged Directory (mergedir): The final, unified view where you interact with your customized system. Files from the upperdir take precedence over those in the lowerdir.

When you read a file, OverlayFS first checks the upperdir. If found, it reads from there. If not, it falls back to the lowerdir. When you write, modify, or delete a file, the changes are directed to the upperdir. If a file exists in the lowerdir but not the upperdir, modifying it triggers a ‘copy_up’ operation, copying the original file to the upperdir before applying changes.

Prerequisites and Initial Setup

Before diving into OverlayFS, ensure you have the following:

• Rooted Android Device: Magisk is highly recommended for its systemless approach.
• Custom Recovery (Optional but Recommended): Such as TWRP, for emergency flashing or direct filesystem access.
• ADB and Fastboot Setup: For interacting with your device from a computer.
• Basic Linux Command Line Knowledge: Familiarity with mount, mkdir, cp, chmod, etc.

Identifying Your Target Partition

Modern Android devices often use a /system_root setup where /system is merely a symlink or bind mount within /system_root. You need to identify the actual partition containing the read-only system files. You can often find this using mount or by checking your device’s `fstab` entries:

adb shellmount | grep ' / 'adb shellcat /proc/mounts | grep ' /system'

Look for the root filesystem mount or the actual /system partition. For many devices, /system_root is the effective root of the immutable system. Let’s assume /system_root is our target for this guide.

Preparing Directories on /data

Since /data is always writable and persistent, we’ll create our OverlayFS directories there. Connect your device via ADB and open a shell:

adb shellsu# Ensure you have root permissions# Create parent directory for OverlayFS structuresmkdir -p /data/overlayfs# Create upper, work, and merged directoriesmkdir -p /data/overlayfs/upperdir/systemmkdir -p /data/overlayfs/workdir/systemmkdir -p /data/overlayfs/merged/system

The /system subdirectories are crucial because we’ll be overlaying on /system_root or /system directly. If your lowerdir is /system_root, you’d target /data/overlayfs/upperdir/system_root and /data/overlayfs/merged/system_root. For simplicity, we’ll target /system as the ‘visible’ system partition in this guide.

Manual OverlayFS Implementation (Test Only)

Before making it persistent, let’s test a manual mount. This should be done on a fresh boot with no existing modifications to the target system files.

adb shellsu# Unmount the existing /system partition (if it's a bind mount or similar)umount /system# Mount OverlayFS. Replace /system with your actual target if different.mount -t overlay overlay -olowerdir=/system,upperdir=/data/overlayfs/upperdir/system,workdir=/data/overlayfs/workdir/system /data/overlayfs/merged/system# Then, bind mount the merged directory to /systemmount -o bind /data/overlayfs/merged/system /system

Now, if you list the contents of /system, you’re actually seeing the merged view. You can test a customization:

# Create a test file inside the 'customized' systemecho 'Hello OverlayFS!' > /system/overlay_test.txt# Verify it's therecat /system/overlay_test.txt# Check if it appeared in your upperdir (it should)cat /data/overlayfs/upperdir/system/overlay_test.txt

This manual mount will disappear on reboot. To revert, simply reboot your device or manually unmount and remount the original system.

Automating Persistence with Magisk

The most robust way to make OverlayFS persistent on Android is through a Magisk module. Magisk’s post-fs-data.sh script executes very early in the boot process, allowing us to perform the necessary mounts before Android fully initializes.

Magisk Module Structure

A basic Magisk module for OverlayFS needs the following structure:

overlayfs_module/├── module.prop├── customize.sh  (Optional, for initial setup if needed)└── post-fs-data.sh

module.prop Example

module.prop contains module metadata:

id=overlayfs_customizername=OverlayFS Persistent System Customizerversion=v1.0versionCode=1author=Your NameDescription=Enables persistent system modifications via OverlayFS.

post-fs-data.sh Example

This is where the core logic resides. It will create directories (if they don’t exist) and perform the mount:

#!/system/bin/sh# Wait for /data to be fully availablewhile [ "$(getprop sys.boot_completed)" != "1" ]; do  sleep 1;done# Define pathsLOWER_DIR="/system" # Or /system_root depending on your deviceOVERLAY_ROOT="/data/overlayfs"UPPER_DIR="$OVERLAY_ROOT/upperdir/system"WORK_DIR="$OVERLAY_ROOT/workdir/system"MERGED_DIR="$OVERLAY_ROOT/merged/system"# Create directories if they don't exist (Magisk module install might already do this)mkdir -p "$UPPER_DIR"mkdir -p "$WORK_DIR"mkdir -p "$MERGED_DIR"# Ensure workdir is empty for each mountrm -rf "${WORK_DIR}/*" "${WORK_DIR}/.*" # Clear hidden files too# Unmount existing /system if it's a bind mount or similar (critical for some devices)if mount | grep -q "$MERGED_DIR on /system"; then  umount /systemfi# Perform the OverlayFS mountmount -t overlay overlay -olowerdir="$LOWER_DIR",upperdir="$UPPER_DIR",workdir="$WORK_DIR" "$MERGED_DIR"# Check if OverlayFS mount was successfulif [ $? -ne 0 ]; then  log -p E "OverlayFS: Failed to mount overlay."  exit 1fi# Now bind mount the merged directory to the actual /system locationumount /system # Unmount the original system if mountedread-onlymount -o bind "$MERGED_DIR" "/system"if [ $? -ne 0 ]; then  log -p E "OverlayFS: Failed to bind mount merged directory to /system."  exit 1fi# Log successlog -p I "OverlayFS: Persistent system customizations active!"

Building and Flashing the Module

1. Save the above files into the overlayfs_module directory.
2. Zip the entire overlayfs_module directory (ensure module.prop is at the root of the zip).
3. Transfer the zip to your Android device.
4. Open Magisk Manager, go to ‘Modules’, tap ‘Install from storage’, and select your zip file.
5. Reboot your device.

After reboot, any changes you make to /system will be stored in /data/overlayfs/upperdir/system and persist across reboots.

Example Customization: Modifying build.prop

Let’s say you want to change your device model name reported in settings or enable a hidden feature flag in build.prop. With OverlayFS active, you can directly edit it:

adb shellsu# Now you're interacting with the merged filesystemvi /system/build.prop # Or use a text editor of your choice# Make your desired changes, e.g., add or modify a propertyecho 'ro.product.custom_feature=true' >> /system/build.prop# Verify the changecat /system/build.prop | grep 'custom_feature'

These changes will now survive reboots. If you uninstall the Magisk module, the /data/overlayfs directories will remain, but the OverlayFS mount won’t occur, and your system will revert to its original immutable state (unless you delete the files in /data/overlayfs/upperdir/system manually).

Troubleshooting and Best Practices

• Bootloops: If your device bootloops after installing the module, it’s likely due to an incorrect mount command or a critical system file being corrupted. Boot into safe mode (if possible) or recovery, disable the Magisk module, and delete the /data/overlayfs directories.
• Performance: While OverlayFS is efficient, heavy I/O operations on overlaid files might introduce a slight performance overhead.
• Updates: System updates (especially A/B updates) typically replace the lowerdir. Your upperdir will remain, but conflicts can arise if the original file structure changes significantly. Always back up your upperdir before major updates.
• Security: Be extremely cautious about what you modify. Incorrect changes can destabilize your system or create security vulnerabilities.
• Cleaning Up: To remove customizations, delete the corresponding files from /data/overlayfs/upperdir/system. To completely revert to stock, uninstall the Magisk module and delete the entire /data/overlayfs directory.

Conclusion

OverlayFS provides an elegant and powerful solution for achieving persistent system-level customizations on immutable Android devices. By understanding its principles and carefully crafting a Magisk module, you can break free from the constraints of read-only partitions, tailoring your Android experience to your exact needs without compromising system integrity or update mechanisms. This expert guide equips you with the knowledge to harness this Linux kernel feature for advanced Android modding.