Introduction: Unlocking Android’s Kernel with KernelSU

KernelSU represents a paradigm shift in Android rooting and customization, offering a kernel interface that allows modules to run directly in kernel space. Unlike traditional Magisk modules which operate in userspace, KernelSU modules can achieve deeper system modifications, making it an invaluable tool for security research, custom feature development, and performance enhancements. This hands-on lab will guide you through the process of developing your very first KernelSU module, from setting up your environment to deploying and testing a simple “Hello World” module, laying the groundwork for more advanced kernel-level modifications.

Prerequisites for Your KernelSU Development Journey

Before diving into module development, ensure you have the following:

• An Android device with an unlocked bootloader and KernelSU successfully installed. This tutorial assumes you already have KernelSU working.
• A Linux-based development environment (Ubuntu, Debian, WSL) for compiling kernel modules.
• ADB (Android Debug Bridge) and Fastboot tools installed and configured on your development machine.
• The Android NDK (Native Development Kit) for cross-compiling, specifically the toolchain.
• Approximately 50-100 GB of free disk space for kernel source code and build artifacts.
• Basic understanding of Linux shell scripting and C programming.

Understanding KernelSU’s Architecture

KernelSU injects its own code into the Android kernel, creating a privileged execution environment. Modules developed for KernelSU leverage this environment, allowing them to:

• Execute code directly in kernel space.
• Access and modify kernel data structures.
• Hook kernel functions for system-wide behavioral changes.
• Provide enhanced root capabilities to userspace applications.

This deep integration is what sets KernelSU apart, offering unparalleled control over the Android operating system.

Setting Up Your Kernel Development Environment

The first crucial step is to obtain your device’s exact kernel source code and prepare your build environment. This ensures compatibility and allows you to compile kernel modules against the correct kernel headers.

1. Obtaining Kernel Source Code

You need the kernel source code that precisely matches your device’s running kernel. Often, device manufacturers provide this in their open-source repositories (e.g., GitHub, GitLab) or on their support pages. Check your device’s kernel version via “Settings > About Phone > Kernel Version”.

# Example: Cloning a common Android kernel treegit clone https://android.googlesource.com/kernel/common.gitcd common# Find the appropriate branch/tag for your device's kernel versiongit checkout android-xx.x-release

Alternatively, you might need to extract the kernel from your device’s firmware or look for device-specific repositories on GitHub (e.g., LineageOS, custom ROMs).

2. Setting Up the Cross-Compiler

Android kernels are typically compiled for ARM or ARM64 architectures. You’ll need an appropriate cross-compilation toolchain.

# Download the Android NDKwget https://dl.google.com/android/repository/android-ndk-r25c-linux.zipunzip android-ndk-r25c-linux.zipexport NDK_ROOT=$(pwd)/android-ndk-r25c# Set up environment variables for ARM64 (common for modern Android devices)export ARCH=arm64export CROSS_COMPILE=${NDK_ROOT}/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-# Add more specific path for GCC if needed, though LLVM/Clang is preferred# export PATH=$NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH

Ensure CROSS_COMPILE points to the correct toolchain for your device’s architecture.

3. Building a Stock Kernel (Verification)

It’s good practice to verify your setup by building the stock kernel. Navigate to your kernel source directory:

# Clean previous buildsmake ARCH=arm64 cleanmake ARCH=arm64 mrproper# Configure the kernel for your device (e.g., using defconfig)# You might need to find the specific defconfig for your device, often in arch/arm64/configs/make ARCH=arm64 your_device_defconfig_here# Build the kernel (using -jN for parallel compilation, where N is your CPU cores)make ARCH=arm64 -j$(nproc)

If the compilation completes without errors, your environment is ready.

Developing Your First KernelSU Module: “Hello World”

Let’s create a simple KernelSU module that logs a message to the kernel ring buffer (dmesg) when activated.

1. Module Structure

A basic KernelSU module is a ZIP file containing:

