KernelSU

https://kernelsu.org/guide/
Admin
KernelSU is a kernel-based root solution for Android GKI devices that operates in kernel mode to...
Tokens:33,162
Snippets:250
Trust Score:8.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Add KernelSU to kernel source tree with setup script

Source: https://kernelsu.org/guide/how-to-integrate-for-non-gki.html

Downloads and runs the KernelSU setup script for version v0.9.5, the last version supporting non-GKI kernels. Use this command in the kernel source tree before building.

```sh
curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.9.5
```

--------------------------------

### Example metamount.sh script

Source: https://kernelsu.org/guide/metamodule.html

Example script for the metamount.sh hook, which controls how modules are mounted during boot. It sets MODDIR to the metamodule's directory.

```sh
#!/system/bin/sh
MODDIR="${0%/*}"

```

--------------------------------

### Install AnyKernel3 via adb sideload

Source: https://kernelsu.org/guide/installation.html

Command to install the AnyKernel3 ZIP via ADB sideload in a custom recovery like TWRP. Alternative to placing the ZIP on /sdcard and installing via the TWRP GUI.

```bash
adb sideload AnyKernel-*.zip
```

--------------------------------

### meta-overlayfs metamount.sh variables

Source: https://kernelsu.org/guide/metamodule.html

Starts the meta-overlayfs metamount.sh implementation by setting variables for the module directory, image file, and mount point.

```sh
#!/system/bin/sh
MODDIR="${0%/*}"
IMG_FILE="$MODDIR/modules.img"
MNT_DIR="$MODDIR/mnt"
```

--------------------------------

### Register custom Android service with initrc

Source: https://kernelsu.org/guide/module.html

Example .rc file that registers a custom Android service. If placed at /data/adb/modules/mymodule/initrc/myservice.rc, it registers a service named myservice at boot and starts it when sys.boot_completed=1 is reached.

```rc
service myservice /data/adb/modules/mymodule/bin/myservice
    user root
    group root
    disabled
    seclabel u:r:ksu:s0

on property:sys.boot_completed=1
    start myservice
```

--------------------------------

### Correct mount command with source 'KSU'

Source: https://kernelsu.org/guide/metamodule.html

Example of a mount operation that sets the source/device name to 'KSU', which is required for KernelSU to identify and manage its mounts.

```sh
mount -t overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work KSU /target

```

--------------------------------

### Build kernel with Bazel

Source: https://kernelsu.org/guide/how-to-build.html

Builds the kernel using Bazel, starting from Android 13.

```sh
tools/bazel build --config=fast //common:kernel_aarch64_dist
```

--------------------------------

### Mount ext4 image and execute meta-overlayfs

Source: https://kernelsu.org/guide/metamodule.html

Mounts an ext4 image if not already mounted, sets environment variables for dual-directory support, and executes the meta-overlayfs binary. The actual mounting logic is in a Rust binary.

```bash
if ! mountpoint -q "$MNT_DIR"; then
    mkdir -p "$MNT_DIR"
    mount -t ext4 -o loop,rw,noatime "$IMG_FILE" "$MNT_DIR"
fi

export MODULE_METADATA_DIR="/data/adb/modules"
export MODULE_CONTENT_DIR="$MNT_DIR"

"$MODDIR/meta-overlayfs"
```

--------------------------------

### Simple bind mount implementation

Source: https://kernelsu.org/guide/metamodule.html

Iterates over modules in /data/adb/modules, skipping those with disable or skip_mount markers, and bind-mounts the system directory to /system with the required dev=KSU option.

```sh
for module in /data/adb/modules/*; do
    if [ -f "$module/disable" ] || [ -f "$module/skip_mount" ]; then
        continue
    fi

    if [ -d "$module/system" ]; then
        # Mount with source=KSU (REQUIRED!)
        mount -o bind,dev=KSU "$module/system" /system
    fi
done
```

--------------------------------

### Metamodule symlink

Source: https://kernelsu.org/guide/metamodule.html

Symlink created by KernelSU when a metamodule is installed, providing a stable path to the active metamodule regardless of its ID.

```sh
/data/adb/metamodule -> /data/adb/modules/<metamodule_id>
```

--------------------------------

### Metamodule file structure

Source: https://kernelsu.org/guide/metamodule.html

Shows the recommended file layout for a metamodule, including the required module.prop and optional hook scripts and standard module files.

```txt
meta-example/
├── module.prop              (must include metamodule=1)
│
│      *** Metamodule-specific hooks ***
├── metamount.sh             (optional: custom mount handler)
├── metainstall.sh           (optional: installation hook for regular modules)
├── metauninstall.sh         (optional: cleanup hook for regular modules)
│
│      *** Standard module files (all optional) ***
├── customize.sh             (installation customization)
├── post-fs-data.sh          (post-fs-data stage script)
├── service.sh               (late_start service script)
├── boot-completed.sh        (boot completed script)
├── uninstall.sh             (metamodule's own uninstallation script)
└── [any additional files]

```

--------------------------------

### Boot execution order

Source: https://kernelsu.org/guide/metamodule.html

