Documentation for the script create_overlay_mount.sh

Last Update: 23.10.2025/bs

Contents


  1. Documentation for the script create_overlay_mount.sh
    1. Contents
    2. Introduction
    3. Author
    4. License
    5. History
    6. Details
      1. Usage examples
      2. Environment variables used by the script
      3. Using Magisk and overlay mounts in parallel
    7. Example disk images
      1. Virtual disk with a clang21 toolchain
      2. Virtual disk with a clang19 toolchain
      3. Virtual disk with Perl 5.42 and a minimal clang19 toolchain
    8. Test Environment
    9. Limitations
    10. Trouble Shooting
    11. Additional infos
      1. The Magisk Module magisk_overlayfs
    12. Downloads
    13. Links

 

Introduction


Since Android 10 many file systems in the Android OS are only mounted read-only and can no longer be mounted writable even by the root user. This is safe, but extremely unattractive.

One way to circumvent these restrictions is to install Magisk and Magisk modules. Magisk uses bind mounts to change or create files in the read-only file systems. This works very well to create or change binaries in /system/bin, for example. However, when creating the Magisk module you need to know which files are to be added or replaced.

To install new tools directly in Android via “make install”, for example, this does not work

A more flexible solution is the use of overlay mounts. As far as I know, overlay mounts have been supported in Android since Android 10 (at least partially).


Because overlay mounts are supported by Android out-of-the-box, Magisk is not mandatory to use overlay mounts in Android.

Therefore, I wrote a little script to manually create and use overlay mounts in Android on rooted devices:

create_overlay_mount.sh