• module.prop: Metadata about the module.
• service.sh: A shell script that runs on boot (or module activation) as root in the kernel context.
• (Optional) Other scripts (post-fs-data.sh, boot-completed.sh, customize.sh, etc.)
• (Optional) Actual kernel modules (.ko files) or binaries.

2. Creating module.prop

Create a directory for your module (e.g., ksu_hello_world) and inside it, create module.prop:

id=ksuhelloworldname=KernelSU Hello Worldversion=v1.0versionCode=1author=YourNamedescription=A simple KernelSU module that logs "Hello World" to dmesg.minKsuVersion=11000 # Minimum KernelSU version (adjust as needed)

Ensure minKsuVersion is compatible with your KernelSU installation.

3. Creating service.sh

This script will run when the module is enabled. Create service.sh in the same directory:

#!/system/bin/shlog_file=/data/local/tmp/ksu_hello_world.log# Log to dmesgecho "KernelSU Hello World module activated!" > /dev/kmsgecho "Current date and time: $(date)" > /dev/kmsg# Example: Write to a file in userspace (requires appropriate permissions)echo "Hello from KernelSU module at $(date)" >> "$log_file"# Sleep for a bit to ensure logs are processed, then exitsleep 5exit 0

Remember to make service.sh executable:

chmod +x service.sh

Note: Directly writing to /dev/kmsg is a kernel-level operation. Writing to /data/local/tmp is a userspace operation but demonstrates the capabilities of service.sh running with root privileges.

4. Packaging the Module

Now, create a ZIP archive of your module directory. Make sure module.prop and service.sh are at the root of the ZIP file.

cd ksu_hello_worldzip -r ../ksu_hello_world.zip ./*cd ..

You should now have ksu_hello_world.zip.

Flashing and Testing Your Module

With your module packaged, it’s time to deploy it to your device.

1. Transferring the Module

Push the ZIP file to your Android device using ADB:

adb push ksu_hello_world.zip /sdcard/Download/

2. Installing the Module

You can install the module using either the KernelSU Manager app or via the ksu command-line tool.

Using KernelSU Manager App:

1. Open the KernelSU Manager app on your device.
2. Tap the “Install from storage” or “Module” section (UI may vary).
3. Navigate to /sdcard/Download/ and select ksu_hello_world.zip.
4. The app will install the module. Reboot your device when prompted or when installation is complete.

Using ksu Command-Line Tool (from adb shell):

First, get a root shell:

adb shellsu

Then, use the ksu command to install:

/data/adb/ksu/bin/ksu module install /sdcard/Download/ksu_hello_world.zip

After installation, you’ll likely need to reboot for the service.sh script to execute if it’s meant for early boot.

reboot

3. Verifying the Module

After your device reboots, connect via ADB and check the kernel logs (dmesg) and the log file:

adb shellsu dmesg | grep "KernelSU Hello World"

You should see output similar to:

<6>KernelSU Hello World module activated!<6>Current date and time: [current date and time]

Also, check the userspace log file:

cat /data/local/tmp/ksu_hello_world.log

This should show:

Hello from KernelSU module at [current date and time]

If you see these messages, congratulations! You’ve successfully developed and deployed your first KernelSU module.

Beyond “Hello World”: What’s Next?

This simple module demonstrates the basic framework. The real power of KernelSU lies in its ability to:

• Inject Kernel Modules (.ko): Compile and load custom kernel modules directly.
• Hook System Calls: Intercept and modify the behavior of system calls.
• Modify Kernel Memory: Change kernel variables or data structures dynamically.
• Interact with User Space: Communicate between kernel and userspace components.

For more complex modules, you’ll delve into writing C/C++ code that compiles into a .ko file, which your service.sh script can then load using insmod. This opens up possibilities for custom drivers, security enhancements, and unique Android functionalities.

Conclusion

Developing KernelSU modules empowers you with unprecedented control over your Android device’s kernel. By following this guide, you’ve established a robust development environment and deployed a foundational “Hello World” module. This foundational knowledge is your stepping stone into the advanced world of kernel-level modifications, allowing you to explore custom features, optimize performance, and conduct in-depth security research directly from the heart of the Android system.