KernelSU

https://kernelsu.org
Admin
KernelSU is a kernel-based root solution for Android GKI devices that grants root permission in...
Tokens:16,245
Snippets:213
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Perform Mount Operations

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

Examples for setting the source to 'KSU' when performing mount operations to ensure KernelSU compatibility.

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

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

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

### Install via ADB Sideload

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

Install the AnyKernel3 ZIP package directly using ADB sideload in recovery mode.

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

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

### Add KernelSU Support (Main Branch)

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

Integrate the development version (main branch) of KernelSU into your kernel source by downloading and running the setup script with the 'main' argument.

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

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

### Register a Custom Android Service

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

Example of an .rc file content used to define a service and trigger it upon boot completion.

```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
```

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

### Add KernelSU Support (Latest Tag)

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

Integrate the latest stable version of KernelSU into your kernel source by downloading and running the setup script.

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

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

### KernelSU Module Installer Functions

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

Helper functions available within the customize.sh script for console output and file permission management.

```text
ui_print <msg>
    print <msg> to console
    Avoid using 'echo' as it will not display in custom recovery's console

abort <msg>
    print error message <msg> to console and terminate the installation
    Avoid using 'exit' as it will skip the termination cleanup steps

set_perm <target> <owner> <group> <permission> [context]
    if [context] is not set, the default is "u:object_r:system_file:s0"
    this function is a shorthand for the following commands:
       chown owner.group target
       chmod permission target
       chcon context target

set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission> [context]
    if [context] is not set, the default is "u:object_r:system_file:s0"
    for all files in <directory>, it will call:
       set_perm file owner group filepermission context
    for all directories in <directory> (including itself), it will call:
       set_perm dir owner group dirpermission context
```

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

### Define Custom SELinux Domain Rules

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

Example configuration for defining a custom SELinux domain and associated access rules. The allow rule is for demonstration and should be restricted in production environments.

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

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

### Add KernelSU Support (Specific Tag)

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

Integrate a specific version (e.g., v0.5.2) of KernelSU into your kernel source by downloading and running the setup script with the desired tag.

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

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

### Define files for removal in customize.sh

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

Use the REMOVE variable to specify paths that should be whiteouted during module installation.

```sh
REMOVE="
/system/app/YouTube
/system/app/Bloatware
"
```

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

### Execute Shell Commands via JavaScript API

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

Example of using the kernelsu npm package to execute shell commands from a module's web page.

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

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

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

### Initialize metamount.sh Script

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

Basic boilerplate for a metamount.sh script.

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

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

### Sync Kernel Source Code

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

Initialize the kernel manifest, set the manifest file, and sync the repository. Ensure you use the correct manifest.xml for reproducible builds.

```bash
repo init -u https://android.googlesource.com/kernel/manifest
mv <kernel_manifest.xml> .repo/manifests
repo init -m manifest.xml
repo sync
```

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

### Android Boot Process with KernelSU

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

Overview of the Android boot sequence highlighting KernelSU integration points and script execution stages.

```text
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)
```

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

### Define boot execution order

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

Outlines the sequence of stages and scripts executed during the boot process.

```text
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
```

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

### Implement simple bind mount

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

Iterates through modules to perform bind mounts, requiring the dev=KSU flag.

```shell
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
```

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

### Prepare magiskboot on Android

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

Set execution permissions for the magiskboot binary.

```bash
cd /data/local/tmp/
chmod +x magiskboot
```

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

### Check ksud boot-patch help

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

Displays the help menu for the boot-patch command in the ksud tool.

```sh
ksud boot-patch -h
Patch boot or init_boot images to apply KernelSU

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

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

### Implement metamount.sh handler

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

Initializes paths for the mount handler in the meta-overlayfs implementation.

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

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

### Manage Module Configuration - KernelSU

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

Use the `ksud module config` commands to manage your module's configuration. Temporary values take priority over persistent values for the same key. Configurations are stored in `/data/adb/ksu/module_configs/<module_id>/`.

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

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

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

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

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

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

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

```bash
# Delete a configuration entry
ksud module config delete my_setting
```

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

```bash
# Clear all persistent configurations
ksud module config clear
```

```bash
# 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