The usage for the script is:

ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh -h

 create_overlay_mount.sh v1.3.0 - create one or more overlay mounts on a device running a rooted Android OS

 Usage:  create_overlay_mount.sh [-h|--help] [--version] [--verbose|-v] [--noselinux] [--selinux] [--initdisk|--format] [--details] [--short] [--active] [--nomagisk] [var=value]
                                 [help] [vars] [list] [test] [get] [undo] [diff] [get] [restore] [clean] [mount_only] [mount] [umount] [remount] [directory0] [... directory#] [default]

ASUS_I006D:/ #


The parameter can be entered in any order.


To view the detailed usage help use the parameter -v -h or help:


./create_overlay_mount.sh help
ASUS_I006D:/ $ /data/local/tmp/create_overlay_mount.sh help

 create_overlay_mount.sh v1.3.0 - create one or more overlay mounts on a device running a rooted Android OS

 Usage:  create_overlay_mount.sh [-h|--help] [--version] [--verbose|-v] [--noselinux] [--selinux] [--initdisk|--format] [--details] [--short] [--active] [--nomagisk] [var=value]
                                 [help] [vars] [list] [test] [get] [undo] [diff] [get] [restore] [clean] [mount_only] [mount] [umount] [remount] [directory0] [... directory#] [default]

 The parameter that neither start with a "-" or "/" nor contain a "=" are the action parameter that determine what is to be done.
 Only one action parameter for a run is allowed.

 Without an action parameter the script prints the short usage help. If one more directories are found in the parameter the default action is "mount".

 All parameter starting with a "/" are considered to be a filename or directory name.
 The parameter with the directory names are optional.

 The default directory list for the actions "mount", "diff", "get" and "undo" is the list of directories in the environment variable DIRS_TO_OVERLAY.
 The default directory list for the actions "test", "umount", and "remount" is the list of directories currently mounted to an overlay filesystem.

 There are no default values for the action "restore"; the actions "mount_only" and "list" ignore directory parameter.

 The actions "vars" and "help" only print help messages.

 If the variable DIRS_TO_OVERLAY is empty the script uses the hardcoded default value for this variable; that is: /system_ext  /product  /odm  /system

 "directory#" must be either "default", "none", or the fully qualified directory name of a directory.
 The value "none" deletes the current list of directories in the variable DIRS_TO_OVERLAY; the value "default" adds the default directories to the list
 of directories. The parameter can be used more than once.
 
 The known option parameter are:
 
 --version    print the script version and exit
 --verbose    print more messages
 --noselinux  disable SELinux at start of the script (SELinux is NOT enabled again by the script)
 --selinux    enable SELinux at start of the script (SELinux is NOT disabled again by the script)
 --initdisk   format the virtual disk before creating the overlay mounts; this will undo all previous changes in the filesystems
              Without this option the script never formats an existing virtual disk.
 --details    print more details
 --short      print only the important information
 --active     the tasks diff, get, and undo should work only on the currently mounted overlay filesystems
 --nomagisk   do not create temporary bind mounts for the Magisk binaries; without this parameter the script creates temporary
              bind mounts for the executables magisk, su, and resetprop if Magisk is installed and the bind mount
              should be created for the directory "/system".
              The bind mounts are created in the directory "/data/local/tmp"; to use another directory for the bind mounts set the environment variable
              BIND_MOUNT_TARGET_DIR="<directory_name>"
              To create bind mounts for additional files before creating the overlay mount for "/system", add the filenames to the variable FILES_TO_KEEP
              (see below for details); the files must exist and bind mounts for directories are not supported.

 The known action parameter are:

 help         print verbose usage help
 vars         print only the list of supported environment variables
 list         list directories mounted on overlay filesystems
 test         test write access to directories mounted on overlay filesystems;
              default is: test write access to all directories currently mounted on an overlay filesystems
 get          print the name of the backend used for a file or directory mounted on an overlay filesystem
 undo         delete all changes done in a directory with an overlay mount
              default is: delete all changes done for all directories in the environment variable DIRS_TO_OVERLAY (regardless of the mount status)
 diff         list the file changes for directories with overlay mounts
              default is: list the changes done for all directories in the environment variable DIRS_TO_OVERLAY (regardless of the mount status)
 restore      restore a file or directory mounted on an overlay filesystem

 mount_only   mount the virtual disk and exit

 mount        mount the overlays for the directories
 umount       umount the overlays for the directories; default is to umount all overlays
 remount      remount the overlay mounts

 clean        umount all overlay mounts and umount the virtual disk

 Other supported parameter:

 var=value sets the variable "var" to the value "value"
 

 The number of filenames in the variable FILES_TO_KEEP is not limited; the filenames must be separated by whitespaces or commas.
 
 The filenames in the variable FILES_TO_KEEP are interpreted by the script using these rules:

 - filenames without a slash are searched in the directory "/system/bin", e.g.  bash -> /system/bin/bash
 
 - filenames starting with "bin/" are searched in the directory "/system", e.g.  bin/sh -> /system/bin/sh
 
 - filenames starting with "./" are searched in the directory "/system", e.g.  ./etc/ssh/sshd_config  -> /system/./etc/ssh/sshd_config
 
 - fully qualified names are searched in "/",  e.g /system_ext/bin/rsync -> /system_ext/bin/rsync
 

 Notes
 
 Set the variable TRACE to any value before starting the script to execute it with "set -x"

 The detailed documentation for the script can be found here:

     http://bnsmb.de/android/Documentation_for_the_script_create_overlay_mount.sh.html


Supported environment variables:

Name                       Default Value
----                       -------------
IMAGE_FILE                 /data/local/tmp/image001
BASEDIR                    /dev/ov
DIRS_TO_OVERLAY            /system_ext /product /odm /system
FILESYSTEM_TO_USE          ext4
FILESYSTEM_SIZE            100m
MKFS_OPTIONS              
MOUNT_OPTIONS             
SELINUX_CONTEXT            u:object_r:system_file:s0
UMOUNT_WAIT_TIME           0
MOUNT                      /system/bin/mount
UMOUNT                     /system/bin/umount
LOSETUP                    /system/bin/losetup
MKFS                      
DD                         /system/bin/dd
FILES_TO_KEEP             
BIND_MOUNT_TARGET_DIR      /data/local/tmp

ASUS_I006D:/ $                                                                                                                                                        


Note:

The default for the MKFS binary is created dynamically based on the filesystem type to use:  mkfs.${FILESYSTEM_TO_USE}
----


The script create_overlay_mount.sh can be used to mount or umount an overlay filesystem for directories like /system , /system_ext, etc.
Overlay mounts for sub directories only like /system/priv-app or /system/priv-app/Shell are also possible (but see the note below).

For directories mounted with an overlay mount the script can be used

- to test the write access (script parameter "test")

- to list the files and directories changed or deleted (script parameter "diff")

- to undo all changes at once for one or more directories (script parameter "undo")

- to restore changed files or deleted files or directories (script parameter "restore")

- to print the current backend for each file or directory (script parameter "get")

- to remove all overlay mounts and the loop device (script parameter "clean")


See the details below for the usage examples of the script.



The script only requires binaries that are part of the standard Android OS (e.g. mount, umount, df, losetup, mkfs.ext4 )

Since there might be a "problem" using the umount binary and the sh binary in Android to umount the system directories (see here), I created a statically linked umount binary and a statically linked bash binary -- see the Downloads section below.


Please note that overlay mounts for sub directories such as /system/priv-app or /system/bin are not actually intended in the design for overlay mounts and can therefore lead to unexpected problems.


Author


Bernd Schemmer (Bernd.Schemmer@gmx.de)


License


License
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.



----

History


ChangeLog


23.10.2025

adapted the documentation to the script version 1.3.0
added the section about using Magisk and overlay mounts in parallel 
moved the infos about the Magisk Module for implementing overlay mounts to a separate section 


20.10.2025 /bs

added the documentation for the virtual disk with clang21 toolchain         
corrected a bug in the section Virtual disk with a clang19 toolchain :  -Wno-int-conversion instead of -Wno-int-conversioni  in the command to define the CFLAGS for compiling nano
added some more info about using overlay mounts and Magisk in parallel 


22.06.2025 /bs

Initial release

23.06.2025 /bs

corrected the infos about how to use the virtual disk from the Magisk Module with overlayfs 
added the hint about "lost" files in mounted sub directories 
added infos about overlay mounts for /vendor
the directory /vendor is not in the default list with directories for overlay mounts anymore.

24.06.2025 /bs

default mount point is now /dev/ov
mount points to sub directories in a directory are now remounted after creating the overlay mount

10.07.2025 /bs

added the documentation about the Example Disk images 


11.07.2025 /bs

minor bug fixes; add the instructions to compile nano.


----

Details


The script must be executed by the root user to create the overlay mounts. In addition, root access is necessary to create or change files or directories in the system directories mounted to overlay mounts.

The filesystem type used for the filesystem mounted on /data does not support overlay mounts. Therefore, the script creates a file, configures that file as virtual disk, formats the virtual disk with the ext4 filesystem and mounts the virtual disk. The filesystem on the virtual disks is than used as backend for the overlay mounts. If the virtual disk already exists, the script uses it again without formatting the virtual disk.

All changes in the directories mounted via overlay mounts are saved on the virtual disk. Therefore, the changes in the directories that are mounted via the overlay file system are persistent as long as the virtual disk used as the backend for the overlay mounts exists.

Overlay mounts can be created for most of the directories, except for directories in filesystems that do not support overlay mounts (like /data) and some directories with special meaning (like /dev, /sys, /proc detc.) or directories with a special SELinux context like /oem in the OmniROM.

To find out whether an overlay mount can be created for a directory, simply test it with the script. If it does not work, the script simply fails, but does not break anything.

Example
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  /oem
 The image file "/data/local/tmp/image001" already exists - there should already be a filesystem
Creating and mounting the directories for the overlay mount for "/oem" ...
 Creating the directory "/dev/ov/upper/oem" ...
 chcon: '/dev/ov/upper/oem' to u:object_r:oemfs:s0: Permission denied
 WARNING: Error changing the SELinux context for the directory "/dev/ov/upper/oem" to "u:object_r:oemfs:s0"
ERROR: Error creating the directory "/dev/ov/upper/oem" (RC=50)
 50|ASUS_I006D:/data/local/tmp 


----


If the script is executed without a parameter, the script prints the short usage help.

If there are one or more directories in the parameter but no action parameter, the default action is mount .

If the script is executed with an action parameter and one or more directories or files in the parameter, the requested action is done only for the directories or files in the parameter.

If the script is executed with an action parameter but without a directory, the action is done for the directories in the default directory list for that action.

The default directory lists used by the different actions are:

Action
 Default directories
 Comment
mount
 directories listed in the environment variable DIRS_TO_OVERLAY

diff
 directories listed in the environment variable DIRS_TO_OVERLAY
the action is done regardless of the mount status of the directories

use the option --active to process only the mounted overlay filesystems
undo
 directories listed in the environment variable DIRS_TO_OVERLAY
the action is done regardless of the mount status of the directories

use the option --active to process only the mounted overlay filesystems



test
 directories currently mounted with an overlay filesystem
umount
 directories currently mounted with an overlay filesystem
remount
directories currently mounted with an overlay filesystem
get
 directories listed in the environment variable DIRS_TO_OVERLAY use the option --active to process only the mounted overlay filesystems

This action can also be used for files.



restore
 n/a
 there are no default files or directories for this action

This action can also be used for files.
list
 n/a
 This action always lists all directories currently mounted with an overlay filesystem

Use the option --details to also list the backend directory and backend disk for each overlay mount



mount_only
 n/a


To explicitly request one of the actions only for the directories listed in the variable DIRS_TO_OVERLAY, use the parameter default.


The default value for the variable DIRS_TO_OVERLAY hard-coded in the script is:

/system_ext
/product
/odm
/system  

 

Usage examples



Note

Most of the examples below were executed in the OmniROM - the directories may look different in other Android distributions


To create the overlay mounts, use the script parameter mount.

Example output of executing the script with the parameter mount the first time:


/data/local/tmp/create_overlay_mount.sh mount
ASUS_I006D:/data/local/tmp # ./create_overlay_mount.sh  mount
Creating the image file "/data/local/tmp/image001" with the size 100m ...
1+0 records in
1+0 records out
104857600 bytes (100 M) copied, 0.098 s, 0.9 G/s
Creating a "ext4" filesystem on the image file "/data/local/tmp/image001" now ...
mke2fs 1.46.6 (1-Feb-2023)
Discarding device blocks: done                           
Creating filesystem with 102400 1k blocks and 25584 inodes
Filesystem UUID: 2b5c9bd3-a9eb-4977-acb3-7a5359e7ecfd
Superblock backups stored on blocks:
    8193, 24577, 40961, 57345, 73729

Allocating group tables: done                           
Writing inode tables: done                           
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done

Creating the directory "/dev/ov" ...
Mounting the imagefile "/data/local/tmp/image001" to "/dev/ov" ...
Creating the directory "/dev/ov/upper" ...
Creating the directory "/dev/ov/merged" ...
Creating the directory "/dev/ov/work" ...

Creating and mounting the directories for the overlay mount for "/system_ext" ...
Creating the directory "/dev/ov/upper/system_ext" ...
Creating the directory "/dev/ov/merged/system_ext" ...
Creating the directory "/dev/ov/work/system_ext" ...
Creating the overlay mount for "/system_ext" ...
Creating the bind mount "/system_ext"...
Checking the overlay mount for "/system_ext" ...

Creating and mounting the directories for the overlay mount for "/product" ...
Creating the directory "/dev/ov/upper/product" ...
Creating the directory "/dev/ov/merged/product" ...
Creating the directory "/dev/ov/work/product" ...
Creating the overlay mount for "/product" ...
Creating the bind mount "/product"...
Checking the overlay mount for "/product" ...

Creating and mounting the directories for the overlay mount for "/odm" ...
Creating the directory "/dev/ov/upper/odm" ...
Creating the directory "/dev/ov/merged/odm" ...
Creating the directory "/dev/ov/work/odm" ...
Creating the overlay mount for "/odm" ...
Creating the bind mount "/odm"...
Checking the overlay mount for "/odm" ...

Creating and mounting the directories for the overlay mount for "/system" ...
Creating the directory "/dev/ov/upper/system" ...
Creating the directory "/dev/ov/merged/system" ...
Creating the directory "/dev/ov/work/system" ...
Creating the overlay mount for "/system" ...
Creating the bind mount "/system"...
Checking the overlay mount for "/system" ...

Summary:
--------

4 overlay mount(s) created:

  /system_ext
  /product
  /odm
  /system

ASUS_I006D:/data/local/tmp #

----


To only create an overlay mount for the directory /odm_dlkm the script usage is

/data/local/tmp/create_overlay_mount.sh mount /odm_dlkm

or

/data/local/tmp/create_overlay_mount.sh /odm_dlkm

e.g. (in this example the file used as virtual disk already exists):

/data/local/tmp/create_overlay_mount.sh /odm_dlkm
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh /odm_dlkm
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem

Creating and mounting the directories for the overlay mount for "/odm_dlkm" ...
Creating the directory "/dev/ov/upper/odm_dlkm" ...
Creating the directory "/dev/ov/merged/odm_dlkm" ...
Creating the directory "/dev/ov/work/odm_dlkm" ...
Creating the overlay mount for "/odm_dlkm" ...
Creating the bind mount "/odm_dlkm"...
Checking the overlay mount for "/odm_dlkm" ...

Summary:
--------

1 overlay mount(s) created:

  /odm_dlkm

ASUS_I006D:/data/local/tmp #
 

----


To create an overlay mount for an additional directory, execute the script again, e.g. to create an additional overlay mount for the directory /vendor/etc:

/data/local/tmp/create_overlay_mount.sh /vendor/etc
130|ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh /vendor/etc
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem

Creating and mounting the directories for the overlay mount for "/vendor/etc" ...
Creating the directory "/data/local/tmp/ov/upper/vendor#etc" ...
Creating the directory "/data/local/tmp/ov/merged/vendor#etc" ...
Creating the directory "/data/local/tmp/ov/work/vendor#etc" ...
Creating the overlay mount for "/vendor/etc" ...
Creating the bind mount "/vendor/etc"...
Checking the overlay mount for "/vendor/etc" ...

Summary:
--------

1 overlay mount(s) created:

  /vendor/etc

ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh list
Directories mounted on an overlay filesystem

/system_ext
/product
/odm
/system
/vendor/etc


ASUS_I006D:/data/local/tmp # 


----


Directory parameters for the script overwrite the variable DIRS_TO_OVERLAY. To create an overlay mount for the default directories and additional directories, use the parameter default, e.g.: to create overlay mounts for the default directories and the directories /vendor/app and /vendor/bin, execute:

/data/local/tmp/create_overlay_mount.sh default /vendor/app /vendor/bin
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh default /vendor/app /vendor/bin
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem

Creating and mounting the directories for the overlay mount for "/system_ext" ...
Creating the overlay mount for "/system_ext" ...
Creating the bind mount "/system_ext"...
Checking the overlay mount for "/system_ext" ...

Creating and mounting the directories for the overlay mount for "/product" ...
Creating the overlay mount for "/product" ...
Creating the bind mount "/product"...
Checking the overlay mount for "/product" ...

Creating and mounting the directories for the overlay mount for "/odm" ...
Creating the overlay mount for "/odm" ...
Creating the bind mount "/odm"...
Checking the overlay mount for "/odm" ...

Creating and mounting the directories for the overlay mount for "/system" ...
Creating the overlay mount for "/system" ...
Creating the bind mount "/system"...
Checking the overlay mount for "/system" ...

Creating and mounting the directories for the overlay mount for "/vendor/app" ...
Creating the overlay mount for "/vendor/app" ...
Creating the bind mount "/vendor/app"...
Checking the overlay mount for "/vendor/app" ...

Creating and mounting the directories for the overlay mount for "/vendor/bin" ...
Creating the overlay mount for "/vendor/bin" ...
Creating the bind mount "/vendor/bin"...
Checking the overlay mount for "/vendor/bin" ...

Summary:
--------

6 overlay mount(s) created:

  /system_ext
  /product
  /odm
  /system
  /vendor/app
  /vendor/bin

ASUS_I006D:/data/local/tmp #

----


Note that it is not possible to create an overlay mount for a subdirectory if there is already an overlay mount for the parent directory in place.

For example, if there is an overlay mount for /system in place, you cannot create an overlay mount for /system/etc. Creating an overlay mount for /system if there is already a overlay mount for a sub directory as /system/etc is also not possible with this script.




To list the overlay mounts created by the script use the parameter list :

/data/local/tmp/create_overlay_mount.sh list

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh list
Directories mounted on an overlay filesystem

/system_ext
/product
/odm
/system
/vendor/app
/vendor/bin


ASUS_I006D:/data/local/tmp #

 
# Use the option parameter --details to print more details:

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh list --details
Directories mounted on an overlay filesystem

Directory        Backend Directory
---------        -----------------
/system_ext      /dev/ov (Virtual disk: /data/local/tmp/image001)
/product         /dev/ov (Virtual disk: /data/local/tmp/image001)
/odm             /dev/ov (Virtual disk: /data/local/tmp/image001)
/system          /dev/ov (Virtual disk: /data/local/tmp/image001)
/vendor/app      /dev/ov (Virtual disk: /data/local/tmp/image001)
/vendor/bin      /dev/ov (Virtual disk: /data/local/tmp/image001)

ASUS_I006D:/data/local/tmp #

----


To get the directories used for new files for the current active overlay mounts use the parameter get with the option --active:

/data/local/tmp/create_overlay_mount.sh get --active
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh get --active
/dev/ov/upper/system_ext # /system_ext
/dev/ov/upper/product # /product
/dev/ov/upper/odm # /odm
/dev/ov/upper/system # /system
/dev/ov/upper/vendor#app # /vendor/app
/dev/ov/upper/vendor#bin # /vendor/bin

ASUS_I006D:/data/local/tmp #


# or only for specific directories:

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh get --active /system
/dev/ov/upper/system # /system

ASUS_I006D:/data/local/tmp #

----


To test the write access in the directories with overlay mounts use the parameter test:

/data/local/tmp/create_overlay_mount.sh test
ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh test
Testing the write access for directories mounted on overlay filesystems ...


Testing write access for the directory "/system_ext" ...
  OK, the write access to the directory "/system_ext" works

Testing write access for the directory "/product" ...
  OK, the write access to the directory "/product" works

Testing write access for the directory "/odm" ...
  OK, the write access to the directory "/odm" works

Testing write access for the directory "/system" ...
  OK, the write access to the directory "/system" works

Testing write access for the directory "/odm_dlkm" ...
  OK, the write access to the directory "/odm_dlkm" works

ASUS_I006D:/ #

----


To list the backend used for a file or directory use the parameter get

The format of the output of the action get is

backend_file # original_file # comment

e.g.

/data/local/tmp/ov/upper/system_ext/etc/passwd # /system_ext/etc/passwd # the file was changed


Entries for deleted files may be files, directories, or anything else. As long as the overlay mount and the bind mount is in place, this info is not available (see below for a workaround for this problem).




Example output of the script with the parameter get:

/data/local/tmp/create_overlay_mount.sh  get  /system_ext/priv-app/OmniControl/testdir

----
commands to create the test environment
# instructions to create the test env
 #
 cd /system_ext/
 mkdir -p ./priv-app/OmniControl/testdir/testdir2
 touch ./priv-app/OmniControl/testdir/testdir2/testfile3
 touch  ./priv-app/OmniControl/testdir/testfile2
 touch ./priv-app/OmniControl/testfile1
 rm ./priv-app/OmniControl/oat/arm64/OmniControl.odex
rm ./priv-app/OmniControl/oat/arm64/OmniControl.vdex                                                                                                                                                                       
----

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh diff /system_ext
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/system_ext" ...
There is currently an overlay mounted for the directory "/system_ext"
File changes in the directory "/system_ext" :

./priv-app
./priv-app/OmniControl
./priv-app/OmniControl/oat
./priv-app/OmniControl/oat/arm64
./priv-app/OmniControl/testdir
./priv-app/OmniControl/testdir/testdir2
./priv-app/OmniControl/testdir/testdir2/testfile3
./priv-app/OmniControl/testdir/testfile2
./priv-app/OmniControl/testfile1

Files or directories deleted in the directory "/system_ext" :

./priv-app/OmniControl/oat/arm64/OmniControl.odex
./priv-app/OmniControl/oat/arm64/OmniControl.vdex


ASUS_I006D:/system_ext #                                                                                    

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/testdir
/dev/ov/upper/system_ext/priv-app/OmniControl/testdir # /system_ext/priv-app/OmniControl/testdir

ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/testdir/testdir2      
/dev/ov/upper/system_ext/priv-app/OmniControl/testdir/testdir2 # /system_ext/priv-app/OmniControl/testdir/testdir2

ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/testdir/testdir2/testfile3
/dev/ov/upper/system_ext/priv-app/OmniControl/testdir/testdir2/testfile3 # /system_ext/priv-app/OmniControl/testdir/testdir2/testfile3 # the file was changed

ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/testdir/testfile2
/dev/ov/upper/system_ext/priv-app/OmniControl/testdir/testfile2 # /system_ext/priv-app/OmniControl/testdir/testfile2 # the file was changed

ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/testfile1
/dev/ov/upper/system_ext/priv-app/OmniControl/testfile1 # /system_ext/priv-app/OmniControl/testfile1 # the file was changed

ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/testfile5
/dev/ov/upper/system_ext/priv-app/OmniControl/testfile5 # /system_ext/priv-app/OmniControl/testfile5 # the file was not yet changed or deleted

ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/oat/arm64/OmniControl.odex
/dev/ov/upper/system_ext/priv-app/OmniControl/oat/arm64/OmniControl.odex # /system_ext/priv-app/OmniControl/oat/arm64/OmniControl.odex # the file/directory was deleted


ASUS_I006D:/system_ext #

ASUS_I006D:/system_ext # /data/local/tmp/create_overlay_mount.sh get /system_ext/priv-app/OmniControl/oat/arm64/OmniControl.vdex
/dev/ov/upper/system_ext/priv-app/OmniControl/oat/arm64/OmniControl.vdex # /system_ext/priv-app/OmniControl/oat/arm64/OmniControl.vdex # the file/directory was deleted

ASUS_I006D:/system_ext #


----


The options --short and --details can be used to change the information printed by the action get:



Other example for the action get
----
commands to create the test environments
# instructions to create the test env
 #
 /data/local/tmp/create_overlay_mount.sh umount /odm
 /data/local/tmp/create_overlay_mount.sh /odm/etc /vendor

touch /odm/etc/passwd
 touch /odm/etc/selinux/precompiled_sepolicy
 rm /odm/etc/group
touch /vendor/etc/vmmgr.conf
----

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh list
Directories mounted on an overlay filesystem

/vendor
/odm/etc


ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  diff /odm/etc /vendor
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/odm/etc" ...
There is currently an overlay mounted for the directory "/odm/etc"
File changes in the directory "/odm/etc" :

./passwd
./selinux
./selinux/precompiled_sepolicy

Files or directories deleted in the directory "/odm/etc" :

./group


 ----------------------------------------------------------------------
List the changes in the directory "/vendor" ...
There is currently an overlay mounted for the directory "/vendor"
File changes in the directory "/vendor" :

./etc
./etc/vmmgr.conf

Files or directories deleted in the directory "/vendor" :



ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /vendor /vendor/etc /vendor/etc/vmmgr.conf  /odm /odm/etc /odm/etc/passwd  /odm/etc/group  /vendor/etc/ueventd.rc /odm/etc/build.prop
/dev/ov/upper/vendor # /vendor
/dev/ov/upper/vendor/etc # /vendor/etc
/dev/ov/upper/vendor/etc/vmmgr.conf # /vendor/etc/vmmgr.conf # the file was changed
# There is no overlay mount active for "/odm" in the backend "/dev/ov"
/dev/ov/upper/odm#etc # /odm/etc
/dev/ov/upper/odm#etc/passwd # /odm/etc/passwd # the file was changed
/dev/ov/upper/odm#etc/group # /odm/etc/group # the file/directory was deleted
/dev/ov/upper/vendor/etc/ueventd.rc # /vendor/etc/ueventd.rc # the file was not yet changed or deleted
/dev/ov/upper/odm#etc/build.prop # /odm/etc/build.prop # the file was not yet changed or deleted

ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /vendor /vendor/etc /vendor/etc/vmmgr.conf  /odm /odm/etc /odm/etc/passwd  /odm/etc/group  /vendor/etc/ueventd.rc /odm/etc/build.prop    --short
/dev/ov/upper/vendor
/dev/ov/upper/vendor/etc
/dev/ov/upper/vendor/etc/vmmgr.conf
# There is no overlay mount active for "/odm" in the backend "/dev/ov"
/dev/ov/upper/odm#etc
/dev/ov/upper/odm#etc/passwd
/dev/ov/upper/odm#etc/group
/dev/ov/upper/vendor/etc/ueventd.rc
/dev/ov/upper/odm#etc/build.prop

ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /vendor /vendor/etc /vendor/etc/vmmgr.conf  /odm /odm/etc /odm/etc/passwd  /odm/etc/group  /vendor/etc/ueventd.rc /odm/etc/build.prop    --details
drwxr-xr-x 3 root shell u:object_r:vendor_file:s0  1024 2025-06-25 10:53 /dev/ov/upper/vendor # /vendor
drwxr-xr-x 2 root shell u:object_r:vendor_configs_file:s0  1024 2009-01-01 01:00 /dev/ov/upper/vendor/etc # /vendor/etc
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  25 2025-06-25 10:55 /dev/ov/upper/vendor/etc/vmmgr.conf # /vendor/etc/vmmgr.conf # the file was changed
# There is no overlay mount active for "/odm" in the backend "/dev/ov"
drwxr-xr-x 3 root root u:object_r:vendor_configs_file:s0  1024 2025-06-25 10:55 /dev/ov/upper/odm#etc # /odm/etc
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  0 2025-06-25 10:55 /dev/ov/upper/odm#etc/passwd # /odm/etc/passwd # the file was changed
c--------- 1 root root u:object_r:vendor_configs_file:s0  0,   0 2025-06-25 10:55 /dev/ov/upper/odm#etc/group # /odm/etc/group # the file/directory was deleted
/dev/ov/upper/vendor/etc/ueventd.rc # /vendor/etc/ueventd.rc # the file was not yet changed or deleted
/dev/ov/upper/odm#etc/build.prop # /odm/etc/build.prop # the file was not yet changed or deleted

ASUS_I006D:/data/local/tmp #

127|ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /vendor /vendor/etc /vendor/etc/vmmgr.conf  /odm /odm/etc /odm/etc/passwd  /odm/etc/group  /vendor/etc/ueventd.rc /odm/etc/build.prop    --details --short
drwxr-xr-x 3 root shell u:object_r:vendor_file:s0  1024 2025-06-25 10:53 /dev/ov/upper/vendor
drwxr-xr-x 2 root shell u:object_r:vendor_configs_file:s0  1024 2009-01-01 01:00 /dev/ov/upper/vendor/etc
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  25 2025-06-25 10:55 /dev/ov/upper/vendor/etc/vmmgr.conf
# There is no overlay mount active for "/odm" in the backend "/dev/ov"
drwxr-xr-x 3 root root u:object_r:vendor_configs_file:s0  1024 2025-06-25 10:55 /dev/ov/upper/odm#etc
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  0 2025-06-25 10:55 /dev/ov/upper/odm#etc/passwd
c--------- 1 root root u:object_r:vendor_configs_file:s0  0,   0 2025-06-25 10:55 /dev/ov/upper/odm#etc/group
/dev/ov/upper/vendor/etc/ueventd.rc
/dev/ov/upper/odm#etc/build.prop

ASUS_I006D:/data/local/tmp #

----


To umount all overlay mounts created by the script use the parameter umount

/data/local/tmp/create_overlay_mount.sh umount
ASUS_I006D:/data/local/tmp #  /data/local/tmp/create_overlay_mount.sh  umount
/data/local/tmp/create_overlay_mount.sh: line 2416: LogInfoVar: command not found
/data/local/tmp/create_overlay_mount.sh: line 2417: LogInfoVar: command not found
/data/local/tmp/create_overlay_mount.sh: line 2418: LogInfoVar: command not found
/data/local/tmp/create_overlay_mount.sh: line 2419: LogInfoVar: command not found
/data/local/tmp/create_overlay_mount.sh: line 2420: LogInfoVar: command not found
Umounting the bind mounts ...
/data/local/tmp/create_overlay_mount.sh: line 1434: LogInfoVar: command not found
Umounting the bind mount  "/system_ext" ...
/data/local/tmp/create_overlay_mount.sh: line 1434: LogInfoVar: command not found
Umounting the bind mount  "/product" ...
/data/local/tmp/create_overlay_mount.sh: line 1434: LogInfoVar: command not found
Umounting the bind mount  "/odm" ...
/data/local/tmp/create_overlay_mount.sh: line 1434: LogInfoVar: command not found
Umounting the bind mount  "/system" ...
 ... done
/data/local/tmp/create_overlay_mount.sh: line 1474: LogInfoVar: command not found
Umounting the overlay mounts ...
Umounting "/dev/ov/merged/system_ext" ...
Umounting "/dev/ov/merged/product" ...
Umounting "/dev/ov/merged/odm" ...
Umounting "/dev/ov/merged/system" ...
 ... done

ASUS_I006D:/data/local/tmp #


----

Note that umounting /system may fail -- see below for a workaround for this problem.


To umount only the overlays of the directories /product and /odm use this command:

/data/local/tmp/create_overlay_mount.sh  umount /product /odm
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh /odm /product umount
Umounting the bind mounts ...
Umounting "/odm" ...
Umounting "/product" ...
 ... done
Umounting the overlay mounts ...
Umounting "/data/local/tmp/ov/merged/odm" ...
Umounting "/data/local/tmp/ov/merged/product" ...
 ... done

ASUS_I006D:/data/local/tmp #

----



To check the contents of the virtual disk used as backend without creating the overlay mounts use the parameter mount_only:

/data/local/tmp/create_overlay_mount.sh mount_only
# create some test files

ASUS_I006D:/data/local/tmp # for i in /system /system_ext  /product /odm/  ; do touch $i/test.$$ ; ls -l $i/test.$$ ; done
-rw-r--r-- 1 root root 0 2025-06-25 11:01 /system/test.2343
-rw-r--r-- 1 root root 0 2025-06-25 11:01 /system_ext/test.2343
-rw-r--r-- 1 root root 0 2025-06-25 11:01 /product/test.2343
-rw-r--r-- 1 root root 0 2025-06-25 11:01 /odm//test.2343
1|ASUS_I006D:/data/local/tmp #


# and reboot the phone

ASUS_I006D:/ # reboot
...

# execute in an adb shell after the reboot

1|ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh mount_only
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem

The virtual disk is mounted to "/dev/ov"

ASUS_I006D:/data/local/tmp #

1|ASUS_I006D:/data/local/tmp # ls -l /dev/ov/upper/*/*
-rw-r--r-- 1 root root       0 2025-06-25 11:01 /dev/ov/upper/odm/test.2343
-rw-r--r-- 1 root root       0 2025-06-25 11:01 /dev/ov/upper/product/test.2343
-rw-r--r-- 1 root root       0 2025-06-25 11:01 /dev/ov/upper/system/test.2343
-rw-r--r-- 1 root root       0 2025-06-25 11:01 /dev/ov/upper/system_ext/test.2343

ASUS_I006D:/data/local/tmp #

----


To create a new virtual disk /data/local/tmp/image001_ext3 with 50 MB and ext3 filesystem without creating any overlay filesystem use this command:

/data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/data/local/tmp/image001_ext3 FILESYSTEM_TO_USE=ext3 FILESYSTEM_SIZE=50m BASEDIR=/data/local/tmp/ovtest mount_only

ASUS_I006D:/ #  /data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/data/local/tmp/image001_ext3 FILESYSTEM_TO_USE=ext3 FILESYSTEM_SIZE=50m BASEDIR=/data/local/tmp/ovtest mount_only
Creating the image file "/data/local/tmp/image001_ext3" with the size 50m ...
1+0 records in
1+0 records out
52428800 bytes (50 M) copied, 0.056713 s, 882 M/s
Creating a "ext3" filesystem on the image file "/data/local/tmp/image001_ext3" now ...
mke2fs 1.46.2 (28-Feb-2021)
Discarding device blocks: done                           
Creating filesystem with 51200 1k blocks and 12824 inodes
Filesystem UUID: e5433d8e-da14-4ca5-bae1-1c7a7b13382c
Superblock backups stored on blocks:
    8193, 24577, 40961

Allocating group tables: done                           
Writing inode tables: done                           
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done

Creating the directory "/data/local/tmp/ovtest" ...
Mounting the imagefile "/data/local/tmp/image001_ext3" to "/data/local/tmp/ovtest" ...

The virtual disk is mounted to "/data/local/tmp/ovtest"

ASUS_I006D:/ #

----


To use the file /data/local/tmp/image001_ext3 for overlay mounts later use:

/data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/data/local/tmp/image001_ext3  BASEDIR=/data/local/tmp/ovtest  /odm /odm_dlkm
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/data/local/tmp/image001_ext3  BASEDIR=/data/local/tmp/ovtest  /odm /odm_dlkm
The image file "/data/local/tmp/image001_ext3" already exists - there should already be a filesystem
Creating the directory "/data/local/tmp/ovtest/upper" ...
Creating the directory "/data/local/tmp/ovtest/merged" ...
Creating the directory "/data/local/tmp/ovtest/work" ...

Creating and mounting the directories for the overlay mount for "/odm" ...
Creating the directory "/data/local/tmp/ovtest/upper/odm" ...
Creating the directory "/data/local/tmp/ovtest/merged/odm" ...
Creating the directory "/data/local/tmp/ovtest/work/odm" ...
Creating the overlay mount for "/odm" ...
Creating the bind mount "/odm"...
Checking the overlay mount for "/odm" ...

Creating and mounting the directories for the overlay mount for "/odm_dlkm" ...
Creating the directory "/data/local/tmp/ovtest/upper/odm_dlkm" ...
Creating the directory "/data/local/tmp/ovtest/merged/odm_dlkm" ...
Creating the directory "/data/local/tmp/ovtest/work/odm_dlkm" ...
Creating the overlay mount for "/odm_dlkm" ...
Creating the bind mount "/odm_dlkm"...
Checking the overlay mount for "/odm_dlkm" ...

Summary:
--------

2 overlay mount(s) created:

  /odm
  /odm_dlkm

ASUS_I006D:/data/local/tmp #

----


To use different virtual disks in parallel the variable BASEDIR must also be different:

Example for using multiple virtual disks
ASUS_I006D:/data/local/tmp #  IMAGE_FILE=/data/local/tmp/virtualdisk001 BASEDIR=/data/local/tmp/virtualfs001 ./create_overlay_mount.sh /vendor /vendor_dlkm
Creating the image file "/data/local/tmp/virtualdisk001" with the size 100m ...
1+0 records in
1+0 records out
104857600 bytes (100 M) copied, 0.084065 s, 1.1 G/s
Creating a "ext4" filesystem on the image file "/data/local/tmp/virtualdisk001" now ...
mke2fs 1.46.2 (28-Feb-2021)
Discarding device blocks: done                           
Creating filesystem with 102400 1k blocks and 25688 inodes
Filesystem UUID: 6bf0e517-3da8-4813-b463-b49b63eaedfd
Superblock backups stored on blocks:
    8193, 24577, 40961, 57345, 73729

Allocating group tables: done                           
Writing inode tables: done                           
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done

Creating the directory "/data/local/tmp/virtualfs001" ...
Mounting the imagefile "/data/local/tmp/virtualdisk001" to "/data/local/tmp/virtualfs001" ...
Creating the directory "/data/local/tmp/virtualfs001/upper" ...
Creating the directory "/data/local/tmp/virtualfs001/merged" ...
Creating the directory "/data/local/tmp/virtualfs001/work" ...

Creating and mounting the directories for the overlay mount for "/vendor" ...
Creating the directory "/data/local/tmp/virtualfs001/upper/vendor" ...
Creating the directory "/data/local/tmp/virtualfs001/merged/vendor" ...
Creating the directory "/data/local/tmp/virtualfs001/work/vendor" ...
Creating the overlay mount for "/vendor" ...
Creating the bind mount "/vendor"...
Checking the overlay mount for "/vendor" ...

Creating and mounting the directories for the overlay mount for "/vendor_dlkm" ...
Creating the directory "/data/local/tmp/virtualfs001/upper/vendor_dlkm" ...
Creating the directory "/data/local/tmp/virtualfs001/merged/vendor_dlkm" ...
Creating the directory "/data/local/tmp/virtualfs001/work/vendor_dlkm" ...
Creating the overlay mount for "/vendor_dlkm" ...
Creating the bind mount "/vendor_dlkm"...
Checking the overlay mount for "/vendor_dlkm" ...

Summary:
--------

2 overlay mount(s) created:

  /vendor
  /vendor_dlkm

ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp #  IMAGE_FILE=/data/local/tmp/virtualdisk002 BASEDIR=/data/local/tmp/virtualfs002 ./create_overlay_mount.sh /odm /odm_dlkm
Creating the image file "/data/local/tmp/virtualdisk002" with the size 100m ...
1+0 records in
1+0 records out
104857600 bytes (100 M) copied, 0.083999 s, 1.1 G/s
Creating a "ext4" filesystem on the image file "/data/local/tmp/virtualdisk002" now ...
mke2fs 1.46.2 (28-Feb-2021)
Discarding device blocks: done                           
Creating filesystem with 102400 1k blocks and 25688 inodes
Filesystem UUID: 891ce037-082c-49a8-9828-4f26f9b8dba2
Superblock backups stored on blocks:
    8193, 24577, 40961, 57345, 73729

Allocating group tables: done                           
Writing inode tables: done                           
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done

Creating the directory "/data/local/tmp/virtualfs002" ...
Mounting the imagefile "/data/local/tmp/virtualdisk002" to "/data/local/tmp/virtualfs002" ...
Creating the directory "/data/local/tmp/virtualfs002/upper" ...
Creating the directory "/data/local/tmp/virtualfs002/merged" ...
Creating the directory "/data/local/tmp/virtualfs002/work" ...

Creating and mounting the directories for the overlay mount for "/odm" ...
Creating the directory "/data/local/tmp/virtualfs002/upper/odm" ...
Creating the directory "/data/local/tmp/virtualfs002/merged/odm" ...
Creating the directory "/data/local/tmp/virtualfs002/work/odm" ...
Creating the overlay mount for "/odm" ...
Creating the bind mount "/odm"...
Checking the overlay mount for "/odm" ...

Creating and mounting the directories for the overlay mount for "/odm_dlkm" ...
Creating the directory "/data/local/tmp/virtualfs002/upper/odm_dlkm" ...
Creating the directory "/data/local/tmp/virtualfs002/merged/odm_dlkm" ...
Creating the directory "/data/local/tmp/virtualfs002/work/odm_dlkm" ...
Creating the overlay mount for "/odm_dlkm" ...
Creating the bind mount "/odm_dlkm"...
Checking the overlay mount for "/odm_dlkm" ...

Summary:
--------

2 overlay mount(s) created:

  /odm
  /odm_dlkm

ASUS_I006D:/data/local/tmp #
ASUS_I006D:/data/local/tmp #
ASUS_I006D:/data/local/tmp # ./create_overlay_mount.sh list --details
Directories mounted on an overlay filesystem

Directory         Backend Directory
---------         -----------------
/vendor           /data/local/tmp/virtualfs001 (Virtual disk: /data/local/tmp/virtualdisk001)
/vendor_dlkm      /data/local/tmp/virtualfs001 (Virtual disk: /data/local/tmp/virtualdisk001)
/odm              /data/local/tmp/virtualfs002 (Virtual disk: /data/local/tmp/virtualdisk002)
/odm_dlkm         /data/local/tmp/virtualfs002 (Virtual disk: /data/local/tmp/virtualdisk002)

ASUS_I006D:/data/local/tmp #

----

 
Note that in this case you must always use BASEDIR=<base_directory> and, for some commands IMAGE_FILE=<image_file>, to process the overlay mounts (e.g. for the actions undo, umount, diff, etc). Therefore it's recommended to create different wrapper scripts for using multiple virtual disks.

This feature can be used, for example, to create different test environments.


The script can also be used to create overlay mounts for sub directories, e.g. to create overlay filesystems for the directories /*/etc and the directory /system_ext/framework do

/data/local/tmp/create_overlay_mount.sh /*/etc /system_ext/framework
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  /*/etc /system_ext/framework
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem
Mounting the imagefile "/data/local/tmp/image001" to "/dev/ov" ...

Creating and mounting the directories for the overlay mount for "/odm/etc" ...
Creating the overlay mount for "/odm/etc" ...
Creating the bind mount "/odm/etc"...
Checking the overlay mount for "/odm/etc" ...

Creating and mounting the directories for the overlay mount for "/odm_dlkm/etc" ...
ERROR: The directory "/odm_dlkm/etc" does NOT exist -- ignored

Creating and mounting the directories for the overlay mount for "/product/etc" ...
Creating the directory "/dev/ov/upper/product#etc" ...
Creating the directory "/dev/ov/merged/product#etc" ...
Creating the directory "/dev/ov/work/product#etc" ...
Creating the overlay mount for "/product/etc" ...
Creating the bind mount "/product/etc"...
Checking the overlay mount for "/product/etc" ...

Creating and mounting the directories for the overlay mount for "/system/etc" ...
Creating the directory "/dev/ov/upper/system#etc" ...
Creating the directory "/dev/ov/merged/system#etc" ...
Creating the directory "/dev/ov/work/system#etc" ...
Creating the overlay mount for "/system/etc" ...
Creating the bind mount "/system/etc"...
Checking the overlay mount for "/system/etc" ...
WARNING: Seems like the overlay mount for "/system/etc" works only partial -- please check the directory contents

Creating and mounting the directories for the overlay mount for "/system_ext/etc" ...
Creating the directory "/dev/ov/upper/system_ext#etc" ...
Creating the directory "/dev/ov/merged/system_ext#etc" ...
Creating the directory "/dev/ov/work/system_ext#etc" ...
Creating the overlay mount for "/system_ext/etc" ...
Creating the bind mount "/system_ext/etc"...
Checking the overlay mount for "/system_ext/etc" ...

Creating and mounting the directories for the overlay mount for "/vendor/etc" ...
Creating the directory "/dev/ov/upper/vendor#etc" ...
Creating the directory "/dev/ov/merged/vendor#etc" ...
Creating the directory "/dev/ov/work/vendor#etc" ...
Creating the overlay mount for "/vendor/etc" ...
Creating the bind mount "/vendor/etc"...
Checking the overlay mount for "/vendor/etc" ...

Creating and mounting the directories for the overlay mount for "/vendor_dlkm/etc" ...
ERROR: "/vendor_dlkm/etc" is a symbolic link for "/vendor/vendor_dlkm/etc" -- ignored

Creating and mounting the directories for the overlay mount for "/system_ext/framework" ...
Creating the directory "/dev/ov/upper/system_ext#framework" ...
Creating the directory "/dev/ov/merged/system_ext#framework" ...
Creating the directory "/dev/ov/work/system_ext#framework" ...
Creating the overlay mount for "/system_ext/framework" ...
Creating the bind mount "/system_ext/framework"...
Checking the overlay mount for "/system_ext/framework" ...

Summary:
--------

6 overlay mount(s) created:

  /odm/etc
  /product/etc
  /system/etc
  /system_ext/etc
  /vendor/etc
  /system_ext/framework

2 directory(s) missing:

  /odm_dlkm/etc # directory does not exist
  /vendor_dlkm/etc # this is a symbolic link

ASUS_I006D:/data/local/tmp #


see below for the reason for the warning message: WARNING: Seems like the overlay mount for "/system/etc" works only partial -- please check the directory contents
----


 

To list the file changes for a directory with overlay mount use the parameter diff, e.g. to list all changes for the directories /odm_dlkm and /system:

/data/local/tmp/create_overlay_mount.sh diff /odm_dlkm /system

----
commands to create the test environment
# instructions to create the test env
 #
  mkdir /odm_dlkm/testdir
  touch /odm_dlkm/testdir/testfile1
  touch /odm_dlkm/testdir/testfile2
  touch /odm_dlkm/testfile0
  rm  /odm_dlkm/etc
----

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  diff /odm_dlkm /system
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/odm_dlkm" ...
There is currently an overlay mounted for the directory "/odm_dlkm"
File changes in the directory "/odm_dlkm" :

./testdir
./testdir/testfile1
./testdir/testfile2
./testfile0

Files or directories deleted in the directory "/odm_dlkm" :

./etc


 ----------------------------------------------------------------------
List the changes in the directory "/system" ...
There is currently no overlay mounted for the directory "/system"
File changes in the directory "/system" :

./bin
./bin/0001logcatboot
./bin/configure_microg.sh
./bin/correct_dev_pn553.sh
./bin/disable_intent_filter_verification.sh
./bin/enable_microg.sh
./bin/enable_wifi.sh
./bin/enable_wireless_adb.sh
./bin/install_apk.sh
./bin/install_mm.sh
./bin/list_bind_mounts.sh
./bin/list_logical_device_backends.sh
./bin/list_logical_device_usage.sh
./bin/list_magisk_root_permissions.sh
./bin/list_magisk_settings.sh
./bin/lmm
./bin/myldd
./bin/rcbm.sh
./bin/recreate_bind_mount.sh
./bin/remount_dynamic_partitions.sh
./bin/remove_screenlock.sh
./bin/rename_apk.sh
./bin/search_magisk_package.sh
./bin/setpath.sh
./bin/sudo
./bin/switch_adb_via_wifi.sh

Files or directories deleted in the directory "/system" :



ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  diff /odm_dlkm /system --details
SELinux is currently enabled
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/odm_dlkm" ...
There is currently an overlay mounted for the directory "/odm_dlkm"
File changes in the directory "/odm_dlkm" :

drwxr-xr-x 3 root root u:object_r:vendor_file:s0  1024 2025-06-17 08:59 ./testdir
-rw-r--r-- 1 root root u:object_r:vendor_file:s0     0 2025-06-17 08:59 ./testdir/testfile1
drwxr-xr-x 2 root root u:object_r:vendor_file:s0  1024 2025-06-17 09:00 ./testdir/testfile2
-rw-r--r-- 1 root root u:object_r:vendor_file:s0     0 2025-06-17 09:00 ./testfile0

Files or directories deleted in the directory "/odm_dlkm" :

./etc


 ----------------------------------------------------------------------
List the changes in the directory "/system" ...
There is currently no overlay mounted for the directory "/system"
File changes in the directory "/system" :

drwxr-x--x 2 root shell u:object_r:system_file:s0   1024 2025-06-16 21:04 ./bin
-rwxr-xr-x 1 root root  u:object_r:system_file:s0    156 2025-06-16 21:04 ./bin/0001logcatboot
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   2919 2025-06-16 21:04 ./bin/configure_microg.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0    354 2025-06-16 21:04 ./bin/correct_dev_pn553.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0     51 2025-06-16 21:04 ./bin/disable_intent_filter_verification.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0    146 2025-06-16 21:04 ./bin/enable_microg.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   2956 2025-06-16 21:04 ./bin/enable_wifi.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0  22230 2025-06-16 21:04 ./bin/enable_wireless_adb.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0  10108 2025-06-16 21:04 ./bin/install_apk.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0  16046 2025-06-16 21:04 ./bin/install_mm.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   4432 2025-06-16 21:04 ./bin/list_bind_mounts.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   7271 2025-06-16 21:04 ./bin/list_logical_device_backends.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   9463 2025-06-16 21:04 ./bin/list_logical_device_usage.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0    223 2025-06-16 21:04 ./bin/list_magisk_root_permissions.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0    449 2025-06-16 21:04 ./bin/list_magisk_settings.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0  19701 2025-06-16 21:04 ./bin/lmm
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   1038 2025-06-16 21:04 ./bin/myldd
lrwxrwxrwx 1 root root  u:object_r:system_file:s0     24 2025-06-16 21:04 ./bin/rcbm.sh -> ./recreate_bind_mount.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   3774 2025-06-16 21:04 ./bin/recreate_bind_mount.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0  16866 2025-06-16 21:04 ./bin/remount_dynamic_partitions.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0     69 2025-06-16 21:04 ./bin/remove_screenlock.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   2708 2025-06-16 21:04 ./bin/rename_apk.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   1434 2025-06-16 21:04 ./bin/search_magisk_package.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0     42 2025-06-16 21:04 ./bin/setpath.sh
-rwxr-xr-x 1 root root  u:object_r:system_file:s0     13 2025-06-16 21:04 ./bin/sudo
-rwxr-xr-x 1 root root  u:object_r:system_file:s0   5273 2025-06-16 21:04 ./bin/switch_adb_via_wifi.sh

Files or directories deleted in the directory "/system" :



ASUS_I006D:/data/local/tmp #



----

The default directory list for the action diff is the list of directories in the variable DIRS_TO_OVERLAY.  Use the options --active to list only the changes in all mounted overlay filesystems:


/data/local/tmp/create_overlay_mount.sh  diff --active
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  list
Directories mounted on an overlay filesystem

/odm/etc
/vendor


ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  diff --active
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/odm/etc" ...
There is currently an overlay mounted for the directory "/odm/etc"
File changes in the directory "/odm/etc" :

./passwd
./selinux

Files or directories deleted in the directory "/odm/etc" :

./group


 ----------------------------------------------------------------------
List the changes in the directory "/vendor" ...
There is currently an overlay mounted for the directory "/vendor"
File changes in the directory "/vendor" :

./etc
./etc/vmmgr.conf

Files or directories deleted in the directory "/vendor" :



ASUS_I006D:/data/local/tmp #

----



To undo all changes for a directory with an overlay mount use the parameter undo, e.g. to undo all changes in the directory /system execute:

/data/local/tmp/create_overlay_mount.sh undo /system
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  undo /system
Undoing the change in the directories ...
Undoing the changes for the directory "/system" ...

ASUS_I006D:/data/local/tmp #

----


To undo all the changes for all directories currently mounted on overlay filesystems do:

/data/local/tmp/create_overlay_mount.sh  undo
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  undo
Undoing the change in the directories ...
Undoing the changes for the directory "/system_ext" ...
Undoing the changes for the directory "/product" ...
Undoing the changes for the directory "/odm" ...
Undoing the changes for the directory "/system" ...

ASUS_I006D:/data/local/tmp #

----

Note that there is no redo.



To undo the changes only for specific files use the parameter restore:

/data/local/tmp/create_overlay_mount.sh restore /system/etc/hosts
ASUS_I006D:/data/local/tmp # cat /system/etc/hosts
 127.0.0.1       localhost
 ::1             ip6-localhost
 ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # echo "1.1.1.1 dnsserver" >>/system/etc/hosts
 ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # cat /system/etc/hosts                                                                                                                                                 
127.0.0.1       localhost
 ::1             ip6-localhost
 1.1.1.1 dnsserver
 ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh restore /system/etc/hosts
 Deleting the files "/data/local/tmp/ov/upper/system/etc/hosts" and "/data/local/tmp/ov/merged/system/etc/hosts" ...
 Restoring the file "/system/etc/hosts" ...
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # cat /system/etc/hosts
 127.0.0.1       localhost
 ::1             ip6-localhost
 ASUS_I006D:/data/local/tmp #



----


To restore a deleted file on a filesystem mount with overlays use the parameter restore :

/data/local/tmp/create_overlay_mount.sh restore /odm/etc/build.prop
ASUS_I006D:/data/local/tmp # ls -l /odm/etc/build.prop
-rw------- 1 root root 999 2009-01-01 01:00 /odm/etc/build.prop
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # rm /odm/etc/build.prop
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # ls -l /odm/etc/build.prop
ls: /odm/etc/build.prop: No such file or directory
1|ASUS_I006D:/data/local/tmp #

1|ASUS_I006D:/data/local/tmp # /data/local/tmp//create_overlay_mount.sh restore /odm/etc/build.prop
Restoring the file "/odm/etc/build.prop" ...

ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # ls -l /odm/etc/build.prop
-rw------- 1 root root 999 2009-01-01 01:00 /odm/etc/build.prop
ASUS_I006D:/data/local/tmp #



----


Other examples for the action restore
commands to create the test environment
/data/local/tmp/create_overlay_mount.sh mount /system/app/EasterEgg

----


ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh diff /system/app/EasterEgg
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/system/app/EasterEgg" ...
There is currently an overlay mounted for the directory "/system/app/EasterEgg"
File changes in the directory "/system/app/EasterEgg" :


Files or directories deleted in the directory "/system/app/EasterEgg" :



ASUS_I006D:/ #


ASUS_I006D:/ # ls -ld $( find /system/app/EasterEgg )
drwxr-xr-x 1 root root    1024 2025-06-22 13:35 /system/app/EasterEgg
-rw-r--r-- 1 root root 2139850 2009-01-01 01:00 /system/app/EasterEgg/EasterEgg.apk
drwxr-xr-x 3 root root    4096 2009-01-01 01:00 /system/app/EasterEgg/oat
drwxr-xr-x 2 root root    4096 2009-01-01 01:00 /system/app/EasterEgg/oat/arm64
-rw-r--r-- 1 root root   41904 2009-01-01 01:00 /system/app/EasterEgg/oat/arm64/EasterEgg.odex
-rw-r--r-- 1 root root   56904 2009-01-01 01:00 /system/app/EasterEgg/oat/arm64/EasterEgg.vdex
ASUS_I006D:/ #


# delete some files

ASUS_I006D:/ # rm /system/app/EasterEgg/EasterEgg.apk
ASUS_I006D:/ # rm /system/app/EasterEgg/oat/arm64/EasterEgg.odex
ASUS_I006D:/ # rm /system/app/EasterEgg/oat/arm64/EasterEgg.vdex                                                                                                   
ASUS_I006D:/ #

ASUS_I006D:/ # ls -ld $( find /system/app/EasterEgg )                                                                                                                
drwxr-xr-x 1 root root 1024 2025-06-22 13:41 /system/app/EasterEgg
drwxr-xr-x 1 root root 1024 2009-01-01 01:00 /system/app/EasterEgg/oat
drwxr-xr-x 1 root root 1024 2025-06-22 13:41 /system/app/EasterEgg/oat/arm64
ASUS_I006D:/ #


# restore a file

ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh restore /system/app/EasterEgg/EasterEgg.apk
Restoring the file "/system/app/EasterEgg/EasterEgg.apk" ...

ASUS_I006D:/ #

ASUS_I006D:/ # ls -ld $( find /system/app/EasterEgg )                                                                                                                
drwxr-xr-x 1 root root    1024 2025-06-22 13:42 /system/app/EasterEgg
-rw-r--r-- 1 root root 2139850 2009-01-01 01:00 /system/app/EasterEgg/EasterEgg.apk
drwxr-xr-x 1 root root    1024 2009-01-01 01:00 /system/app/EasterEgg/oat
drwxr-xr-x 1 root root    1024 2025-06-22 13:41 /system/app/EasterEgg/oat/arm64
ASUS_I006D:/ #


# restore all  files in a directory

ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh restore /system/app/EasterEgg/oat
Restoring the directory "/system/app/EasterEgg/oat" ...

ASUS_I006D:/ #

ASUS_I006D:/ # ls -ld $( find /system/app/EasterEgg )                                                                                                                
drwxr-xr-x 1 root root    1024 2025-06-22 13:43 /system/app/EasterEgg
-rw-r--r-- 1 root root 2139850 2009-01-01 01:00 /system/app/EasterEgg/EasterEgg.apk
drwxr-xr-x 3 root root    4096 2009-01-01 01:00 /system/app/EasterEgg/oat
drwxr-xr-x 2 root root    4096 2009-01-01 01:00 /system/app/EasterEgg/oat/arm64
-rw-r--r-- 1 root root   41904 2009-01-01 01:00 /system/app/EasterEgg/oat/arm64/EasterEgg.odex
-rw-r--r-- 1 root root   56904 2009-01-01 01:00 /system/app/EasterEgg/oat/arm64/EasterEgg.vdex
ASUS_I006D:/ #


ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh diff /system/app/EasterEgg
List the changes in the directories ...

 ----------------------------------------------------------------------
List the changes in the directory "/system/app/EasterEgg" ...
There is currently an overlay mounted for the directory "/system/app/EasterEgg"
File changes in the directory "/system/app/EasterEgg" :


Files or directories deleted in the directory "/system/app/EasterEgg" :



ASUS_I006D:/ #

# change a file

ASUS_I006D:/ # echo >/system/app/EasterEgg/EasterEgg.apk
ASUS_I006D:/ #

ASUS_I006D:/ # ls -l /system/app/EasterEgg/EasterEgg.apk
-rw-r--r-- 1 root root 1 2025-06-22 13:49 /system/app/EasterEgg/EasterEgg.apk
ASUS_I006D:/ #


ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh restore /system/app/EasterEgg/
"/system/app/EasterEgg" is a directory with an overlay mount -- use the parameter "undo /system/app/EasterEgg" to undo all changes for this directory

ASUS_I006D:/ #

ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh restore /system/app/EasterEgg/EasterEgg.apk
Restoring the file "/system/app/EasterEgg/EasterEgg.apk" ...

ASUS_I006D:/ # ls -l /system/app/EasterEgg/EasterEgg.apk
-rw-r--r-- 1 root root 2139850 2009-01-01 01:00 /system/app/EasterEgg/EasterEgg.apk
ASUS_I006D:/ #

----


In case of an error in a directory with an overlay you may remount the directory using the script parameter remount:

 /data/local/tmp/create_overlay_mount.sh remount /system_ext
ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh remount /system_ext
Remounting the overlay mounts ...
Remounting "/system_ext" ...
 ... done

ASUS_I006D:/data/local/tmp #



----

 

Environment variables used by the script



The script uses these environment variables:


Variable
 Usage
 Default value
 Comment
IMAGE_FILE file used for the virtual disk
 /data/local/tmp/image001
BASEDIR the mount point for the virtual disk /dev/ov
 this parent directory for this directory (/dev in the default config) must be readable and executable by any user
DIRS_TO_OVERLAY the directories for which the script creates an overlay mount /system_ext
/product
/odm
/system
FILESYSTEM_TO_USE the filesystem used on the virtual disk
 ext4
 must be a filesystem known by the running Android that supports overlay mounts (e.g. ext4 or ext3)

The parameter is only used when creating a new filesystem on the virtual disk.
 
FILESYSTEM_SIZE the size of the virtual disk 100m
 the value can be any value that is known by the binary dd for the parameter bs (see the output of "dd --help")

The variable is only used when the virtual disk is created.
MKFS_OPTIONS additional options for the mkfs* command to create the filesysten on the loop device
The variable is only used when the virtual disk is created.
MOUNT_OPTIONS additional options for the mount command to mount the filesystem on the loop device

SELINUX_CONTEXT the SELinux context used for new directories if the script can not read the SELinux context of an existing directory u:object_r:system_file:s0




MOUNT
 mount binary to use
 $( which mount )
UMOUNT
 umount binary to use $( which umount )
LOSETUP
 losetup binary to use $( which losetup )
MKFS
 mkfs binary to use $( which mkfs.${FILESYSTEM_TO_USE} )
DD
 dd binary to use $( which dd )




UMOUNT_WAIT_TIME
 time in seconds to wait between umounting the bind mounts and umounting the overlay mounts
 0
 in some Android versions it's necessary to wait some time between umounting the bind mount andumounting the overlay mount. Set this variable to the number of seconds the script should wait between these umounts.
BIND_MOUNT_TARGET_DIR
 target directory for bind mounts
 /data/local/tmp
 see using Magisk and overlay mounts in parallel
FILES_TO_KEEP
 list of files for which a bind mount shoud be created
see using Magisk and overlay mounts in parallel


To change one or more of these variables use either a command like this

IMAGE_FILE="/data/local/tmp/image002" BASEDIR="/data/local/tmp/ov2" create_overlay_mount.sh

or this

create_overlay_mount.sh IMAGE_FILE="/data/local/tmp/image002" BASEDIR="/data/local/tmp/ov2"


Note:

Use

create_overlay_mount.sh vars

to only print the current list of supported environment variables with default values.




The new files created in the directories with overlay mounts can be found in the directory

${BASEDIR}/upper/${DIR_NAME}

e.g.

ASUS_I006D:/data/local/tmp # df -h /odm
Filesystem      Size Used Avail Use% Mounted on
overlay          88M  55K   88M   1% /odm
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # touch /odm/testfile.$$
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # ls -ldZ /odm/testfile.$$
-rw-r--r-- 1 root root u:object_r:vendor_file:s0  0 2025-06-24 21:59 /odm/testfile.4944
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # ls -ldZ /dev/ov/upper/odm/testfile.4944
-rw-r--r-- 1 root root u:object_r:vendor_file:s0  0 2025-06-24 21:59 /dev/ov/upper/odm/testfile.4944
ASUS_I006D:/data/local/tmp #




For sub directories with overlay mounts the directory name in the directory ${BASEDIR}/upper is in the format subir1#subdir2#....#subdirN,

For an overlay mount for /vendor/vendor_dlkm/etc the directory name is vendor#vendor_dlkm#etc :

ASUS_I006D:/data/local/tmp # df -h /vendor/vendor_dlkm/
Filesystem      Size Used Avail Use% Mounted on
/dev/block/dm-4 1.1G 1.1G  3.5M 100% /vendor
ASUS_I006D:/data/local/tmp #   
                                                                                                                                              
ASUS_I006D:/data/local/tmp # df -h /vendor/vendor_dlkm/etc
Filesystem      Size Used Avail Use% Mounted on
overlay          88M  59K   88M   1% /vendor/vendor_dlkm/etc
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # touch /vendor/vendor_dlkm/etc/test.$$
ASUS_I006D:/data/local/tmp #
ASUS_I006D:/data/local/tmp # ls -ldZ /vendor/vendor_dlkm/etc/test.$$
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  0 2025-06-24 22:02 /vendor/vendor_dlkm/etc/test.4944
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # ls -ldZ /dev/ov/upper/vendor\#vendor_dlkm\#etc/test.$$
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  0 2025-06-24 22:02 /dev/ov/upper/vendor#vendor_dlkm#etc/test.4944
ASUS_I006D:/data/local/tmp #


For deleted files or directories a character device with major 0 and minor 0 is created in the directory ./upper, e.g:

ASUS_I006D:/data/local/tmp # rm /vendor/etc/ueventd.rc
ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # ls -l /vendor/etc/ueventd.rc
ls: /vendor/etc/ueventd.rc: No such file or directory

1|ASUS_I006D:/data/local/tmp #

1|ASUS_I006D:/data/local/tmp # ls -l /data/local/tmp/ov/upper/vendor\#etc/ueventd.rc
c--------- 1 root root 0,   0 2025-06-14 14:17 /data/local/tmp/ov/upper/vendor#etc/ueventd.rc
ASUS_I006D:/data/local/tmp #


Notes

Use the action get to print the backend for a file in a directory with an overlay mount:


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /odm/testfile.4944
/dev/ov/upper/odm/testfile.4944 # /odm/testfile.4944 # the file was changed

ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /odm/testfile.4944 --details
-rw-r--r-- 1 root root u:object_r:vendor_file:s0  0 2025-06-24 21:59 /dev/ov/upper/odm/testfile.4944 # /odm/testfile.4944 # the file was changed

ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh get /vendor/vendor_dlkm/etc/test.4944
 /dev/ov/upper/vendor#vendor_dlkm#etc/test.4944 # /vendor/vendor_dlkm/etc/test.4944 # the file was changed
ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh get /vendor/vendor_dlkm/etc/test.4944  --details
-rw-r--r-- 1 root root u:object_r:vendor_configs_file:s0  0 2025-06-24 22:02 /dev/ov/upper/vendor#vendor_dlkm#etc/test.4944 # /vendor/vendor_dlkm/etc/test.4944 # the file was changed

ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /vendor/etc/ueventd.rc
/dev/ov/upper/vendor#etc/ueventd.rc # /vendor/etc/ueventd.rc # the file/directory was deleted

ASUS_I006D:/data/local/tmp #

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  get /vendor/etc/ueventd.rc  --details
c--------- 1 root root u:object_r:vendor_configs_file:s0  0,   0 2025-06-24 22:08 /dev/ov/upper/vendor#etc/ueventd.rc # /vendor/etc/ueventd.rc # the file/directory was deleted

ASUS_I006D:/data/local/tmp #





ext3 and ext4 filesystems can be increased while mounted:

Instructions to increase the virtual disk used as backend
# Note: only the commands in bold are necessary to increase the virtual disk

ASUS_I006D:/ # ls -lh /data/local/tmp/image001
-rw-r--r-- 1 root root 10M 2025-03-15 20:36 /data/local/tmp/image001
ASUS_I006D:/ #

# -> the size of the file used as virtual disk is 10 MB

ASUS_I006D:/ # df -h /data/local/tmp/ov
Filesystem        Size Used Avail Use% Mounted on
/dev/block/loop31 8.6M  39K  8.6M   1% /data/local/tmp/ov
ASUS_I006D:/ #

# increase the size of the file /data/local/tmp/image001 by 50M

ASUS_I006D:/ # dd if=/dev/zero count=1 bs=50m >>/data/local/tmp/image001
1+0 records in
1+0 records out
52428800 bytes (50 M) copied, 0.058147 s, 860 M/s
ASUS_I006D:/ #

ASUS_I006D:/ # ls -lh /data/local/tmp/image001
-rw-r--r-- 1 root root 60M 2025-03-15 20:38 /data/local/tmp/image001
ASUS_I006D:/ #


# -> the size of the file used as virtual disk is now 60 MB

# update the loop device
#
ASUS_I006D:/ # losetup -j /data/local/tmp/image001 -c
ASUS_I006D:/ #

# resize the filesystem on the virtual disk
#
ASUS_I006D:/ # resize2fs /dev/block/loop31
resize2fs 1.46.2 (28-Feb-2021)
Filesystem at /dev/block/loop31 is mounted on /data/local/tmp/ov; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 1
The filesystem on /dev/block/loop31 is now 61440 (1k) blocks long.

ASUS_I006D:/ #

ASUS_I006D:/ # df -h /data/local/tmp/ov
Filesystem        Size Used Avail Use% Mounted on
/dev/block/loop31  58M  39K   58M   1% /data/local/tmp/ov
ASUS_I006D:/ #



Note:

ext4 filesystem can also be decreased when the filesystem is not mounted but it is not that easy to shrink the file used for the virtual disk.

 


For first tests, I strongly recommend NOT to create an overlay mount for the directory /system:

If something fails when creating an overlay for /system, there is no access to any of the executables and files in /system anymore and a reboot via Android GUI is required to fix that


The script does not support directory names with a hash "#" in the name.


To check, if overlay filesystems are supported in the Android OS use the command:

grep overlay /proc/filesystems

The output should look like this:

ASUS_I006D:/data/local/tmp #  grep overlay /proc/filesystems
nodev    overlay
ASUS_I006D:/data/local/tmp #



Please note that files created with Magisk modules, e.g. in /system/bin, are no longer visible after configuring an overlay mount for /system using the script create_overlay_mount.sh. That's also true for the executable "su" from Magisk necessary to become root user (see using Magisk and overlay mounts in parallel for a workaround for this issue).



The script create_overlay_mount.sh can also run early in the boot process if Magisk (or a similar tool) is installed. E.g. with installed Magisk do:

Copy the script to /data/adb/create_overlay_mount.sh into the directory /data/adb and create a start script in the directory /data/adb/post-fs-data.d:

cat <<EOT >/data/adb/post-fs-data.d/configure_overlay_mounts.sh
exec 2>/cache/confiure_overlay.log 1>&2
set -x
/data/adb/create_overlay_mount.sh mount
EOT
chmod 755 /data/adb/post-fs-data.d/configure_overlay_mounts.sh


In this case, the restrictions described above regarding the command "su" and the installed Magisk modules do not apply.

But not all sub directories in /system are writable using this approach. Furthermore, other problems may arise when using the script this way.

Therefore, this approach is not recommended—it is better to copy the necessary files from the Magisk modules from /data/adb/modules/<module name>/system to /system while the overlay file system is mounted.

Warning

You should have a working TWRP recovery that can access the files in the directory /data for your phone before adding files to /data/adb/post-fs-data.d.
 (Starting the phone in Safe mode does NOT help to fix a buggy script in /data/adb/post-fs-data.d)


See here for instructions to manually create an overlay mount in Android.


Using Magisk and overlay mounts in parallel


Files created with Magisk modules, e.g. in /system/bin, are no longer visible after configuring an overlay mount for /system using the script create_overlay_mount.sh. That's also true for the executable "su" necessary to become root user if Magisk is installed.

To get around this issue, create_overlay_mount.sh creates bind mounts for the Magisk executables magisk, su, and resetprop before mounting an overlay filesystem for /system. These bind mounts can then be used instead of the original executables.

Example:

ASUS_I006D:/ $ id
uid=2000(shell) gid=2000(shell) groups=2000(shell),1004(input),1007(log),1011(adb),1015(sdcard_rw),1028(sdcard_r),1078(ext_data_rw),1079(ext_obb_rw),3001(net_bt_admin),3002(net_bt),3003(inet),3006(net_bw_stats),3009(readproc),3011(uhid),3012(readtracefs) context=u:r:shell:s0
ASUS_I006D:/ $

ASUS_I006D:/ $ which su
/system/bin/su
ASUS_I006D:/ $

ASUS_I006D:/ $ su - -c /data/local/tmp/create_overlay_mount.sh /system
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem
Creating the directory "/dev/ov" ...
Mounting the imagefile "/data/local/tmp/image001" to "/dev/ov" ...

Creating and mounting the directories for the overlay mount for "/system" ...

Magisk is installed - creating temporary copies of the Magisk executables ...
Creating the temporary file "/data/local/tmp/system/bin/magisk" ...
Creating the temporary file "/data/local/tmp/system/bin/su" ...
Creating the temporary file "/data/local/tmp/system/bin/resetprop" ...

Creating the overlay mount for "/system" ...
Creating the bind mount "/system"...
Checking the overlay mount for "/system" ...

Summary:
--------

1 overlay mount(s) created:

  /system

ASUS_I006D:/ $

ASUS_I006D:/ $ which su
1|ASUS_I006D:/ $

1|ASUS_I006D:/ $ id
uid=2000(shell) gid=2000(shell) groups=2000(shell),1004(input),1007(log),1011(adb),1015(sdcard_rw),1028(sdcard_r),1078(ext_data_rw),1079(ext_obb_rw),3001(net_bt_admin),3002(net_bt),3003(inet),3006(net_bw_stats),3009(readproc),3011(uhid),3012(readtracefs) context=u:r:shell:s0
ASUS_I006D:/ $

# use the bind mount instead of the now hidden original files
#
ASUS_I006D:/ $ /data/local/tmp/system/bin/su -
ASUS_I006D:/ #

ASUS_I006D:/ # id
uid=0(root) gid=0(root) groups=0(root) context=u:r:magisk:s0
ASUS_I006D:/ #


To create additional bind mounts for other files (e.g. files installed via Magisk Modules), add the filenames to the environment variable FILES_TO_KEEP before calling the script create_overlay_mounts.sh.

The number of filenames in the variable FILES_TO_KEEP is not limited by the script; the filenames must be separated by white spaces or commas. The files must exist; bind mounts for directories are not supported.

The filenames in the variable FILES_TO_KEEP are interpreted by the script using these rules:

Example:

ASUS_I006D:/ $ FILES_TO_KEEP="dmesg bin/sh /system_ext/bin/rsync ./etc/ssh/sshd_config ./usr/bin/fuser ./bin/DebugTools/7zz"  su - -c /data/local/tmp/create_overlay_mount.sh /system
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem
Creating the directory "/dev/ov" ...
Mounting the imagefile "/data/local/tmp/image001" to "/dev/ov" ...

Creating and mounting the directories for the overlay mount for "/system" ...

Magisk is installed - creating temporary copies of the Magisk executables ...
Creating the temporary file "/data/local/tmp/system/bin/dmesg" ...
Creating the temporary file "/data/local/tmp/system/bin/sh" ...
Creating the temporary file "/data/local/tmp/system_ext/bin/rsync" ...
Creating the temporary file "/data/local/tmp/system/./etc/ssh/sshd_config" ...
Creating the temporary file "/data/local/tmp/system/./usr/bin/fuser" ...
Creating the temporary file "/data/local/tmp/system/./bin/DebugTools/7zz" ...
Creating the temporary file "/data/local/tmp/system/bin/magisk" ...
Creating the temporary file "/data/local/tmp/system/bin/su" ...
Creating the temporary file "/data/local/tmp/system/bin/resetprop" ...

Creating the overlay mount for "/system" ...
Creating the bind mount "/system"...
Checking the overlay mount for "/system" ...

Summary:
--------

1 overlay mount(s) created:

  /system

ASUS_I006D:/ $


The default target directory for the bind mounts is /data/local/tmp. To change the directory for the bind mounts, set the variable BIND_MOUNT_TARGET_DIR, e.g.:

ASUS_I006D:/ $ mkdir -p /data/local/tmp/bind_mounts
ASUS_I006D:/ $

ASUS_I006D:/ $ FILES_TO_KEEP="bvi ./bin/DebugTools/7zz"  su - -c /data/local/tmp/create_overlay_mount.sh /system BIND_MOUNT_TARGET_DIR=/data/local/tmp/bind_mounts
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem
Creating the directory "/dev/ov" ...
Mounting the imagefile "/data/local/tmp/image001" to "/dev/ov" ...

Creating and mounting the directories for the overlay mount for "/system" ...

Magisk is installed - creating temporary copies of the Magisk executables ...
Creating the temporary file "/data/local/tmp/bind_mounts/system/bin/bvi" ...
Creating the temporary file "/data/local/tmp/bind_mounts/system/./bin/DebugTools/7zz" ...
Creating the temporary file "/data/local/tmp/bind_mounts/system/bin/magisk" ...
Creating the temporary file "/data/local/tmp/bind_mounts/system/bin/su" ...
Creating the temporary file "/data/local/tmp/bind_mounts/system/bin/resetprop" ...

Creating the overlay mount for "/system" ...
Creating the bind mount "/system"...
Checking the overlay mount for "/system" ...

Summary:
--------

1 overlay mount(s) created:

  /system

ASUS_I006D:/ $


If there are many files implemented via Magisk Modules, I recommend to copy these files to /system after creating the overlay mount:

# Copy the files from the Magisk module myscripts to /system:
 
cp -r /data/adb/modules/myscripts/system/* /system 



Example disk images


Virtual disk with a clang21 toolchain


URL : https://xdaforums.com/t/using-a-virtual-disk-with-a-clang21-toolchain-and-android-ndk-r29-for-an-overlay-mount.4764760/


I created a virtual disk image with a clang21 toolchain, the necessary files from the Android NDK r29 for compiling C/C++ programs on the phone, and some other useful tools for compiling source code:

http://bnsmb.de/files/public/Android/clang21_virtual_image.gz

This virtual disk image can be used on any phone with an arm64 CPU and a recent Android version .

The clang21 toolchain contains these executables:

clang 21.0
make 4.4.1
cmake 4.0.1
ninja 1.13.0
gnupatch 2.8
pkg-config 0.29
pkgconf 2.30
git 2.50.1
gdb 16.3
bash 5.2.37
perl 5.42.0
python 3.14.0
rsync 3.4.1
curl 8.11.0
wget2 2.1.0
binutils 2.42
nano 8.6
openssh 10.0p2
openssl 3.5.4
openvpn 2.7
unfsd 0.11

plus some other tools

Root access is required for overlay mounting the file system on the virtual disk image; root access is not required to use the compiler and tools from the virtual disk.

Note that the compressed file containing the disk image is approximately 500 MB in size; the uncompressed file containing the virtual disk occupies 2.0 GB of storage space. Approximately 350 MB of storage space is available on the virtual disk


To use the virtual disk use these commands:

Copy the file clang21_virtual_image.gz to the phone and uncompress it:

adb push clang21_virtual_image.gz /sdcard/Download

adb shell gzip -d /sdcard/Download/clang21_virtual_image.gz



Then open an adb shell on the phone, become root user, and configure the virtual disk as overlay file system for the directory /system:

/data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/clang21_virtual_image /system

(This command must be done once after each reboot of the phone to use the overlay file system)

Example:

/data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/clang21_virtual_image /system
ASUS_I006D:/ #  /data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/clang21_virtual_image /system
The image file "/sdcard/Download/clang21_virtual_image" already exists - there should already be a filesystem
Creating the directory "/dev/ov" ...
Mounting the imagefile "/sdcard/Download/clang21_virtual_image" to "/dev/ov" ...

Creating and mounting the directories for the overlay mount for "/system" ...
Creating the overlay mount for "/system" ...
Creating the bind mount "/system"...
Checking the overlay mount for "/system" ...

Summary:
--------

1 overlay mount(s) created:

  /system

ASUS_I006D:/ #



Now all files from the virtual disk are available in /system , e.g:

ASUS_I006D:/ $ id
uid=2000(shell) gid=2000(shell) groups=2000(shell),1004(input),1007(log),1011(adb),1015(sdcard_rw),1028(sdcard_r),1078(ext_data_rw),1079(ext_obb_rw),3001(net_bt_admin),3002(net_bt),3003(inet),3006(net_bw_stats),3009(readproc),3011(uhid),3012(readtracefs) context=u:r:shell:s0
ASUS_I006D:/ $

126|ASUS_I006D:/ $ /system/usr/bin/git --version
git version 2.50.1
ASUS_I006D:/ $

ASUS_I006D:/ $ /system/usr/clang21/utils/bin/make --version
GNU Make 4.4.1
Built for aarch64-unknown-linux-android
Copyright (C) 1988-2023 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
ASUS_I006D:/ $


And the directory /system is writable for the user root:


ASUS_I006D:/ # touch /system/xxx.$$$
ASUS_I006D:/ #

ASUS_I006D:/ # ls -l /system/xxx.$$$
-rw-r--r-- 1 root root 0 2025-10-19 13:49 /system/xxx.3264$
ASUS_I006D:/ #

Note: Some executables on the virtual disk require libraries in /system/usr/lib -- these executables are only usable after initializing the environment (or setting the variable LD_LIBRARY_PATH manually)


Before using the binaries from the clang21 toolchain on the virtual disk in an adb session to compile programs, init the toolchain environment with the command:

source /system/bin/init_clang21_env

(this command must be done once in each adb session using the clang21 toolchain)

Example:


source /system/bin/init_clang21_env
ASUS_I006D:/ $ source /system/bin/init_clang21_env
The clang21 tool chain environment is already prepared for the user "shell" (remove the file "/data/local/tmp/toolchain_prepare_shell_done" to prepare the environment again)
Initializing the clang21 tool chain environment ...

Preparing the clang environment for creating binaries for the CPU type aarch64
Using the home directory "/data/local/tmp/home/shell"
INFO: The target root directory "/data/local/tmp/develop/sysroot" does not exist

Using clang 21                                                                            
Using the NDK /system/usr/ndk/r29                                                          (environment variable NDK_DIR)
Using the sysroot directory /system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot   (environment variable SYSROOT)
Using the target root directory /data/local/tmp/develop/sysroot                            (environment variable TARGET_ROOT)

Environment variables used:

PATH is now:         /system/usr/clang21/bin:/product/bin:/apex/com.android.runtime/bin:/apex/com.android.art/bin:/system_ext/bin:/system/bin:/system/xbin:/odm/bin:/vendor/bin:/vendor/xbin:/system/usr/clang21/utils/bin:/system/usr/bin

LD_LIBRARY_PATH:     :/system/usr/lib:/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/lib/aarch64-linux-android:/system/usr/clang21/lib

API is now:          31
NDK_DIR is now:      /system/usr/ndk/r29

SYSROOT is now:      /system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot

CFLAGS are now:       -I/system/usr/include -I/system/usr/clang21/include -I/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/include--sysroot=/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot

CPPFLAGS are now:     -I/system/usr/include -I/system/usr/clang21/include -I/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/include

CXXFLAGS are now:     -I/system/usr/include -I/system/usr/clang21/include -I/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/include --target=aarch64-linux-android31

LDFLAGS are now:      -L/system/usr/lib -L/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/lib/clang/21/lib/linux/aarch64 -L/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/lib/aarch64-linux-android/31 -L/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/lib/aarch64-linux-android -B/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot/usr/lib/aarch64-linux-android/31 --sysroot=/system/usr/ndk/r29/toolchains/llvm/prebuilt/aarch64/sysroot -lc 

CLANG is now:        /system/usr/clang21/bin/clang
CC is now:           /system/usr/clang21/bin/clang
CXX is now:          /system/usr/clang21/bin/clang++
CPP is now:          /system/usr/clang21/bin/clang-cpp
CXXCPP is now:       /system/usr/clang21/bin/clang-cpp
AR is now:           /system/usr/clang21/bin/llvm-ar
AS is now:           /system/usr/clang21/bin/llvm-as
LD is now:           /system/usr/clang21/bin/lld
LLD is now:          /system/usr/clang21/bin/lld
RANLIB is now:       /system/usr/clang21/bin/llvm-ranlib
STRIP is now:        /system/usr/clang21/bin/llvm-strip
PKG_CONFIG is now:   /system/usr/clang21/utils/bin/pkg-config

Checking the clang binary ...

clang version 21.0.0git (https://android.googlesource.com/toolchain/llvm-project 37f38d1f3276b62fba09462ab4807dce846c732d)
Target: aarch64-unknown-linux-android
Thread model: posix
InstalledDir: /system/usr/clang21/bin

Defining some aliases ...
vi=/system/usr/bin/vi
find=/system/usr/bin/find
tar=/system/usr/bin/tar
bash=/system/usr/bin/bash
sed=/system/usr/bin/sed
awk=/system/usr/bin/awk
dd=/system/usr/bin/dd
nano=/system/usr/bin/nano
[clang21 toolchain] ASUS_I006D:/ $
                                                                                                                                                                



This command must be done once in each adb or ssh session.


The script /system/bin/init_clang21_env executes the script /system/bin/prepare_clang21_environment to prepare the clang21 toolchain environment (this script is only executed once for each user).

The script /system/bin/prepare_clang21_environment creates the necessary directories and files in /data/local/tmp/home if they do not yet exist.
 

The script init_clang21_env sets some environment variables, if they are not already defined:

Environment variable
 Default Value
 Comment
HOME
 /data/local/tmp/home/$( id -un )
 the variable is also set to the default value if the value is "/"

The home directory is created by the script prepare_clang21_environment if it does not yet exist
TMPDIR
 /data/local/tmp
TERMINFO
 /system/etc/terminfo
 the terminfo database is part of the virtual disk
TERM
 vt100
SSL_CERT_DIR
 /system/etc/security/cacerts
SSL_CERT_FILE
 /data/local/tmp/home/ca-certificates.crt
 This file is created by the script prepare_clang21_environment

If the file does not exist the script uses the file

/system/etc/security/ca-certificates.crt

(That file is part of the virtual disk)
CLANG_VERSION
 21
CLANG_DIR
 /system/usr/clang${CLANG_VERSION}
NDK_VERSION
 r29
NDK_DIR
 /system/usr/ndk/${NDK_VERSION]
SYSROOT
 /system/usr/ndk/${NDK_VERSION]/toolchains/llvm/prebuilt/aarch64/sysroot
API
 31
CPU_TYPE
 uname -m
TARGET_ROOT
 /data/local/tmp/develop/sysroot
 this variable can be used for the parameter "--prefix" for the configure scripts.

The environment variable is only defined if the directory exists (the directory is not created by the script)
CFLAGS, CPPFLAGS, CXXFLAGS, LDFLAGS
 mandatory values for using the clang compiler




The script also sets the environment variables

CC, CXX, CPP, CXXPP, AR, AS, LD, RANLIB, STRIP, PKG_CONFIG

with the fully qualified names of the clang binaries.

Note that it's important to use the environment variables CFLAGS or CXXFLAGS and LDFLAGS to compile a binary or library using the clang21 toolchain.
Most configure scripts for Unix programs use the values of these variables when they are set. To invoke clang manually, always use this syntax

# to compile a C program
#
clang $CFLAGS $LDFLAGS <your parameter>

or

# to compile a C++ program
 #
 clang $CXXFLAGS $LDFLAGS <your parameter>

The necessary files to compile binaries for arm64 CPUs from the Android NDK are in the directory /system/usr/ndk/r29.


The virtual disk also contains some libraries in the directory /system/usr/lib (including the necessary header files in the directory /system/usr/include)


If a file is missing, just copy it to /system/bin or another sub directory in /system. All new files copied to one of these directories are saved in the virtual disk and will therefor survive a reboot (dito for file changes in /system)

To test the compiler use these commands:

[clang21 toolchain] ASUS_I006D:/data/local/tmp/home/shell $ cd /system/usr/share/examples/
[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $

[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $ b
total 16
-rw-r--r-- 1 system root 586 2025-10-19 12:05 helloworld_in_assembler.s
-rw-r--r-- 1 system root 608 2025-10-19 12:05 helloworld_in_assembler_for_as.s
-rw-r--r-- 1 system root 774 2025-10-19 12:05 helloworld_in_c++.cpp
-rw-r--r-- 1 system root 398 2025-10-19 12:05 helloworld_in_c.c
[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $

[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $ clang ${CFLAGS} ${LDFLAGS} -o /data/local/tmp/helloworld_in_c helloworld_in_c.c  && /data/local/tmp/helloworld_in_c
Hello, World from a C program!
Compiled with Clang 21.0.0
[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $

[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $ clang++ ${CXXFLAGS} ${LDFLAGS}  -o /data/local/tmp/helloworld_in_c++ ./helloworld_in_c++.cpp && /data/local/tmp//helloworld_in_c++
Hello, World from a C++ program!
Compiled with Clang 21.0.0
Compiler version: Clang 21.0.0git (https://android.googlesource.com/toolchain/llvm-project 37f38d1f3276b62fba09462ab4807dce846c732d)
[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $

[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $ clang -nostdlib -static -Wl,--entry=_start -o /data/local/tmp/helloworld_in_assembler helloworld_in_assembler.s && /data/local/tmp//helloworld_in_assembler                                                  
Hello, World from an assembler program compiled with clang!
[clang21 toolchain] ASUS_I006D:/system/usr/share/examples $


Another test : Download and compile the editor nano:

# init the clang21 toolchain environment if not done yet
#
source /system/bin/init_clang21_env

cd /data/local/tmp

wget https://www.nano-editor.org/dist/v8/nano-8.6.tar.gz
tar -xf nano-8.6.tar.gz    
cd nano-8.6

CFLAGS="$CFLAGS -Wno-implicit-function-declaration -Wno-int-conversion -DGNULIB_LIBPOSIX"

LDFLAGS="$LDFLAGS -static"

./configure --prefix=/system --disable-nls

make -j$( nproc )


The compiled nano binary is then in the directory ./src, e.g:

ASUS_I006D:/data/local/tmp/nano-8.6 # ls -ltr src/nano
-rwxr-xr-x 1 root root 3329704 2025-10-19 13:35 src/nano
ASUS_I006D:/data/local/tmp/nano-8.6 #

ASUS_I006D:/data/local/tmp/nano-8.6 # file src/nano
src/nano: ELF executable, 64-bit LSB arm64, static, for Android 31, built by NDK r29 (14206865), not stripped
ASUS_I006D:/data/local/tmp/nano-8.6 #

ASUS_I006D:/data/local/tmp/nano-8.6 # src/nano --version
 GNU nano, version 8.6
 (C) 2025 the Free Software Foundation and various contributors
 Compiled options: --disable-libmagic --disable-nls --enable-utf8
ASUS_I006D:/data/local/tmp/nano-8.6 #


To replace the nano binary in the virtual disk become root user and copy the new nano binary to /system/bin:

cp src/nano /system/bin/nano

or execute as user root:

make install

to install nano.


Configuration Details

The home directory for the user using the clang21 toolchain is

/data/local/tmp/home/$( id -un )

This directory is created by the script /system/bin/prepare_clang21_environment if it does not yet exist.

The SSL certificate bundle file used by wget, curl, and git is /data/local/tmp/home/ca-certificates.crt; this file is generated using the certificates in /system/etc/security/cacerts by the script /system/bin/prepare_clang21_environment if it does not yet exist.

The host key files for OpenSSH are in the directory /data/local/tmp/.ssh. The script /system/bin/prepare_clang21_environment creates this directory and the host key files if they do not yet exist
The authorized_keys file for OpenSSH is /data/local/tmp/.ssh/authorized_keys; this file must be created by the user with the used public ssh keys (ssh connections with password authentication are not supported)

See here for the documenation for the NFS Server unfsd.

See here for the documentation for OpenSSH.

See here for the documentation for OpenVPN.

see here for the documentation for a Magisk Module with clang21 and the Android NDK r29





Virtual disk with a clang19 toolchain


(see also https://xdaforums.com/t/using-a-virtual-disk-with-a-clang19-toolchain-for-an-overlay-mount.4749365/)

I have created a virtual disk image with a clang19 toolchain that can be used for testing.


Notes

This virtual disk is only a prove of concept. I did not do indepth tests and I do not plan to update the image on a a regular base.

Be aware that compressed file with the disk image is about 520 MB; the uncompressed file with the virtual disk occupies 2,1 GB diskspace. There is about 500 MB free space in the virtual disk.


To use the virtual disk use these commands:


Download the file with the virtual disk image to the PC

wget http://bnsmb.de/files/public/Android/clang19_virtual_image.gz


Copy the file clang19_virtual_image.gz to the phone

adb push clang19_virtual_image.gz /sdcard/Download


and uncompress it:

adb shell gzip -d /sdcard/Download/clang19_virtual_image.gz



Then open an adb shell on the phone, become root user, and configure the virtual disk as overlay filesystem for the directory /system:

/data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/clang19_virtual_image /system

(This command must be done once after each reboot of the phone to use the overlay filesystem)


Example:

/data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/clang19_virtual_image  /system
ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/clang19_virtual_image  /system
 The image file "/sdcard/Download/clang19_virtual_image" already exists - there should already be a filesystem
 Creating the directory "/dev/ov" ...
 Mounting the imagefile "/sdcard/Download/clang19_virtual_image" to "/dev/ov" ...
Creating and mounting the directories for the overlay mount for "/system" ...
 Creating the overlay mount for "/system" ...
 Creating the bind mount "/system"...
 Checking the overlay mount for "/system" ...
Summary:
 --------
1 overlay mount(s) created:
  /system
ASUS_I006D:/ #



Now the directory /system is writable:

ASUS_I006D:/ # touch /system/xxx.$$$
ASUS_I006D:/ #

ASUS_I006D:/ # ls -l /system/xxx.$$$
-rw-r--r-- 1 root root 0 2025-07-09 20:00 /system/xxx.4975$
ASUS_I006D:/ #


To use the clang19 toolchain from the virtual disk, init the toolchain with the command:

source /system/bin/init_clang19_env

(this command must be done once in each adb session using the clang toolchain)


Example:

source /system/bin/init_clang19_env
ASUS_I006D:/ # source /system/bin/init_clang19_env

Preparing the clang environment for creating binaries for the CPU type aarch64
The target root directory /data/local/tmp/develop/sysroot does not exist

Using clang 19                                                                            
Using the NDK /system/usr/ndk/r27b                                                         (environment variable NDK_DIR)
Using the sysroot directory /system/usr/ndk/r27b/sysroot                                   (environment variable SYSROOT)
Using the target root directory /data/local/tmp/develop/sysroot                            (environment variable TARGET_ROOT)


Environment variables used:


PATH is now:         /system/usr/clang19/bin:/product/bin:/apex/com.android.runtime/bin:/apex/com.android.art/bin:/system_ext/bin:/system/bin:/system/xbin:/odm/bin:/vendor/bin:/vendor/xbin

LD_LIBRARY_PATH:     :/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/:/system/usr/clang19/lib:/system/usr/lib

API is now:          31
NDK_DIR is now:      /system/usr/ndk/r27b

SYSROOT is now:      /system/usr/ndk/r27b/sysroot

CFLAGS are now:       -I/system/usr/clang19/include -I/system/usr/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include --sysroot=/system/usr/ndk/r27b/sysroot

CPPFLAGS are now:     -I/system/usr/clang19/include -I/system/usr/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include

CXXFLAGS are now:     -I/system/usr/clang19/include -I/system/usr/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include --sysroot=/system/usr/ndk/r27b/sysroot

LDFLAGS are now:      -L/system/usr/lib -L/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/31 -L/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android -B/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/31/ --sysroot=/system/usr/ndk/r27b/sysroot -lc
CC is now:           /system/usr/clang19/bin/clang
CXX is now:          /system/usr/clang19/bin/clang++
CPP is now:          /system/usr/clang19/bin/clang-cpp
CXXCPP is now:       /system/usr/clang19/bin/clang-cpp
AR is now:           /system/usr/clang19/bin/llvm-ar
AS is now:           /system/usr/clang19/bin/llvm-as
LD is now:           /system/usr/clang19/bin/lld
RANLIB is now:       /system/usr/clang19/bin/llvm-ranlib
STRIP is now:        /system/usr/clang19/bin/llvm-strip
PKG_CONFIG is now:   /system/usr/clang19/bin/pkg-config

Checking the clang binary ...

clang version 19.0.0git (https://android.googlesource.com/toolchain/llvm-project b3a530ec6537146650e42be89f1089e9a3588460)
Target: aarch64-unknown-linux-android
Thread model: posix
InstalledDir: /system/usr/clang19/bin

Define some aliase ...
[1752086863.227690] alias 'setlibpath=export LD_LIBRARY_PATH=:/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/:/system/usr/clang19/lib:/system/usr/lib'
[1752086863.227904] alias 'cp_crt_libs=cp ${NDK_DIR}/sysroot/usr/lib/${CPU_TYPE}-linux-android/${API}/crt*.o .'
[1752086863.228071] alias 'make_fast=make -j$( nproc )'
[1752086863.228231] alias 'cc=/system/usr/clang19/bin/clang'
[1752086863.228371] set +x
ASUS_I006D:/ #



 
(This command must be done once in each adb or ssh session)


Now you can use the tools from the clang19 toolchain to compile C, C++, and assembler source files on the phone.

Installed in the overlay filesystem on the virtual disk are most of the tools from the clang19 toolchain for installation in /data/local/tmp/sysroot -- see the github repository with the clang19 toolchain :

https://github.com/bnsmb/clang19_toolchain_for_android 

The virtual disk also contains a lot of pre-compiled libraries in the directory /system/usr/lib (including the necessary header files in the directory /system/usr/include) and the necessary files to compile binaries for arm64 CPUs from the Android NDK in the directory. /system/usr/ndk/r27b.


If a file is missing, just copy it to /system/bin or another sub directory in /system. All new files copied to one of these directories are saved in the virtual disk and will therefor survive a reboot (dito for files changes in /system)

To test the compiler use these commands:


ASUS_I006D:/ # cd /system/usr/share/examples
ASUS_I006D:/system/usr/share/examples #

ASUS_I006D:/system/usr/share/examples # clang ${CFLAGS} ${LDFLAGS} -o helloworld_in_c helloworld_in_c.c  && ./helloworld_in_c
Hello, World from a C program!
Compiled with Clang 19.0.0
ASUS_I006D:/system/usr/share/examples #

ASUS_I006D:/system/usr/share/examples # clang++ ${CXXFLAGS} ${LDFLAGS}  -o helloworld_in_c++ ./helloworld_in_c++.cpp && ./helloworld_in_c++
Hello, World from a C++ program!
Compiled with Clang 19.0.0
Compiler version: Clang 19.0.0git (https://android.googlesource.com/toolchain/llvm-project b3a530ec6537146650e42be89f1089e9a3588460)
ASUS_I006D:/system/usr/share/examples #

ASUS_I006D:/system/usr/share/examples # clang -nostdlib -static -Wl,--entry=_start -o helloworld_in_assembler helloworld_in_assembler.s && ./helloworld_in_assembler
Hello, World from an assembler program compiled with clang!
ASUS_I006D:/system/usr/share/examples #
ASUS_I006D:/system/usr/share/examples #


Another test : Download and compile the editor nano:

source /system/bin/init_clang19_env

cd /data/local/tmp

wget https://www.nano-editor.org/dist/v8/nano-8.5.tar.gz
tar -xf nano-8.5.tar.gz    
cd nano-8.5

CFLAGS="$CFLAGS -Wno-implicit-function-declaration -Wno-int-conversion -DGNULIB_LIBPOSIX"

LDFLAGS="$LDFLAGS -static"

./configure --prefix=/system --disable-nls --enable-utf8

make -j$( nproc )


The compiled nano binary is then in the directory src, e.g:


ASUS_I006D:/data/local/tmp/develop/nano-8.5 $ ls -ltr src/nano
-rwxrwxrwx 1 shell shell 3394288 2025-07-11 13:51 src/nano
ASUS_I006D:/data/local/tmp/develop/nano-8.5 $

ASUS_I006D:/data/local/tmp/develop/nano-8.5 $ file  src/nano
src/nano: ELF executable, 64-bit LSB arm64, static, for Android 31, built by NDK r27b (12297006), not stripped
ASUS_I006D:/data/local/tmp/develop/nano-8.5 $

ASUS_I006D:/data/local/tmp/develop/nano-8.5 $   src/nano --version 
 GNU nano, version 8.5
 (C) 2025 the Free Software Foundation and various contributors
 Compiled options: --disable-libmagic --disable-nls --enable-utf8
ASUS_I006D:/data/local/tmp/develop/nano-8.5 $


To replace the nano binary in the virtual disk just copy the new nano binary to /system/bin:

cp src/nano /system/bin/nano



Virtual disk with Perl 5.42 and a minimal clang19 toolchain

(see also https://xdaforums.com/t/using-a-virtual-disk-with-perl-5-42-and-a-minimal-clang19-toolchain-for-an-overlay-mount.4749262/)

I have created a virtual disk with Perl 5.42, a minimal clang19 toolchain, vim, nano and wget2 for arm64 CPUs that can be used to compile new Perl modules on the phone:

http://bnsmb.de/files/public/Android/perl542_and_clang_virtual_image.gz


Notes

This virtual disk is only a prove of concept. I did not do indepth tests and I do not plan to update the image on a a regular base.

The size of the compressed image is about 270 MB; the uncompressed virtual disk occupies 1 GB space and there are about 115 MB free space in the virtual disk.


To use the virtual disk, download the file with the virtual disk to the PC

wget http://bnsmb.de/files/public/Android/perl542_and_clang_virtual_image.gz


Copy the file to the phone

adb push perl542_and_clang_virtual_image.gz /sdcard/Download/perl542_and_clang_virtual_image.gz


uncompress it on the phone

adb shell gzip -d /sdcard/Download/perl542_and_clang_virtual_image.gz


and execute as user root in an adb shell

create_overlay_mount.sh IMAGE_FILE=/sdcard/Download/perl542_and_clang_virtual_image  /system
This command must be executed once after each reboot because overlay mounts are not persistent (-> if somethings goes wrong after creating the overlay mount just reboot the phone and you're back in buisness)


To use the clang19 from the virtual disk in an adb shell, execute this command

source /system/bin/init_clang19_env ex


Notes:

This command must be executed once in each adb session using the clang toolchain.

The parameter "ex" for init_clang19_env is optional -- the only purpose of this parameter is to print the commands to test the compiler.


Before using cpan to install perl modules, create the home directory if it does not yet exist (see also the notes below)

mkdir -p /data/local/tmp/perl_home


To test the image, install a simple Perl module like for example Scalar::Util using cpan:

cpan install Scalar::Util

cpan install
 

ASUS_I006D:/ $

# init the clang19 environment
#
ASUS_I006D:/ $ source /system/bin/init_clang19_env

Preparing the clang environment for creating binaries for the CPU type aarch64
The target root directory /data/local/tmp/develop/sysroot does not exist

Using clang 19                                                                            
Using the NDK /system/usr/ndk/r27b                                                         (environment variable NDK_DIR)
Using the sysroot directory /system/usr/ndk/r27b/sysroot                                   (environment variable SYSROOT)
Using the target root directory /data/local/tmp/develop/sysroot                            (environment variable TARGET_ROOT)


Environment variables used:


PATH is now:         /system/usr/bin:/system/usr/clang19/bin:/product/bin:/apex/com.android.runtime/bin:/apex/com.android.art/bin:/system_ext/bin:/system/bin:/system/xbin:/odm/bin:/vendor/bin:/vendor/xbin

LD_LIBRARY_PATH:     :/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/:/system/usr/clang19/lib:/system/usr/lib

API is now:          31
NDK_DIR is now:      /system/usr/ndk/r27b

SYSROOT is now:      /system/usr/ndk/r27b/sysroot

CFLAGS are now:       -I/system/usr/clang19/include -I/system/usr/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include --sysroot=/system/usr/ndk/r27b/sysroot

CPPFLAGS are now:     -I/system/usr/clang19/include -I/system/usr/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include

CXXFLAGS are now:     -I/system/usr/clang19/include -I/system/usr/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include --sysroot=/system/usr/ndk/r27b/sysroot

LDFLAGS are now:      -L/system/usr/lib -L/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/31 -L/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android -B/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/31/ --sysroot=/system/usr/ndk/r27b/sysroot -lc
CC is now:           /system/usr/clang19/bin/clang
CXX is now:          /system/usr/clang19/bin/clang++
CPP is now:          /system/usr/clang19/bin/clang-cpp
CXXCPP is now:       /system/usr/clang19/bin/clang-cpp
AR is now:           /system/usr/clang19/bin/llvm-ar
AS is now:           /system/usr/clang19/bin/llvm-as
LD is now:           /system/usr/clang19/bin/lld
RANLIB is now:       /system/usr/clang19/bin/llvm-ranlib
STRIP is now:        /system/usr/clang19/bin/llvm-strip
PKG_CONFIG is now:   /system/usr/clang19/bin/pkg-config

Checking the clang binary ...

clang version 19.0.0git (https://android.googlesource.com/toolchain/llvm-project b3a530ec6537146650e42be89f1089e9a3588460)
Target: aarch64-unknown-linux-android
Thread model: posix
InstalledDir: /system/usr/clang19/bin

Define some aliase ...
[1752212875.848172] alias 'setlibpath=export LD_LIBRARY_PATH=:/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/:/system/usr/clang19/lib:/system/usr/lib'
[1752212875.848379] alias 'cp_crt_libs=cp ${NDK_DIR}/sysroot/usr/lib/${CPU_TYPE}-linux-android/${API}/crt*.o .'
[1752212875.848569] alias 'make_fast=make -j$( nproc )'
[1752212875.848735] alias 'cc=/system/usr/clang19/bin/clang'
[1752212875.848905] set +x
ASUS_I006D:/ $
ASUS_I006D:/ $

ASUS_I006D:/ $ cpan install Scalar::Util
Loading internal logger. Log::Log4perl recommended for better logging

CPAN.pm requires configuration, but most of it can be done automatically.
If you answer 'no' below, you will enter an interactive dialog for each
configuration option instead.

Would you like to configure as much as possible automatically? [yes]

Trying with
    /system/bin/wget -O "/data/local/tmp/perl_home/.cpan/sources/authors/01mailrc.txt.gz.tmp5308"
to get
    https://cpan.org/authors/01mailrc.txt.gz
HTTP response 301  [https://cpan.org/authors/01mailrc.txt.gz]
Adding URL: https://www.cpan.org/authors/01mailrc.txt.gz
Saving '/data/local/tmp/perl_home/.cpan/sources/authors/01mailrc.txt.gz.tmp5308'
HTTP response 200  [https://www.cpan.org/authors/01mailrc.txt.gz]
/data/local/tmp/perl 100% [============================================================================================================>]  243.98K  149.99KB/s
                          [Files: 1  Bytes: 243.98K [96.70KB/s] Redirects: 1  Todo: 0  Errors: 0                                        ]
Reading '/data/local/tmp/perl_home/.cpan/sources/authors/01mailrc.txt.gz'
............................................................................DONE

Trying with
    /system/bin/wget -O "/data/local/tmp/perl_home/.cpan/sources/modules/02packages.details.txt.gz.tmp5308"
to get
    https://cpan.org/modules/02packages.details.txt.gz
HTTP response 301  [https://cpan.org/modules/02packages.details.txt.gz]
Adding URL: https://www.cpan.org/modules/02packages.details.txt.gz
Saving '/data/local/tmp/perl_home/.cpan/sources/modules/02packages.details.txt.gz.tmp5308'
HTTP response 200  [https://www.cpan.org/modules/02packages.details.txt.gz]
/data/local/tmp/perl 100% [============================================================================================================>]    2.45M  155.90KB/s
                          [Files: 1  Bytes: 2.45M [155.11KB/s] Redirects: 1  Todo: 0  Errors: 0                                         ]
Reading '/data/local/tmp/perl_home/.cpan/sources/modules/02packages.details.txt.gz'
  Database was generated on Thu, 10 Jul 2025 23:29:02 GMT
  HTTP::Date not available
............................................................................DONE

Trying with
    /system/bin/wget -O "/data/local/tmp/perl_home/.cpan/sources/modules/03modlist.data.gz.tmp5308"
to get
    https://cpan.org/modules/03modlist.data.gz
HTTP response 301  [https://cpan.org/modules/03modlist.data.gz]
Adding URL: https://www.cpan.org/modules/03modlist.data.gz
Saving '/data/local/tmp/perl_home/.cpan/sources/modules/03modlist.data.gz.tmp5308'
HTTP response 200  [https://www.cpan.org/modules/03modlist.data.gz]
/data/local/tmp/perl 100% [============================================================================================================>]     248     --.-KB/s
                          [Files: 1  Bytes: 248  [928 B/s] Redirects: 1  Todo: 0  Errors: 0                                             ]
Reading '/data/local/tmp/perl_home/.cpan/sources/modules/03modlist.data.gz'
DONE
Writing /data/local/tmp/perl_home/.cpan/Metadata
Running install for module 'Scalar::Util'

Trying with
    /system/bin/wget -O "/data/local/tmp/perl_home/.cpan/sources/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz.tmp5308"
to get
    https://cpan.org/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz
HTTP response 301  [https://cpan.org/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz]
Adding URL: https://www.cpan.org/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz
Saving '/data/local/tmp/perl_home/.cpan/sources/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz.tmp5308'
HTTP response 200  [https://www.cpan.org/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz]
/data/local/tmp/perl 100% [============================================================================================================>]  177.18K  192.67KB/s
                          [Files: 1  Bytes: 177.18K [123.47KB/s] Redirects: 1  Todo: 0  Errors: 0                                       ]

Trying with
    /system/bin/wget -O "/data/local/tmp/perl_home/.cpan/sources/authors/id/P/PE/PEVANS/CHECKSUMS.tmp5308"
to get
    https://cpan.org/authors/id/P/PE/PEVANS/CHECKSUMS
HTTP response 301  [https://cpan.org/authors/id/P/PE/PEVANS/CHECKSUMS]
Adding URL: https://www.cpan.org/authors/id/P/PE/PEVANS/CHECKSUMS
Saving '/data/local/tmp/perl_home/.cpan/sources/authors/id/P/PE/PEVANS/CHECKSUMS.tmp5308'
HTTP response 200  [https://www.cpan.org/authors/id/P/PE/PEVANS/CHECKSUMS]
/data/local/tmp/perl 100% [============================================================================================================>]  452.19K  155.75KB/s
                          [Files: 1  Bytes: 452.19K [137.40KB/s] Redirects: 1  Todo: 0  Errors: 0                                       ]
Checksum for /data/local/tmp/perl_home/.cpan/sources/authors/id/P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz ok
'YAML' not installed, will not store persistent state
Configuring P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz with Makefile.PL
Checking if your kit is complete...
Looks good
Unrecognized argument in LIBS ignored: '/data/local/tmp/develop/sysroot/usr/lib/libcrypt.a'
Generating a Unix-style Makefile
Writing Makefile for List::Util
Writing MYMETA.yml and MYMETA.json
  PEVANS/Scalar-List-Utils-1.69.tar.gz
  /system/usr/bin/perl Makefile.PL -- OK
Running make for P/PE/PEVANS/Scalar-List-Utils-1.69.tar.gz
cp lib/List/Util.pm blib/lib/List/Util.pm
cp lib/Scalar/List/Utils.pm blib/lib/Scalar/List/Utils.pm
cp lib/Sub/Util.pm blib/lib/Sub/Util.pm
cp lib/Scalar/Util.pm blib/lib/Scalar/Util.pm
cp lib/List/Util/XS.pm blib/lib/List/Util/XS.pm
Running Mkbootstrap for Util ()
chmod 644 "Util.bs"
"/system/usr/bin/perl" -MExtUtils::Command::MM -e 'cp_nonempty' -- Util.bs blib/arch/auto/List/Util/Util.bs 644
"/system/usr/bin/perl" "/system/usr/lib/perl5/5.42.0/ExtUtils/xsubpp"  -typemap '/system/usr/lib/perl5/5.42.0/ExtUtils/typemap'  ListUtil.xs > ListUtil.xsc
mv ListUtil.xsc ListUtil.c
cc -c   -fPIE -fPIC -pie --std=gnu99 --sysroot=/system/usr/ndk/r27b/sysroot -I/system/usr/clang19/include -I/system/usr/ndk/r27b/include -I/system/usr/ndk/r27b/sysroot/usr/include -I/data/local/tmp/develop/sysroot/usr/include --sysroot=/system/usr/ndk/r27b/sysroot -Wno-implicit-function-declaration -Wno-int-conversion -DHAS_SHMAT_PROTOTYPE -DNO_LOCALE -DNO_LOCALE_CTYPE -DNO_LOCALE_NUMERIC -DNO_LOCALE_COLLATE -DNO_LOCALE_TIME -DNO_LOCALE_MESSAGES -DNO_LOCALE_MONETARY -DNO_LOCALE_ADDRESS -DNO_LOCALE_IDENTIFICATION -DNO_LOCALE_MEASUREMENT -DNO_LOCALE_PAPER -DNO_LOCALE_TELEPHONE -DNO_LOCALE_NAME -DNO_LOCALE_SYNTAX -DNO_LOCALE_TOD -fPIC -O2   -DVERSION=\"1.69\" -DXS_VERSION=\"1.69\" -fPIC --sysroot=/system/usr/ndk/r27b/sysroot -B/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android//31 "-I/system/usr/lib/perl5/5.42.0/aarch64-linux-android/CORE"  -DPERL_EXT -DUSE_PPPORT_H ListUtil.c
cc: warning: argument unused during compilation: '-pie' [-Wunused-command-line-argument]
In file included from ListUtil.xs:8:
In file included from /system/usr/lib/perl5/5.42.0/aarch64-linux-android/CORE/perl.h:46:
/system/usr/lib/perl5/5.42.0/aarch64-linux-android/CORE/config.h:1906:9: warning: 'HAS_SHMAT_PROTOTYPE' macro redefined [-Wmacro-redefined]
 1906 | #define HAS_SHMAT_PROTOTYPE     /**/
      |         ^
<command line>:1:9: note: previous definition is here
    1 | #define HAS_SHMAT_PROTOTYPE 1
      |         ^
1 warning generated.
rm -f blib/arch/auto/List/Util/PL_List__Util.so
cc  -shared -O2 --sysroot=/system/usr/ndk/r27b/sysroot -L/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android/31 -L/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android -L/data/local/tmp/develop/sysroot/usr/lib -fPIC --sysroot=/system/usr/ndk/r27b/sysroot -B/system/usr/ndk/r27b/sysroot/usr/lib/aarch64-linux-android//31 --sysroot=/system/usr/ndk/r27b/sysroot  ListUtil.o  -o blib/arch/auto/List/Util/PL_List__Util.so  \
   -ldl -lm -lc   \
 
chmod 755 blib/arch/auto/List/Util/PL_List__Util.so
  PEVANS/Scalar-List-Utils-1.69.tar.gz
  /system/usr/clang19/bin/make -- OK
The current configuration of allow_installing_outdated_dists is 'ask/no', but for this option we would need 'CPAN::DistnameInfo' installed. Please install 'CPAN::DistnameInfo' as soon as possible. As long as we are not equipped with 'CPAN::DistnameInfo' this option does not take effect
Running make test for PEVANS/Scalar-List-Utils-1.69.tar.gz
"/system/usr/bin/perl" -MExtUtils::Command::MM -e 'cp_nonempty' -- Util.bs blib/arch/auto/List/Util/Util.bs 644
PERL_DL_NONLAZY=1 "/system/usr/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00version.t ......... ok  
t/any-all.t ........... ok    
t/blessed.t ........... ok    
t/dualvar.t ........... ok    
t/exotic_names.t ...... ok        
t/first.t ............. ok    
t/getmagic-once.t ..... ok  
t/head-tail.t ......... ok    
t/isvstring.t ......... ok  
t/lln.t ............... ok    
t/max.t ............... ok    
t/maxstr.t ............ ok  
t/mesh.t .............. ok  
t/min.t ............... ok    
t/minstr.t ............ ok  
t/openhan.t ........... ok    
t/pair.t .............. ok    
t/product.t ........... ok    
t/prototype.t ......... ok    
t/readonly.t .......... ok    
t/reduce.t ............ ok    
t/reductions.t ........ ok  
t/refaddr.t ........... ok    
t/reftype.t ........... ok    
t/rt-96343.t .......... ok  
t/sample.t ............ ok  
t/scalarutil-proto.t .. ok    
t/shuffle.t ........... ok  
t/stack-corruption.t .. ok  
t/subname.t ........... ok    
t/sum.t ............... ok    
t/sum0.t .............. ok  
t/tainted.t ........... ok  
t/undefined-block.t ... ok    
t/uniq.t .............. ok    
t/uniqnum.t ........... ok    
t/weak.t .............. ok    
t/zip.t ............... ok  
All tests successful.
Files=38, Tests=2160,  4 wallclock secs ( 0.46 usr  0.14 sys +  2.69 cusr  0.89 csys =  4.18 CPU)
Result: PASS
  PEVANS/Scalar-List-Utils-1.69.tar.gz
  /system/usr/clang19/bin/make test -- OK
Running make install for PEVANS/Scalar-List-Utils-1.69.tar.gz
"/system/usr/bin/perl" -MExtUtils::Command::MM -e 'cp_nonempty' -- Util.bs blib/arch/auto/List/Util/Util.bs 644
Files found in blib/arch: installing files in blib/lib into architecture dependent library tree
Installing /data/local/tmp/perl_home/lib/perl5/aarch64-android/auto/List/Util/PL_List__Util.so
Installing /data/local/tmp/perl_home/lib/perl5/aarch64-android/List/Util.pm
Installing /data/local/tmp/perl_home/lib/perl5/aarch64-android/List/Util/XS.pm
Installing /data/local/tmp/perl_home/lib/perl5/aarch64-android/Scalar/Util.pm
Installing /data/local/tmp/perl_home/lib/perl5/aarch64-android/Scalar/List/Utils.pm
Installing /data/local/tmp/perl_home/lib/perl5/aarch64-android/Sub/Util.pm
Appending installation info to /data/local/tmp/perl_home/lib/perl5/aarch64-android/perllocal.pod
  PEVANS/Scalar-List-Utils-1.69.tar.gz
  /system/usr/clang19/bin/make install  -- OK
ASUS_I006D:/ $

ASUS_I006D:/ $ ls -l /data/local/tmp/perl_home/lib/perl5/aarch64-android/
total 16
drwxr-xr-x 3 shell shell 3452 2025-07-11 07:48 List
drwxr-xr-x 3 shell shell 3452 2025-07-11 07:48 Scalar
drwxr-xr-x 2 shell shell 3452 2025-07-11 07:48 Sub
drwxr-xr-x 3 shell shell 3452 2025-07-11 07:48 auto
-rw-rw-rw- 1 shell shell  233 2025-07-11 07:48 perllocal.pod
ASUS_I006D:/ $


----


All perl executables in the virtual disk use a wrapper script:

ASUS_I006D:/ # cat /system/bin/perl_env ^C                                                                                                                                                                          
130|ASUS_I006D:/ # ls -l /system/bin  | grep perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 cpan -> ./perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 instmodsh -> ./perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 perl -> ./perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 perl5.42.0 -> ./perl_wrapper
-rwxr-xr-x 1 root root       241 2025-07-10 07:13 perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 perlbug -> ./perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 perldoc -> ./perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 perlivp -> ./perl_wrapper
lrwxrwxrwx 1 root root        14 2025-07-10 07:13 perlthanks -> ./perl_wrapper
ASUS_I006D:/ #


The wrapper script perl_wrapper reads and executes the file /system/bin/perl_env to init the perl environment before executing the "real" perl executable.

The script /system/bin/perl_env uses the home directory /data/local/tmp/perl_home. To change this, edit the file /system/bin/perl_env or set the environment variable HOME to another existing directory before executing cpan or any other perl executable.

Perl modules installed via cpan will be installed in the directory ${HOME}/perl5/lib. To change this behaviour, edit the environment variables in the file /system/bin/perl_env.

Note also that the script /system/bin/perl_env reads and executes the file ${HOME}/perl_env if it exists

cat /system/bin/perl_env
ASUS_I006D:/system/usr/share/examples # cat /system/bin/perl_env

# LD_LIBRARY_PATH is not required for this Perl binary or the compiled perl modules
# export LD_LIBRARY_PATH=/system/usr/lib:${LD_LIBRARY_PATH}

PERL_HOME_DIR="/data/local/tmp/perl_home"

if [ "${HOME}"x = ""x -o "${HOME}"x = "/"x ] ; then
  export HOME="${PERL_HOME_DIR}"
else
  PERL_HOME_DIR="${HOME}"
fi

export PERL5LIB="${PERL_HOME_DIR}/lib/perl5:/system/usr/lib/perl5/5.42.0"

export PERL_LOCAL_LIB_ROOT="${PERL_HOME_DIR}"

export PERL_MB_OPT="--install_base ${PERL_HOME_DIR}"
export PERL_MM_OPT="INSTALL_BASE=${PERL_HOME_DIR}"

USER_DEFINED_PERL_INIT_FILE="${PERL_HOME_DIR}/perl_env"

if [ -r "${USER_DEFINED_PERL_INIT_FILE}" ] ; then
  echo "${USER_DEFINED_PERL_INIT_FILE} found - now executing it ..."
  echo
  source "${USER_DEFINED_PERL_INIT_FILE}"
fi

ASUS_I006D:/system/usr/share/examples #

----

No root access is required to run cpan to install new Perl modules as long as the user running cpan has write access to the home directory.

 

Test Environment



ASUS Zenfone 8 with

ASUS Android 13 Beta for ASUS Zenfone 8
ASUS Android 13 for ASUS Zenfone 8
/e/ 3.0 (= Android 13)
LineageOS 20 (= Android 13)
LineageOS 21 (= Android 14)
LineageOS 22 (= Android 15)
StatixOS v7.10 (= Android 14)
OmniROM 14 (= Android 14)
OmniROM 15 (= Android 15)
OmniROM 16 (= Android 16)

Note:

According to ChatGPT the overlay mount functionality does not work on all Android versions (but ChatGTP is sometimes also a great liar ...)


Limitations




Mounts to subdirectories on separate partitions (/dev/block/s*) such as /vendor/dsp in /vendor are remounted after the overlay mount has been created. Please note that there are NO overlay mounts for these mounts!

Example
ASUS_I006D:/data/local/tmp # df -h | grep " /vendor"
/dev/block/dm-4   1.1G 1.1G  3.5M 100% /vendor
/dev/block/sde4   220M 173M   47M  79% /vendor/firmware_mnt
/dev/block/sde9    59M  41M   18M  70% /vendor/dsp
/dev/block/sde5    64M 1.0M   63M   2% /vendor/bt_firmware
/dev/block/sda17  496M 404K  496M   1% /vendor/xrom
ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  /vendor mount
The image file "/data/local/tmp/image001" already exists - there should already be a filesystem

Creating and mounting the directories for the overlay mount for "/vendor" ...
Creating the overlay mount for "/vendor" ...
Creating the bind mount "/vendor"...
Remounting the mount point "/vendor/bt_firmware" ...
Remounting the mount point "/vendor/dsp" ...
Remounting the mount point "/vendor/firmware_mnt" ...
Remounting the mount point "/vendor/xrom" ...
Checking the overlay mount for "/vendor" ...

Summary:
--------

1 overlay mount(s) created:

  /vendor

ASUS_I006D:/data/local/tmp #


ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh  /vendor umount
Umounting the bind mounts ...
Umounting the mounted sub directories ...
Umounting "/vendor/bt_firmware" ...
Umounting "/vendor/dsp" ...
Umounting "/vendor/firmware_mnt" ...
Umounting "/vendor/xrom" ...
Umounting the bind mount  "/vendor" ...
 ... done
Umounting the overlay mounts ...
Umounting "/dev/ov/merged/vendor" ...
 ... done

ASUS_I006D:/data/local/tmp #





The filesystems vfat and f2fs do not support overlay mounts; there maybe other filesystems also not supporting overlay mounts.


Trouble Shooting



An overlay mount for sub directories like /system_ext/bin or /system/etc may or may not work.

If it does not work, the files in the sub directory with overlay mount do not have any permission, example:

ASUS_I006D:/data/local/tmp # ls -ldZ /system_ext/bin/*
---------- 1 root root  u:object_r:unlabeled:s0   0 1970-01-04 04:35 /system_ext/bin/adb_root
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0  16 1970-01-04 04:35 /system_ext/bin/bash -> /system/bin/bash
---------- 1 root root  u:object_r:unlabeled:s0   0 1970-01-04 04:35 /system_ext/bin/dpmd
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0   3 1970-01-04 04:35 /system_ext/bin/eview -> vim
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0   3 1970-01-04 04:35 /system_ext/bin/evim -> vim
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0   3 1970-01-04 04:35 /system_ext/bin/ex -> vim
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0   3 1970-01-04 04:35 /system_ext/bin/gview -> vim
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0   3 1970-01-04 04:35 /system_ext/bin/gvim -> vim
lrwxrwxrwx 1 root root  u:object_r:unlabeled:s0   3 1970-01-04 04:35 /system_ext/bin/gvimdiff -> vim
---------- 1 root root  u:object_r:unlabeled:s0   0 1970-01-04 04:35 /system_ext/bin/htop
---------- 1 root root  u:object_r:unlabeled:s0   0 1970-01-04 04:35 /system_ext/bin/nano
...

create_overlay_mount.sh prints a warning in this case, example:

WARNING: Seems like the overlay mount for "/system_ext/bin" works only partial -- please check the directory contents


To work around this problem, create an overlay mount for the upper directory (e.g. /system or /system_ext) -- at least in my tests, overlay mounts for these directories have always worked.





Umounting /system will fail in most cases due to open files, as the umount command uses libraries from /system/lib64. To "fix" this error, use a statically linked umount binary.

A statically linked umount binary for arm64 CPUs is available here: umount

Either add the statically linked umount binary to a directory in the PATH before /system/bin or set the environment variable UMOUNT before starting the script, e.g:

copy the statically linked umount to /data/local/tmp and execute:


UMOUNT=/data/local/tmp/umount  /data/local/tmp/create_overlay_mount.sh umount /system

or

/data/local/tmp/create_overlay_mount.sh umount /system UMOUNT=/data/local/tmp/umount


If the umount of /system still fails, use a statically linked shell instead of sh.
A statically linked bash binary for arm64 CPUs is available here: bash-static-stripped

Copy the statically linked bash binary to /data/local/tmp and use this command to umount /system:

UMOUNT=/data/local/tmp/umount /data/local/tmp/bash-static-stripped /data/local/tmp/create_overlay_mount.s umount /system


Example

ASUS_I006D:/ # UMOUNT=/data/local/tmp/umount  /data/local/tmp/bash-static-stripped   /data/local/tmp/create_overlay_mount.sh umount /system
Umounting the bind mounts ...
Umounting "/system" ...
 ... done

ASUS_I006D:/ #


It's recommended to change the shebang in the first line in the script create_overlay_mount.sh to use the statically linked bash binary, e.g

ASUS_I006D:/data/local/tmp # diff ./create_overlay_mount.sh.or  ./create_overlay_mount.sh.original
create_overlay_mount.sh.org          create_overlay_mount.sh.original
ASUS_I006D:/data/local/tmp # diff ./create_overlay_mount.sh.original   ./create_overlay_mount.sh                                                                                                                               
--- ./create_overlay_mount.sh.original    2025-06-23 14:38:23.000000000 +0200
+++ ./create_overlay_mount.sh    2025-06-23 14:59:15.979999758 +0200
@@ -1,4 +1,4 @@
-#!/system/bin/sh
+#!/data/local/tmp/bin/bash-static-stripped
 #
 #h#
 #h# create_overlay_mount.sh <VERSION> - create one or more overlay mounts on a device running a rooted Android OS
1|ASUS_I006D:/data/local/tmp #


If creating a overlay mount for /system be careful not to replace one of the symbolic links for toybox!


Use the script parameter -v or --verbose to print more messages


Set the variable TRACE to any string before executing the script to run it with "set -x"


Most problems with overlay mounts are caused by missing or invalid SELinux contexts for the files and directories for which an overlay mount is configured. It is therefore recommended to
temporarily disable SELinux either by using the command

setenforce 0

or use the script parameter "--noselinux"

Start a parallel adb session with the command

logcat | grep denied

or, on the PC, :

adb logcat | grep denied

while testing the overlay mounts.


To access the original files while an overlay mount is in place without umounting the bind mount this approch can be used.

Example:

Read the original /system/etc/hosts after changing the file via overlay mount:


ASUS_I006D:/ # /data/local/tmp/create_overlay_mount.sh get /system
/data/local/tmp/ov/upper/system # /system

ASUS_I006D:/ #

ASUS_I006D:/ # cat /system/etc/hosts
127.0.0.1       localhost
::1             ip6-localhost
ASUS_I006D:/ #

ASUS_I006D:/ # echo "1.1.1.1 dnsserver" >>/system/etc/hosts
ASUS_I006D:/ #

ASUS_I006D:/ # cat /system/etc/hosts
127.0.0.1       localhost
::1             ip6-localhost
1.1.1.1 dnsserver
ASUS_I006D:/ #


# Create a temporary bind mount for / to access the original files

#
ASUS_I006D:/ # mkdir -p /mnt/root
ASUS_I006D:/ #

ASUS_I006D:/ # mount -o bind / /mnt/root
ASUS_I006D:/ #

ASUS_I006D:/ # cat /mnt/root/system/etc/hosts
127.0.0.1       localhost
::1             ip6-localhost
ASUS_I006D:/ #



If the contents of a directory with overlay mount look weird, remount the overlay directory using the script with the parameter "remount" and check the directory contents again.

Example

ASUS_I006D:/data/local/tmp # /data/local/tmp/create_overlay_mount.sh remount system                                                                                                              
Remounting the overlay mounts ...
Remounting "/system" ...
 ... done

ASUS_I006D:/data/local/tmp #


and check again.


Additional infos


The Magisk Module magisk_overlayfs


If Magisk is installed, the Magisk module for implementing overlay mounts can be used to create overlay mounts.

This Magisk Module creates the overlay mounts very early in the boot process . Therefore, the overlay mounts created by this Magisk module do not overwrite bind mounts created by other Magisk modules and "su" via Magisk is still possible in adb sessions when using this Magisk module.


This Magisk module also works in the Android 15.

See How to create Magisk Modules that install new files in system for Details using this Magisk Module


Notes


The virtual disk used by the Magisk Module for implementing overlay mounts, /data/adb/overlay, can also be used with the script create_overlay_mount.sh:

IMAGE_FILE=/data/adb/overlay  ./create_overlay_mount.sh  default /vendor_dlkm /odm_dlkm


Do not use the Magisk module for implementing overlay mounts and the script create_overlay_mount.sh in parallel!



Downloads



create_overlay_mount.sh


Statically linked binaries for arm64 CPUs:

umount
bash-static-stripped

mount
losetup


The binaries are also available in a github repository: 

https://github.com/bnsmb/binaries-for-Android


A virtual disk with a clang21 toolchain for arm64 CPUs is available here

http://bnsmb.de/files/public/Android/clang21_virtual_image.gz


A virtual disk with a clang19 toolchain for arm64 CPUs is available here

http://bnsmb.de/files/public/Android/clang19_virtual_image.gz


A virtual disk with only Perl 5.42 and clang19 for arm64 CPUs is available here:

http://bnsmb.de/files/public/Android/perl542_and_clang_virtual_image.gz


Links

 

The Linux Kernel - overlay filesystems

How to use Overlay FS?

My HowTos for Android


Back to top