Shows the boot execution order for metamodule scripts across post-fs-data, service, and boot-completed stages. metamount.sh runs after all post-fs-data scripts, and metamodule lifecycle scripts run before regular module scripts.

```txt
post-fs-data stage:
  1. Common post-fs-data.d scripts execute
  2. Prune modules, restorecon, load sepolicy.rule
  3. Metamodule's post-fs-data.sh executes (if exists)
  4. Regular modules' post-fs-data.sh execute
  5. Load system.prop
  6. Metamodule's metamount.sh executes
     └─> Mounts all modules systemlessly
  7. post-mount.d stage runs
     - Common post-mount.d scripts
     - Metamodule's post-mount.sh (if exists)
     - Regular modules' post-mount.sh

service stage:
  1. Common service.d scripts execute
  2. Metamodule's service.sh executes (if exists)
  3. Regular modules' service.sh execute

boot-completed stage:
  1. Common boot-completed.d scripts execute
  2. Metamodule's boot-completed.sh executes (if exists)
  3. Regular modules' boot-completed.sh execute
```

--------------------------------

### module.prop with metamodule property

Source: https://kernelsu.org/guide/metamodule.html

Identifies a module as a metamodule by including the 'metamodule=1' property. Without this property, the module is treated as a regular module. The ID should start with 'meta-' to avoid conflicts.

```txt
id=meta-example
name=My Custom Metamodule
version=1.0
versionCode=1
author=Your Name
description=Custom module mounting implementation
metamodule=1

```

--------------------------------

### ksud boot-patch command-line help

Source: https://kernelsu.org/guide/installation.html

Shows the help output for the ksud boot-patch command, which patches boot or init_boot images to apply KernelSU. Use this to see available options for patching the official firmware.

```shell
oriole:/ # ksud boot-patch -h
Patch boot or init_boot images to apply KernelSU

Usage: ksud boot-patch [OPTIONS]
```

--------------------------------

### Android boot process with KernelSU script execution points

Source: https://kernelsu.org/guide/module.html

Shows the Android boot process with KernelSU operations marked by asterisks, including GKI and LKM modes, initrc injection, and the execution points for module scripts (post-fs-data, post-mount, service, boot-completed). Useful for understanding when each module script runs.

```txt
0. Bootloader (nothing on screen)
load patched boot.img
load kernel:
    - GKI mode: GKI kernel with KernelSU integrated
    - LKM mode: stock kernel
...

1. kernel exec init (OEM logo on screen):
    - GKI mode: stock init
    - LKM mode: exec ksuinit, insmod kernelsu.ko, exec stock init
mount /dev, /dev/pts, /proc, /sys, etc.
property-init -> read default props
read init.rc
  *initrc injection: Kernel hook appends KernelSU core RC and module modules.rc to init.rc
...
early-init -> init -> late_init
early-fs
   start vold
fs
  mount /vendor, /system, /persist, etc.
post-fs-data
  *safe mode check
  *execute general scripts in post-fs-data.d/
  *load sepolicy.rule
  *execute metamodule's post-fs-data.sh (if exists)
  *execute module scripts post-fs-data.sh
    **(Zygisk)./bin/zygisk-ptrace64 monitor
  *(pre)load system.prop (same as resetprop -n)
  *execute metamodule's metamount.sh (mounts all modules)
  *execute general scripts in post-mount.d/
  *execute metamodule's post-mount.sh (if exists)
  *execute module scripts post-mount.sh
zygote-start
load_all_props_action
  *execute resetprop (actual set props for resetprop with -n option)
... -> boot
  class_start core
    start-service logd, console, vold, etc.
  class_start main
    start-service adb, netd (iptables), zygote, etc.

2. kernel2user init (ROM animation on screen, start by service bootanim)
*execute general scripts in service.d/
*execute metamodule's service.sh (if exists)
*execute module scripts service.sh
*set props for resetprop without -p option
  **(Zygisk) hook zygote (start zygiskd)
  **(Zygisk) mount zygisksu/module.prop
start system apps (autostart)
...
boot complete (broadcast ACTION_BOOT_COMPLETED event)
*execute general scripts in boot-completed.d/
*execute metamodule's boot-completed.sh (if exists)
*execute module scripts boot-completed.sh

3. User operable (lock screen)
input password to decrypt /data/data
*actual set props for resetprop with -p option
start user apps (autostart)
```

--------------------------------

### Execute shell command with kernelsu JavaScript API

Source: https://kernelsu.org/guide/module-webui.html

Imports the exec function from the kernelsu npm package and runs a shell command to get a system property. The result includes errno and stdout.

```javascript
import { exec } from 'kernelsu';

const { errno, stdout } = exec("getprop ro.product.model");

```

--------------------------------

### Module webroot directory structure

Source: https://kernelsu.org/guide/module-webui.html

Shows the minimal module structure with a webroot directory containing index.html. KernelSU automatically sets permissions and SELinux context for this directory; do not set them manually.

```txt
❯ tree .
.
|-- module.prop
`-- webroot
    `-- index.html

```

--------------------------------

### id command output in ADB shell

Source: https://kernelsu.org/guide/app-profile.html

