termux-exec

When system_linker_exec is active, /proc/pid/exe points to /system/bin/linker64 instead of the actual executable. To find the real path of the executable being run, software should use the TERMUX_EXEC__PROC_SELF_EXE environment variable.

Warning: If you unset LD_PRELOAD in a current process, TERMUX_EXEC__PROC_SELF_EXE will not be automatically updated for subsequent nested exec() calls. You must manually unset it in the first nested process to prevent incorrect values from being passed down.

# Example of preventing issues when unsetting LD_PRELOAD:
system_linker_exec optional: LD_PRELOAD= $TERMUX__PREFIX/bin/sh -c 'echo $TERMUX_EXEC__PROC_SELF_EXE'; $TERMUX__PREFIX/bin/dash -c "echo \$TERMUX_EXEC__PROC_SELF_EXE"

system_linker_exec mandatory: LD_PRELOAD= $TERMUX__PREFIX/bin/sh -c 'echo $TERMUX_EXEC__PROC_SELF_EXE'; /system/bin/linker64 $TERMUX__PREFIX/bin/dash -c "echo \$TERMUX_EXEC__PROC_SELF_EXE"

The termux-exec-package provides shared libraries designed to be preloaded via the $LD_PRELOAD environment variable. This mechanism ensures the proper functioning of the Termux execution environment by intercepting the exec() family of functions.

There are two primary library variants provided:

1. libtermux-exec-direct-ld-preload.so: Used for the direct execution type. It is the default variant and is designed to support system_linker_exec requirements during package updates.
2. libtermux-exec-linker-ld-preload.so: Used for the system_linker_exec execution type. It intercepts additional functions to resolve issues specific to system_linker_exec without impacting the performance of users on the direct execution type.

Automatic Setup: During package installation, a postinst script runs termux-exec-ld-preload-lib setup. This command checks if system_linker_exec is enabled (via termux-exec-system-linker-exec is-enabled) and copies the appropriate variant to $TERMUX__PREFIX/usr/lib/libtermux-exec-ld-preload.so. This path is then exported in the $LD_PRELOAD variable by the Termux login script.

Standard Linux software often assumes a root filesystem starting at / with binaries located in /bin or /usr/bin. On Android, these paths either do not exist or point to Android system binaries in /system/bin, rather than the Termux binaries located in $TERMUX__PREFIX/bin.

termux-exec solves this by intercepting the exec() family of functions. When an execution is attempted using a path starting with /bin/ or /usr/bin/, or when a script's shebang points to such a path, termux-exec replaces the prefix with the Termux prefix path ($TERMUX__PREFIX/bin/).

To enable this behavior, termux-exec must be set in the $LD_PRELOAD environment variable.

Prefix Resolution Logic:

1. It attempts to use the $TERMUX__PREFIX environment variable.
2. If $TERMUX__PREFIX is not exported or is not a valid absolute path, it falls back to the default TERMUX__PREFIX value that was set during the termux-exec build time.

export LD_PRELOAD=/path/to/libtermux-exec.so

The termux-exec package overrides the entire exec() family of functions (declared in unistd.h) to address specific execution restrictions in Termux.

Important Limitations:

• Direct System Calls: It does not override direct calls to the execve() system call made via syscall(2). Programs using direct system calls must be patched to use exec() wrappers or run under proot.
• Static Binaries: Statically linked binaries (e.g., those produced by zig against musl) will not work with this interception mechanism.
• Implementation: The interception is implemented via the $LD_PRELOAD library using ExecIntercept.c and ExecVariantsIntercept.c.

/* Note: This is a conceptual description of the interception mechanism. */
// termux-exec overrides the entire exec() family of functions,
// but will not override direct calls to the execve() system call via syscall(2).

On Android >= 10, SELinux policies prevent untrusted_app* domains from executing files located in app data directories (e.g., /data/data/<package_name>) due to W^X (Write XOR Execute) restrictions.

To bypass this, you can use the system dynamic linker to execute the file. Because the kernel/SELinux sees the system_linker_exec context of the linker rather than the app_data_file context of your binary, execution is permitted.

Executing an ELF Binary

To execute a 64-bit ELF binary located in your app data directory:

/system/bin/linker64 /data/data/com.foo/executable [args]

Executing a Script

To execute a script with a shebang (e.g., #!/path/to/interpreter):

/system/bin/linker64 /path/to/interpreter /data/data/com.foo/script.sh [args]

Note: This method requires Android 10 or higher.

# Example: Executing an ELF binary via the system linker
/system/bin/linker64 /data/data/com.foo/executable [args]

# Example: Executing a script via the system linker
/system/bin/linker64 /path/to/interpreter /data/data/com.foo/script.sh [args]