When manually integrating KernelSU, ensure `CONFIG_KSU` is set to `y` in your kernel's defconfig file to enable the feature. The defconfig file might be located in `arch/arm64/configs` or `arch/arm64/configs/vendor/`.

```txt
CONFIG_KSU=y
```

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

### Define Global initrc Directory Structure

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

Place .rc files in the global /data/adb/initrc.d/ directory. Note that these files must have executable permissions to be processed.

```text
/data/adb/initrc.d/
├── myservice.rc
└── another.rc
```

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

### Mounting an ext4 image for metamodules

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

Shell script snippet to mount an ext4 image and set environment variables for module directory support.

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

# Set environment variables for dual-directory support
export MODULE_METADATA_DIR="/data/adb/modules"
export MODULE_CONTENT_DIR="$MNT_DIR"

# Execute the mount binary
# (The actual mounting logic is in a Rust binary)
"$MODDIR/meta-overlayfs"
```

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

### Patch boot.img on PC

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

Unpack, replace the kernel, and repack the boot image using the PC-compatible magiskboot binary.

```bash
chmod +x magiskboot
./magiskboot unpack boot.img
mv -f Image kernel
./magiskboot repack boot.img
```

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

### Enable Kprobe Configuration

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

These kernel configurations are required to enable kprobe functionality. If kprobe is not enabled, try enabling CONFIG_MODULES or use 'make menuconfig' to find other dependencies.

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

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

### Build aarch64 Kernel Image

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

Build an aarch64 kernel image using the provided script. The LTO=thin flag is recommended, especially if your system has limited memory (less than 24 GB).

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

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

### Create metamodule symlink

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

Establishes a stable path for accessing the active metamodule.

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

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

### Integrate KernelSU into fs/devpts/inode.c

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

Add KernelSU integration to the `devpts_get_priv` function in `fs/devpts/inode.c`. This is necessary if you encounter issues executing `pm` in the terminal.

```diff
diff --git a/fs/devpts/inode.c b/fs/devpts/inode.c
index 32f6f1c68..d69d8eca2 100644
--- a/fs/devpts/inode.c
+++ b/fs/devpts/inode.c
@@ -602,6 +602,8 @@ struct dentry *devpts_pty_new(struct pts_fs_info *fsi, int index, void *priv)
 	return dentry;
 }