Example output of the id command executed in ADB shell, showing UID, GID, groups, and SELinux context. Used to illustrate how Android assigns UIDs and groups to apps.

```sh
oriole:/ $ 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
```

--------------------------------

### Manage modules via ADB with ksud

Source: https://kernelsu.org/guide/rescue-from-bootloop.html

Use when the device can get a root shell via ADB. After mounting metadata and data partitions, /data/adb/ksud can also be run under Recovery mode. The commands list modules, disable or uninstall the problematic one, then reboot.

```shell
adb shell
su
ksud module list          # List all modules
ksud module disable <id>  # Disable problematic module
ksud module uninstall <id> # Or uninstall directly
reboot
```

--------------------------------

### Enable kprobe kernel configs

Source: https://kernelsu.org/guide/how-to-integrate-for-non-gki.html

Add these configs to the kernel config to enable kprobe, which is required for KernelSU integration. If KPROBES is still not enabled, try enabling CONFIG_MODULES or use make menuconfig to search for dependencies.

```txt
CONFIG_KPROBES=y
CONFIG_HAVE_KPROBES=y
CONFIG_KPROBE_EVENTS=y
```

--------------------------------

### Flash boot.img with fastboot

Source: https://kernelsu.org/guide/installation.html

Flashes the KernelSU-provided boot.img to the boot partition in fastboot mode.

```sh
fastboot flash boot boot.img
```

--------------------------------

### Set manage.su_compat to true

Source: https://kernelsu.org/guide/module-config.html

Declares that the module manages SU compatibility and enables it. The presence of the `manage.su_compat` key indicates management, and the value `true` enables the feature.

```bash
ksud module config set manage.su_compat true
```

--------------------------------

### Manage module configuration with ksud module config

Source: https://kernelsu.org/guide/module-config.html

Use these commands in module scripts (post-fs-data.sh, service.sh, boot-completed.sh) to manage module configuration. The KSU_MODULE environment variable is set to the module ID. Temporary values take priority over persistent values for the same key.

```bash
# Get a configuration value
value=$(ksud module config get my_setting)

# Set a persistent configuration value
ksud module config set my_setting "some value"

# Set a temporary configuration value (cleared on reboot)
ksud module config set --temp runtime_state "active"

# Set value from stdin (useful for multiline or complex data)
ksud module config set my_key <<EOF
multiline
text value
EOF

# Or pipe from command
echo "value" | ksud module config set my_key

# Explicit stdin flag
cat file.json | ksud module config set json_data --stdin
```

--------------------------------

### Custom SELinux domain for root process

Source: https://kernelsu.org/guide/app-profile.html

Defines a custom SELinux domain for a root process after executing su. The rule 'allow app1 * * *' is for demonstration only and should not be used in practice as it is similar to Permissive mode.

```sh
type app1
enforce app1
typeattribute app1 mlstrustedsubject
allow app1 * * *
```

--------------------------------

### Build aarch64 kernel image with build.sh

Source: https://kernelsu.org/guide/how-to-build.html

Builds an aarch64 kernel image. The LTO=thin flag is required to avoid build failures on systems with less than 24 GB of memory.

```sh
LTO=thin BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh
```

--------------------------------

### module.prop configuration format

Source: https://kernelsu.org/guide/module.html

Defines the required metadata for a KernelSU module. The id must match the regex ^[a-zA-Z][a-zA-Z0-9._-]+$ and versionCode must be an integer. Use UNIX (LF) line breaks. actionIcon and webuiIcon are optional paths relative to the module root.

```txt
id=<string>
name=<string>
version=<string>
versionCode=<int>
author=<string>
description=<string>
updateJson=<url> (optional)
actionIcon=<path> (optional)
webuiIcon=<path> (optional)
```

--------------------------------

### ksud module config commands for listing, deleting, and clearing configurations

Source: https://kernelsu.org/guide/module-config.html

Commands to list all configuration entries, delete specific persistent or temporary entries, and clear all persistent or temporary configurations. Use `--temp` to target temporary configurations.

```bash
# List all configuration entries (merged persist + temp)
ksud module config list

# Delete a configuration entry
ksud module config delete my_setting

# Delete a temporary configuration entry
ksud module config delete --temp runtime_state

# Clear all persistent configurations
ksud module config clear

# Clear all temporary configurations
ksud module config clear --temp
```

--------------------------------

### Enable CONFIG_KSU in defconfig

Source: https://kernelsu.org/guide/how-to-integrate-for-non-gki.html

Enables KernelSU in the kernel defconfig. The defconfig may be located at arch/arm64/configs or arch/arm64/configs/vendor/your_defconfig. Set CONFIG_KSU to y to enable or n to disable.

```txt
# KernelSU
CONFIG_KSU=y
```

--------------------------------

### Set source string with fsconfig_set_string

Source: https://kernelsu.org/guide/metamodule.html

For modern mount APIs, set the source string to 'KSU' using fsconfig_set_string. This is essential for KernelSU to identify and manage its mounts.

```rust
fsconfig_set_string(fs, "source", "KSU")?;

```
Tokens:
Raw