Introduction: The Immutable Android Root Challenge

Modern Android versions, particularly those leveraging A/B seamless updates, feature an immutable root filesystem. This design enhances security and system integrity, preventing accidental or malicious modifications to core system files. While beneficial for stability, it presents a significant hurdle for advanced users, custom ROM developers, and security researchers who need to apply persistent, live patches or make system-level modifications without rebuilding the entire system image.

Traditionally, making persistent changes on a read-only root involves complex methods like system image modification, Magisk modules, or remounting partitions in read-write mode, which can be fragile or temporary. This article explores a powerful, kernel-level solution: OverlayFS. We’ll delve into how OverlayFS can create a writable, merged view of your Android system, allowing for on-the-fly modifications that can persist across reboots, all while keeping the original system partition pristine.

Understanding OverlayFS: A Union Filesystem

OverlayFS is a union mount filesystem that allows you to combine multiple filesystems (or directories) into a single, unified view. It operates with a ‘lower’ directory (typically read-only) and an ‘upper’ directory (writable). When you access the ‘merged’ view:

• Reads are performed from the upper directory if the file exists there; otherwise, they fall back to the lower directory.
• Writes or modifications to existing files in the lower directory trigger a ‘copy-up’ operation. The file is copied from the lower to the upper directory, and then the modification is applied to the copy in the upper directory.
• New files or directories are created directly in the upper directory.
• Deletions in the merged view are handled by creating ‘whiteout’ files in the upper directory, which effectively hide the corresponding files from the lower directory.

This copy-on-write mechanism ensures that the original lower filesystem remains untouched, providing a safe and reversible way to experiment with system changes.

Key OverlayFS Components:

• lowerdir: The read-only base filesystem (e.g., your Android /system partition).
• upperdir: A writable directory where all modifications, new files, and whiteouts are stored. This should be on a writable partition like /data.
• workdir: An empty, temporary directory on the same writable filesystem as upperdir. It’s used by OverlayFS for atomic operations during copy-up and other internal processes.
• mergeddir: The mount point where the combined view of lowerdir and upperdir is presented. This is where you’ll interact with your modified system.

Prerequisites for Live Patching Android

Before proceeding, ensure you have the following:

• Rooted Android Device: Essential for gaining the necessary permissions to mount filesystems. Magisk is the most common rooting solution.
• ADB Access: Android Debug Bridge for interacting with your device from a computer.
• BusyBox or Toybox: These utilities provide essential Linux commands like mount, mkdir, and cp, often with features specific to Android environments. Magisk usually installs its own set of these.
• Basic Linux Command-Line Knowledge: Familiarity with filesystem concepts and shell commands.

Step-by-Step: Setting Up OverlayFS on Android

Our goal is to create a new root environment (or a partial system overlay) where we can make changes that survive reboots. We’ll typically overlay the /system partition, or even the root filesystem / itself.

1. Identify the Lower Directory

First, identify the path to your read-only system partition. On most modern Android devices, /system is mounted read-only. We can check this using the mount command:

adb shellmount | grep '/system '

You’ll likely see something like /dev/block/dm-0 /system ext4 ro,seclabel,relatime,.... The `ro` confirms it’s read-only. The path will usually be `/system`.

2. Prepare Upper and Work Directories

We need a writable location for our upperdir and workdir. The /data partition is ideal as it’s writable and user-specific. Let’s create these directories:

adb shellsu -cm 'mkdir -p /data/local/overlay/upper'su -cm 'mkdir -p /data/local/overlay/work'su -cm 'mkdir -p /mnt/overlay_root' # The future merged directory

The su -cm prefix executes the command as root.

3. Mount OverlayFS

Now, we can mount the OverlayFS. Let’s assume your original read-only system partition is at /system, and our merged view will be at /mnt/overlay_root. If you want to overlay the entire root filesystem, you would use `/` as the `lowerdir`.

adb shellsu -cm 'mount -t overlay overlay -o lowerdir=/system,upperdir=/data/local/overlay/upper,workdir=/data/local/overlay/work /mnt/overlay_root'

If the command succeeds, you now have a writable view of /system at /mnt/overlay_root.

4. Verify and Apply a Live Patch

Let’s demonstrate a simple modification. We’ll modify the hosts file, which is typically located at /system/etc/hosts.

First, inspect the original file (optional, but good for verification):

adb shellsu -cm 'cat /system/etc/hosts'

Now, modify the file within our merged OverlayFS view. We’ll add a custom entry:

adb shellsu -cm 'echo "127.0.0.1 custom.domain" >> /mnt/overlay_root/etc/hosts'

Verify the change through the merged directory:

adb shellsu -cm 'cat /mnt/overlay_root/etc/hosts'

You should see your added line. Crucially, if you check the original /system/etc/hosts, it remains unchanged:

adb shellsu -cm 'cat /system/etc/hosts'

This demonstrates the copy-up mechanism: the modified hosts file now exists in /data/local/overlay/upper/etc/hosts, and the merged view prioritizes this version.

5. Ensuring Persistence Across Reboots

The OverlayFS mount will disappear upon reboot. To make it persistent, you need to execute the mount command automatically during boot. This can be achieved through various methods:

• Magisk Modules: The most robust and recommended way. A simple Magisk module can contain a post-fs-data.sh script that executes the mount command early in the boot process.
• init.d Scripts: If your custom ROM or kernel supports init.d, you can place a script there.
• Custom init Service: For more advanced scenarios, modifying the device’s init.rc files (requires unpacking and repacking boot images) to add a service to mount OverlayFS.

For a Magisk module, your customize.sh could create the necessary directories and then your post-fs-data.sh would contain the mount command. Remember to correctly set SELinux contexts for the upper and work directories if you encounter permission issues. Often, setting them to `u:object_r:system_data_file:s0` or similar based on `getcon /data` can resolve issues.

# Example post-fs-data.sh contentsu -c 'mkdir -p /data/local/overlay/upper'su -c 'mkdir -p /data/local/overlay/work'su -c 'mkdir -p /mnt/overlay_root'chcon -R u:object_r:system_data_file:s0 /data/local/overlaychcon u:object_r:rootfs:s0 /mnt/overlay_rootsu -c 'mount -t overlay overlay -o lowerdir=/system,upperdir=/data/local/overlay/upper,workdir=/data/local/overlay/work /mnt/overlay_root'

Note: The specific SELinux contexts might vary depending on your Android version and device. Always test thoroughly.

Advanced Considerations and Limitations

• SELinux Contexts: Incorrect SELinux contexts for upperdir, workdir, or mergeddir can cause
  
  Android Mobile Specs & Compare Directory

  Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!

  Compare Devices Specs →