Hybrid Mount

AtomGit · GitHub · 简体中文 · Contributing

Hybrid Mount is a hybrid mount meta-module for KernelSU and APatch. During boot, it scans other modules and selects OverlayFS, Magic Mount, VFS, or ignore for each entry according to global, module, and path rules. Module source directories are always treated as read-only input.

Features

• OverlayFS, Magic Mount, and VFS can be mixed per module and per path.
• Path rules take precedence over module defaults, and module defaults take precedence over the global default.
• OverlayFS supports both tmpfs and ext4 storage modes.
• For ext4 staging, KernelSU uses the official ioctl to hide sysfs nodes; APatch and other non-KSU environments use the bundled LKM compatibility fallback by default.
• Magic Mount supports files, directories, symbolic links, .replace, and whiteout semantics.
• VFS sends injection rules through the keyring to hybridmount or an existing compatible NoMount kernel provider. Releases ship the sources and a prebuilt aarch64 module per supported Android/GKI target, which the boot pipeline loads when the kernel does not already carry one; if that fails it falls back according to vfs_strict. VFS is not a real mount.
• The WebUI provides MD3 (default) and Miuix interfaces.
• arm64, armv7, x86_64, and riscv64 are supported; the installer automatically selects the matching binary. The riscv64 build requires the Android NDK r27 or newer.

Installation

Download the ZIP from Releases and install it with the KernelSU or APatch manager. On first installation, use the volume keys to select the default backend. Upgrades preserve /data/adb/hybrid-mount/config.toml.

Mounting runs after module post-fs-data.sh scripts: at post-mount on APatch and metamount on KernelSU.

Configuration

Default configuration:

moduledir = "/data/adb/modules"
overlay_mode = "ext4" # ext4 | tmpfs
disable_umount = false
default_mode = "overlay" # overlay | magic | vfs
extra_mount = []

[rules.example_module]
default_mode = "magic"

[rules.example_module.paths]
"system/etc/hosts" = "overlay"

Rule paths are relative to the module root. Module-level and path-level rules may also use ignore; the global default backend accepts overlay, magic, or vfs. vfs_strict = true makes startup fail when VFS is unavailable, and vfs_isolate_uids lists the UIDs that should see the native filesystem. The same file path cannot be assigned to more than one backend. Overlay and Magic, the two real mount backends, may share ordinary directories as structural nodes; VFS is a third injection path rather than a real mount. File, type, and .replace conflicts cause the startup planning stage to fail immediately. Configuration changes take effect after reboot.

This routing does not change the project's existing CONFIG_TMPFS_XATTR capability check. On KernelSU, installation removes the module's entire lkm/ directory and runtime uses only the official NukeExt4Sysfs ioctl. APatch and other non-KSU installations keep the LKM and try it by default after mounting ext4 staging. The bundled .ko files support aarch64 only. Automatic selection requires an exact kernel line and Android/GKI tag match; unknown combinations are rejected. Prebuilt LKMs must still be validated for ABI compatibility on the corresponding real device. If the device crashes during insmod, a persistent circuit-breaker marker prevents the LKM from loading again on the next boot while preserving the rest of Hybrid Mount. See module/lkm/README.md for the support matrix, checksums, sources, and licenses.

extra_mount = ["my_extra"] reads <module>/my_extra/ into /my_extra/. Each target must already be a directory, with no corresponding /system/my_extra entry (including a dangling symlink). Use single partition names, not paths; invalid entries are logged and skipped, and apex remains excluded. Modules without system/ work and still honor disable, remove, skip_mount, and the module blacklist. Existing built-in partition handling is preserved. Additional entries use the same backend and path rules, for example "my_extra/etc/file" = "magic". WebUI preserves this field when saving settings; edit it in config.toml and reboot to apply it.

Upgrades accept the retired partitions key in its former array or comma-separated string form. It is ignored without discarding other settings or rules, and omitted from WebUI responses and subsequent configuration saves. Use extra_mount for additional partition roots. Unknown keys and malformed values still cause boot configuration loading to fail.

VFS backend

Hybrid Mount can use built-in or loadable hybridmount, or an existing NoMount kernel provider that reports protocol 20, 21, or 22. When NoMount is detected, the boot pipeline skips loading hybridmount. Hybrid Mount's path-only opaque directory rules (including .replace) require hybridmount.

How the provider is identified. The boot decision keys on a read-only probe of the kernel key type hybridmount: if it answers with a supported version, the provider is usable. Separately, vfs-doctor classifies how it is present — an entry in /proc/modules means a loadable module registered it, a /sys/module/hybridmount directory without that entry means it is compiled into the kernel image, and if neither exists then no provider is present. Probing is read-only, so status and vfs-doctor never trigger an insmod.

This is the beginning of the README. Read the rest at the original. Read the full README ↗