+#ifdef CONFIG_KSU
+extern int ksu_handle_devpts(struct inode*);
+#endif
+
 /**
  * devpts_get_priv -- get private data for a slave
  * @pts_inode: inode of the slave
@@ -610,6 +612,7 @@ struct dentry *devpts_pty_new(struct pts_fs_info *fsi, int index, void *priv)
  */
 void *devpts_get_priv(struct dentry *dentry)
 {
+	#ifdef CONFIG_KSU
+	ksu_handle_devpts(dentry->d_inode);
+	#endif
 	if (dentry->d_sb->s_magic != DEVPTS_SUPER_MAGIC)
 		return NULL;
 	return dentry->d_fsdata;

```

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

### module.prop Configuration Format

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

The required metadata file format for KernelSU modules. Ensure the file uses UNIX (LF) line endings.

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

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

### Flash boot image via fastboot

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

Flash the patched boot image to the device's boot partition using fastboot.

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

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

### Add KernelSU Hooks to open.c

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

Integrates KernelSU hooks into the faccessat system call handler in fs/open.c. This allows KernelSU to manage file access permissions.

```c
#ifdef CONFIG_KSU
extern int ksu_handle_faccessat(int *dfd, const char __user **filename_user, int *mode,
			 int *flags);
#endif
long do_faccessat(int dfd, const char __user *filename, int mode)
{
	const struct cred *old_cred;
	struct cred *override_cred;
	struct path path;
	struct inode *inode;
	struct vfsmount *mnt;
	int res;
	unsigned int lookup_flags = LOOKUP_FOLLOW;
   #ifdef CONFIG_KSU
	ksu_handle_faccessat(&dfd, &filename, &mode, NULL);
   #endif

	if (mode & ~S_IRWXO) 	/* where's F_OK, X_OK, W_OK, R_OK? */
		return -EINVAL;

```

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

### Metamodule Directory Structure

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

Standard file layout for a metamodule, including optional hooks and standard module files.

```text
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]
```

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

### Define directories for replacement in customize.sh

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

Use the REPLACE variable to specify directories that should be replaced with empty ones using OverlayFS opaque attributes.

```sh
REPLACE="
/system/app/YouTube
/system/app/Bloatware
"
```

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

### Build Kernel with Bazel (Android 13+)

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

Build the kernel using Bazel for Android 13 and later versions. This command builds the aarch64 distribution.

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

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

### Manage Modules via ADB

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

Use the ksud command-line tool within an ADB root shell to list, disable, or uninstall modules causing boot issues.

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

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

### Define Module initrc Directory Structure

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

Place .rc files within the initrc/ subdirectory of a module directory to have them automatically included.

```text
/data/adb/modules/<MODID>/
├── initrc/
│   ├── myservice.rc
│   └── another.rc
└── ...
```

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

### Manual Cleanup via Recovery

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

Commands to manually remove KernelSU module loading mechanisms when the system is inaccessible.

```bash
mount /data
```

```bash
rm -f /data/adb/ksud
```

```bash
mount /metadata
rm -f /metadata/ksu/modules.rc
rm -f /metadata/watchdog/ksu/modules.rc
```

```bash
reboot
```

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

### Add KernelSU faccessat Handler

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

This code snippet adds the necessary KSU handler for the `faccessat` syscall in older kernels. Ensure `CONFIG_KSU` is enabled.

```c
#ifdef CONFIG_KSU
extern int ksu_handle_faccessat(int *dfd, const char __user **filename_user, int *mode,
			        int *flags);
#endif
```

```c
   #ifdef CONFIG_KSU
	ksu_handle_faccessat(&dfd, &filename, &mode, NULL);
   #endif
```

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

### Enable KernelSU Safe Mode in input.c

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

Modify the `input_handle_event` function to include KernelSU's safe mode hook. This is recommended for preventing bootloops.

```diff
diff --git a/drivers/input/input.c b/drivers/input/input.c
index 45306f9ef247..815091ebfca4 100755
--- a/drivers/input/input.c
+++ b/drivers/input/input.c
@@ -367,10 +367,13 @@ static int input_get_disposition(struct input_dev *dev, 
 	return disposition;
 }

+#ifdef CONFIG_KSU
+extern bool ksu_input_hook __read_mostly;
+extern int ksu_handle_input_handle_event(unsigned int *type, unsigned int *code, int *value);
+#endif
+
 static void input_handle_event(struct input_dev *dev,
 			       unsigned int type, unsigned int code, int value)
 {
 	int disposition = input_get_disposition(dev, type, code, &value);
+	#ifdef CONFIG_KSU
+	if (unlikely(ksu_input_hook))
+		ksu_handle_input_handle_event(&type, &code, &value);
+	#endif
 
 	if (disposition != INPUT_IGNORE_EVENT && type != EV_SYN)
 		add_input_randomness(type, code, value);

```

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

### Add KernelSU to Kernel Source Tree (v0.9.5)

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

Use this command to add KernelSU to your kernel source tree. Ensure you specify version v0.9.5 for non-GKI compatibility, as later versions do not support non-GKI kernels.

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

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

### Patch boot.img on Android

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

Unpack the boot image, replace the kernel with the KernelSU Image, and repack the image.

```bash
./magiskboot unpack boot.img
mv -f Image kernel
./magiskboot repack boot.img
```

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

### Module Directory Structure

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

The required file structure for a KernelSU module containing a web interface.

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

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

### Define Metamodule in module.prop

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

Required property configuration to identify a module as a metamodule.

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

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

### Patch boot image with ksud

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

Use the ksud tool to patch a boot image with a specific KMI version.

```sh
ksud boot-patch -b <boot.img> --kmi android13-5.10
```

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

### Push magiskboot to Android device

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

Transfer the magiskboot binary to the device's temporary directory using ADB.

```bash
adb push Magisk-*/lib/arm64-v8a/libmagiskboot.so /data/local/tmp/magiskboot
```

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

### Add KernelSU Hooks to read_write.c

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

Integrates KernelSU hooks into the vfs_read system call handler in fs/read_write.c. This allows KernelSU to intercept and manage read operations.

```c
#ifdef CONFIG_KSU
extern bool ksu_vfs_read_hook __read_mostly;
extern int ksu_handle_vfs_read(struct file **file_ptr, char __user **buf_ptr,
			size_t *count_ptr, loff_t **pos);
#endif
ssize_t vfs_read(struct file *file, char __user *buf, size_t count, loff_t *pos)
{
	ssize_t ret;
   #ifdef CONFIG_KSU 
	if (unlikely(ksu_vfs_read_hook))
		ksu_handle_vfs_read(&file, &buf, &count, &pos);
   #endif

	if (!(file->f_mode & FMODE_READ))
		return -EBADF;
	if (!(file->f_mode & FMODE_CAN_READ))

```

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

### Cleanup resources with metauninstall.sh

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

Removes module-specific files from the metamodule mount directory during uninstallation.

```shell
#!/system/bin/sh
# Called when uninstalling regular modules
MODULE_ID="$1"
IMG_MNT="/data/adb/metamodule/mnt"

# Remove module files from image
if [ -d "$IMG_MNT/$MODULE_ID" ]; then
    rm -rf "$IMG_MNT/$MODULE_ID"
fi
```

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

### Add KernelSU Hooks to exec.c

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

Integrates KernelSU hooks into the execveat system call handler in fs/exec.c. This allows KernelSU to intercept execution requests.

```c
#ifdef CONFIG_KSU
extern bool ksu_execveat_hook __read_mostly;
extern int ksu_handle_execveat(int *fd, struct filename **filename_ptr, void *argv,
			void *envp, int *flags);
extern int ksu_handle_execveat_sucompat(int *fd, struct filename **filename_ptr,
			 void *argv, void *envp, int *flags);
#endif
static int do_execveat_common(int fd, struct filename *filename,
			  struct user_arg_ptr argv,
			  struct user_arg_ptr envp,
			  int flags)
{
   #ifdef CONFIG_KSU
	if (unlikely(ksu_execveat_hook))
		ksu_handle_execveat(&fd, &filename, &argv, &envp, &flags);
	else
		ksu_handle_execveat_sucompat(&fd, &filename, &argv, &envp, &flags);
   #endif
	return __do_execve_file(fd, filename, argv, envp, flags, NULL);
}
```

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

### Reboot device via fastboot

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

Reboot the device after flashing the boot image.

```sh
fastboot reboot
```

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

### KernelSU Module Directory Structure

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

The standard layout for a KernelSU module, including metadata, system files, status flags, and lifecycle scripts.

```text
/data/adb/modules
├── .
├── .
|
├── $MODID                  <--- The folder is named with the ID of the module
│   │
│   │      *** Module Identity ***
│   │
│   ├── module.prop         <--- This file stores the metadata of the module
│   │
│   │      *** Main Contents ***
│   │
│   ├── system              <--- This folder will be mounted if skip_mount does not exist
│   │   ├── ...
│   │   ├── ...
│   │   └── ...
│   │
│   │      *** Status Flags ***
│   │
│   ├── skip_mount          <--- If exists, KernelSU will NOT mount your system folder
│   ├── disable             <--- If exists, the module will be disabled
│   ├── remove              <--- If exists, the module will be removed next reboot
│   │
│   │      *** Optional Files ***
│   │
│   ├── post-fs-data.sh     <--- This script will be executed in post-fs-data
│   ├── post-mount.sh       <--- This script will be executed in post-mount
│   ├── service.sh          <--- This script will be executed in late_start service
│   ├── boot-completed.sh   <--- This script will be executed on boot completed
|   ├── uninstall.sh        <--- This script will be executed when KernelSU removes your module
|   ├── action.sh           <--- This script will be executed when user click the Action button in KernelSU app
│   ├── system.prop         <--- Properties in this file will be loaded as system properties by resetprop
│   ├── sepolicy.rule       <--- Additional custom sepolicy rules
│   ├── initrc/             <--- .rc files in this directory will be injected into init.rc on boot
│   │   ├── myservice.rc
│   │   └── ...
│   │
│   │      *** Auto Generated, DO NOT MANUALLY CREATE OR MODIFY ***
│   │
│   ├── vendor              <--- A symlink to $MODID/system/vendor
│   ├── product             <--- A symlink to $MODID/system/product
│   ├── system_ext          <--- A symlink to $MODID/system/system_ext
│   │
│   │      *** Any additional files / folders are allowed ***
│   │
│   ├── ...
│   └── ...
|
├── another_module
│   ├── .
│   └── .
├── .
├── .
```

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

### Backport path_umount for pre-GKI kernels

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

Manually backport the `path_umount` function from kernel version 5.9 to enable the 'Umount modules' feature on pre-GKI kernels. This involves adding `can_umount` and `path_umount` definitions.

```diff
--- a/fs/namespace.c
+++ b/fs/namespace.c
@@ -1739,6 +1739,39 @@ static inline bool may_mandlock(void) 
 }
 #endif
 
+static int can_umount(const struct path *path, int flags)
+{
+	struct mount *mnt = real_mount(path->mnt);
+
+	if (flags & ~(MNT_FORCE | MNT_DETACH | MNT_EXPIRE | UMOUNT_NOFOLLOW))
+		return -EINVAL;
+	if (!may_mount())
+		return -EPERM;
+	if (path->dentry != path->mnt->mnt_root)
+		return -EINVAL;
+	if (!check_mnt(mnt))
+		return -EINVAL;
+	if (mnt->mnt.mnt_flags & MNT_LOCKED) /* Check optimistically */
+		return -EINVAL;
+	if (flags & MNT_FORCE && !capable(CAP_SYS_ADMIN))
+		return -EPERM;
+	return 0;
+}
+
+int path_umount(struct path *path, int flags)
+{
+	struct mount *mnt = real_mount(path->mnt);
+	int ret;
+
+	ret = can_umount(path, flags);
+	if (!ret)
+		ret = do_umount(mnt, flags);
+
+	/* we mustn't call path_put() as that would clear mnt_expiry_mark */
+	dput(path->dentry);
+	mntput_no_expire(mnt);
+	return ret;
+}
 /*
  * Now umount can handle mount points as well as block devices.
  * This is important for filesystems which use unnamed block devices.

```

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

### Add KernelSU Hooks to stat.c (vfs_fstatat)

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

Integrates KernelSU hooks into the vfs_fstatat system call handler in fs/stat.c, as an alternative for kernels without vfs_statx. This allows KernelSU to intercept and manage file status retrieval.

```c
#ifdef CONFIG_KSU
extern int ksu_handle_stat(int *dfd, const char __user **filename_user, int *flags);
#endif
int vfs_fstatat(int dfd, const char __user *filename, struct kstat *stat,
		int flag)
{
	int error = -EINVAL;
	unsigned int lookup_flags = 0;
   #ifdef CONFIG_KSU 
	ksu_handle_stat(&dfd, &filename, &flag);
   #endif

	if ((flag & ~(AT_SYMLINK_NOFOLLOW | AT_NO_AUTOMOUNT |
		      AT_EMPTY_PATH)) != 0)
		goto out;

```

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

### Late-load Mode Script Execution Order

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

Sequence of operations performed when executing the ksud late-load command.

```text
ksud late-load:
  1. Load kernelsu.ko (if not already loaded)
  2. Extract binaries, handle module updates, load SELinux rules, init features
  3. Execute late-load.d/ and module late-load scripts (blocking)
  4. Load system.prop (resetprop -n)
  5. Execute metamodule mount script (OverlayFS)
  6. Execute post-mount.d/ and module post-mount.sh (blocking)
  7. Execute service.d/ and module service.sh (non-blocking)
  8. Execute boot-completed.d/ and module boot-completed.sh (non-blocking)
```

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

### Override Module Description - KernelSU

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

Dynamically override the `description` field from `module.prop` by setting the `override.description` configuration key. This is useful for displaying dynamic status information or runtime configuration details.

```bash
# Override module description
ksud module config set override.description "Custom description shown in the manager"
```

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

### Declare Managed Features - KernelSU

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

Modules can declare which KernelSU features they manage using the `manage.<feature>` configuration pattern. Supported features include `su_compat` and `kernel_umount`.

```bash
# Declare that this module manages SU compatibility and enables it
ksud module config set manage.su_compat true
```

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

### Remove Feature Management

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

Delete the `manage.su_compat` configuration key to stop the module from managing this feature.

```bash
ksud module config delete manage.su_compat
```

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

### Setting source identification for overlayfs

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

Rust code snippet to set the source identifier for overlay mounts, which is required for proper unmounting by KernelSU.

```rust
// From meta-overlayfs/src/mount.rs
fsconfig_set_string(fs, "source", "KSU")?;  // REQUIRED!
```

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

### Add KernelSU Hooks to stat.c (vfs_statx)

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

Integrates KernelSU hooks into the vfs_statx system call handler in fs/stat.c. This allows KernelSU to intercept and manage file status retrieval.

```c
#ifdef CONFIG_KSU
extern int ksu_handle_stat(int *dfd, const char __user **filename_user, int *flags);
#endif

/**
 * vfs_statx - Get basic and extra attributes by filename
 * @dfd: A file descriptor representing the base dir for a relative filename
 * @filename: The name of the file to get attributes from
 * @flags: Flags to control path lookup and attribute retrieval
 * @stat: Pointer to a kstat structure to be filled with attributes
 */
int vfs_statx(int dfd, const char __user *filename, int flags,
	      struct kstat *stat)
{
	int error = -EINVAL;
	unsigned int lookup_flags = LOOKUP_FOLLOW | LOOKUP_AUTOMOUNT);

   #ifdef CONFIG_KSU
	ksu_handle_stat(&dfd, &filename, &flags);
   #endif
	if ((flags & ~(AT_SYMLINK_NOFOLLOW | AT_NO_AUTOMOUNT |
		       AT_EMPTY_PATH | KSTAT_QUERY_FLAGS)) != 0)
		return -EINVAL;

```

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

### Enable BusyBox Standalone Mode via Environment Variable

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

Sets the ASH_STANDALONE environment variable to 1 to ensure all child processes inherit the standalone shell mode.

```bash
ASH_STANDALONE=1 /data/adb/ksu/bin/busybox sh <script>
```

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

### Remove GKI Protected Exports

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

For some Android 14 kernels, remove GKI protected exports to ensure Wi-Fi/Bluetooth functionality. This step might be necessary for compatibility.

```bash
rm common/android/abi_gki_protected_exports_*
```

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

### Manually Refresh modules.rc

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

Command to trigger the regeneration of the modules.rc file, which takes effect on the next boot.

```sh
ksud initrc refresh
```

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

### Enable BusyBox Standalone Mode via Command-line Option

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

Uses the -o standalone flag to execute a script within the BusyBox ash shell in standalone mode.

```bash
/data/adb/ksu/bin/busybox sh -o standalone <script>
```
Tokens:
Raw