File System & Bind Mounts
Relevant source files
The following files were used as context for generating this wiki page:
File systems and bind mounts are fundamental to the operation of Linux environments within Termux. In this project, they enable isolated root file systems (RootFS) to access host Android resources such as the /sdcard, kernel interfaces like /proc and /sys, and shared memory for graphical applications.
The implementation differs significantly between Chroot (which requires root and uses the busybox mount command) and PRoot (which operates in user-space and uses the -b or --bind flag to intercept system calls).
Sources: Documentation/terminology.md:5-12, Documentation/chroot/ubuntu_chroot.md:53-70, Documentation/proot/kalinethunter_proot.md:43-55
Chroot File System Architecture
Chroot environments create a "directory jail" that allows running programs within an isolated file system structure. To function as a full Linux system, several critical host directories must be bind-mounted into the chroot directory.
Mandatory System Mounts
For a Chroot environment to be functional, the following virtual file systems and device nodes must be mounted:
| Mount Point (Internal) | Source (Host/Type) | Purpose |
|---|---|---|
/dev | /dev | Access to hardware device nodes |
/sys | /sys | Interface to kernel and hardware drivers |
/proc | /proc | Process information and kernel parameters |
/dev/pts | devpts | Pseudo-terminal support for shells |
/dev/shm | tmpfs | Shared memory, required for Electron apps |
/sdcard | /sdcard | Access to Android internal storage |
Sources: Documentation/chroot/ubuntu_chroot.md:60-70, Documentation/chroot/arch_chroot.md:73-81, Documentation/chroot/debian_chroot.md:144-154
Chroot Initialization Flow
The initialization process involves remounting the Android /data partition to allow setuid binaries, followed by sequential bind mounts.
This sequence ensures that the guest environment has necessary permissions and hardware access before the shell is spawned.
Sources: Documentation/chroot/ubuntu_chroot.md:57-73, Documentation/chroot/arch_chroot.md:72-84
PRoot Bind Mounts
PRoot provides a user-space implementation of bind mounting. Unlike Chroot, which uses the kernel's mount system, PRoot intercepts system calls to redirect file paths. This allows unrooted users to map host directories into the guest environment.
Command Structure
In PRoot, bind mounts are defined using the -b flag within the command string. A common requirement in this project is binding the Termux temporary directory to the guest /tmp to facilitate X11 communication.
# Example PRoot bind configuration
-b /data/data/com.termux/files/usr/tmp:/tmp
Sources: Documentation/proot/kalinethunter_proot.md:43-46, Documentation/terminology.md:10-12
Mapping and Redirection Logic
PRoot uses a specific command-line structure to define the environment:
Shared Memory and Temporary Files
Shared memory (/dev/shm) and temporary directories (/tmp) are critical for graphical performance and application stability.
Electron and Graphical Apps
Many modern applications (including those based on Electron) require a functional /dev/shm. In Chroot, this is manually mounted as a tmpfs with a specific size (usually 256M).
Sources: Documentation/chroot/ubuntu_chroot.md:66-67, Documentation/chroot/arch_chroot.md:80-81
Hardware Acceleration Mounts
For Hardware Acceleration to function, the guest environment must share the same temporary directory as the host Termux instance. This allows the virgl_test_server running in Termux to communicate with the application inside the Chroot/PRoot environment.
- Requirement: Bind
$PREFIX/tmpto the guest/tmp. - Chroot Example:
sudo busybox mount --bind $PREFIX/tmp /data/local/tmp/chrootubuntu/tmp - PRoot Example:
-b /data/data/com.termux/files/usr/tmp:/tmp
Sources: Documentation/HardwareAcceleration.md:31-40, Documentation/chroot/ubuntu_chroot.md:118-119
Security and Permission Considerations
Bind mounts in Chroot require specific handling of the /data partition. Android typically mounts /data with the nosuid flag for security. To run a full Linux distribution, this must be changed:
- Setuid Fix: The command
busybox mount -o remount,dev,suid /datais executed at the start of chroot scripts. - Path Resolution: DNS resolution is maintained by manually creating or overwriting
/etc/resolv.confwithin the guest RootFS after the initial mount process.
Sources: Documentation/chroot/ubuntu_chroot.md:57-58, Documentation/chroot/arch_chroot.md:72-73, Documentation/chroot/debian_chroot.md:175-176
Summary
The file system strategy in this project relies on bridging the gap between the Android host and the Linux guest. Chroot uses kernel-level bind mounts for high performance and full system compatibility (requiring root), while PRoot uses system call interception for a user-space experience. Both methods prioritize mapping /dev, /proc, /sys, and temporary socket directories to enable hardware acceleration and graphical output.