diff --git a/website/docs/guide/installation.md b/website/docs/guide/installation.md index e1b31b42..49bfd5bf 100644 --- a/website/docs/guide/installation.md +++ b/website/docs/guide/installation.md @@ -43,6 +43,12 @@ w .x .y -zzz -k -something Note that the SubLevel in the kernel version is not part of the KMI! That means that `5.10.101-android12-9-g30979850fc20` has the same KMI as `5.10.137-android12-9-g30979850fc20`! ::: +### Security patch level {#security-patch-level} + +Newer Android devices may have anti-rollback mechanisms in place that do not allow flashing a boot image with an old security patch level. For example, if your device kernel is `5.10.101-android12-9-g30979850fc20`, its security patch is `2023-11`; even if you flash the kernel consistent with the kernel KMI, if the security patch level is older than `2023- 11`(such as `2023-06`), then it may cause bootloop. + +Therefore, kernels with latest security patch levels are preferred while maintaining KMI consistency. + ### Kernel version vs. Android version Please note: **Kernel version and Android version are not necessarily the same!** @@ -53,51 +59,22 @@ If you find that your kernel version is `android12-5.10.101`, but your Android s There are several installation methods for KernelSU, each suitable for a different scenario, so please choose as needed. -1. Install with custom Recovery (e.g. TWRP) -2. Install with a kernel flash app, such as Franco Kernel Manager -3. Install with fastboot using the boot.img provided by KernelSU -4. Repair the boot.img manually and install it - -## Install with custom Recovery - -Prerequisite: Your device must have a custom Recovery, such as TWRP; if not or only official Recovery is available, use another method. - -Step: - -1. From the [Release page](https://github.com/tiann/KernelSU/releases) of KernelSU, download the zip package starting with AnyKernel3 that matches your phone version; for example, the phone kernel version is `android12-5.10. 66`, then you should download the file `AnyKernel3-android12-5.10.66_yyyy-MM.zip` (where `yyyy` is the year and `MM` is the month). -2. Reboot the phone into TWRP. -3. Use adb to put AnyKernel3-*.zip into the phone /sdcard and choose to install it in the TWRP GUI; or you can directly `adb sideload AnyKernel-*.zip` to install. - -PS. This method is suitable for any installation (not limited to initial installation or subsequent upgrades), as long as you use TWRP. - -## Install with Kernel Flasher - -Prerequisite: Your device must be rooted. For example, you have installed Magisk to get root, or you have installed an old version of KernelSU and need to upgrade to another version of KernelSU; if your device is not rooted, please try other methods. - -Step: - -1. Download the AnyKernel3 zip; refer to the section *Installing with Custom Recovery* for downloading instructions. -2. Open the Kernel Flash App and use the provided AnyKernel3 zip to flash. - -If you haven't used the Kernel flash App before, the following are the more popular ones. - -1. [Kernel Flasher](https://github.com/capntrips/KernelFlasher/releases) -2. [Franco Kernel Manager](https://play.google.com/store/apps/details?id=com.franco.kernel) -3. [Ex Kernel Manager](https://play.google.com/store/apps/details?id=flar2.exkernelmanager) - -PS. This method is more convenient when upgrading KernelSU and can be done without a computer (backup first!). . +1. Install with fastboot using the boot.img provided by KernelSU +2. Install with a kernel flash app, such as KernelFlasher +3. Repair the boot.img manually and install it +4. Install with custom Recovery (e.g. TWRP) ## Install with boot.img provided by KernelSU -This method does not require you to have TWRP, nor does it require your phone to have root privileges; it is suitable for your first installation of KernelSU. +If your device's `boot.img` uses a commonly used compression format, you can use the GKI images provided by KernelSU to flash it directly. It does not require TWRP or self-patching the image. ### Find proper boot.img KernelSU provides a generic boot.img for GKI devices and you should flush the boot.img to the boot partition of the device. -You can download boot.img from [GitHub Release](https://github.com/tiann/KernelSU/releases), please note that you should use the correct version of boot.img. For example, if your device displays the kernel `android12-5.10.101` , you need to download `android-5.10.101_yyyy-MM.boot-.img`. (Keep KMI consistent!) +You can download boot.img from [GitHub Release](https://github.com/tiann/KernelSU/releases), please note that you should use the correct version of boot.img. If you don't know which file to download, please carefully read the description of [KMI](#kmi) and [Security Patch Level](#security-patch-level) in this document. -Where `` refers to the kernel compression format of your official boot.img, please check the kernel compression format of your original boot.img, you should use the correct format, e.g. `lz4`, `gz`; if you use an incorrect compression format, you may encounter bootloop. +Normally, there are three boot files in different formats under the same KMI and security patch level. They are all the same except for the kernel compression format. Please check the kernel compression format of your original boot.img. You should use the correct format, such as `lz4`, `gz`; if you use an incorrect compression format, you may encounter bootloop after flashing boot. ::: info 1. You can use magiskboot to get the compression format of your original boot; of course you can also ask other, more experienced kids with the same model as your device. Also, the compression format of the kernel usually does not change, so if you boot successfully with a certain compression format, you can try that format later. @@ -125,16 +102,38 @@ After flashing is complete, you should reboot your device: fastboot reboot ``` +## Install with Kernel Flasher + +Step: + +1. Download the AnyKernel3 zip. If you don't know which file to download, please carefully read the description of [KMI](#kmi) and [Security Patch Level](#security-patch-level) in this document. +2. Open the Kernel Flash App (grant necessary root permissions) and use the provided AnyKernel3 zip to flash. + +This way requires the kernel flash App to have root permissions. You can use the following methods to achieve this: + +1. Your device has rooted. For example, you have installed KernelSU and want to upgrade to the latest version, or you have rooted through other methods (such as Magisk). +2. If your phone is not rooted, but the phone supports the temporary boot method of `fastboot boot boot.img`, you can use the GKI image provided by KernelSU to temporarily boot your device, obtain temporary root permissions, and then use the kernel flash Flash the writer to obtain permanent root privileges. + +1. [Kernel Flasher](https://github.com/capntrips/KernelFlasher/releases) +2. [Franco Kernel Manager](https://play.google.com/store/apps/details?id=com.franco.kernel) +3. [Ex Kernel Manager](https://play.google.com/store/apps/details?id=flar2.exkernelmanager) + +PS. This method is more convenient when upgrading KernelSU and can be done without a computer (backup first!). . + ## Patch boot.img manually For some devices, the boot.img format is not so common, such as not `lz4`, `gz` and uncompressed; the most typical is Pixel, its boot.img format is `lz4_legacy` compressed, ramdisk may be `gz` may also be `lz4_legacy` compression; at this time, if you directly flash the boot.img provided by KernelSU, the phone may not be able to boot; at this time, you can manually patch the boot.img to achieve. -There are generally two patch methods: +It's always recommended to use `magiskboot` to patch images, there are two ways: -1. [Android-Image-Kitchen](https://forum.xda-developers.com/t/tool-android-image-kitchen-unpack-repack-kernel-ramdisk-win-android-linux-mac.2073775/) -2. [magiskboot](https://github.com/topjohnwu/Magisk/releases) +1. [magiskboot](https://github.com/topjohnwu/Magisk/releases) +2. [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci) -Among them, Android-Image-Kitchen is suitable for operation on PC, and magiskboot needs the cooperation of mobile phone. +The official build of `magiskboot` can only run on Android devices, if you want to run it on PC, you can try the second one. + +::: tip +Android-Image-Kitchen is not recommended now, because it doesn't handle the boot metadata(such as security patch level) correctly, thus it may not work on some devices. +::: ### Preparation @@ -142,15 +141,7 @@ Among them, Android-Image-Kitchen is suitable for operation on PC, and magiskboo 2. Download the AnyKernel3 zip file provided by KernelSU that matches the KMI version of your device (you can refer to the *Install with custom Recovery*). 3. Unpack the AnyKernel3 package and get the `Image` file, which is the kernel file of KernelSU. -### Using Android-Image-Kitchen - -1. Download Android-Image-Kitchen to your computer. -2. Put stock boot.img to Android-Image-Kitchen's root folder. -3. Execute `./unpackimg.sh boot.img` at root directory of Android-Image-Kitchen, this command would unpack boot.img and you will get some files. -4. Replace `boot.img-kernel` in the `split_img` directory with the `Image` you extracted from AnyKernel3 (note the name change to boot.img-kernel). -5. Execute `./repackimg.sh` at root directory of 在 Android-Image-Kitchen; And you will get a file named `image-new.img`; Flash this boot.img by fastboot(Refer to the previous section). - -### Using magiskboot +### Using magiskboot on Android devices {#using magiskboot on Android} 1. Download latest Magisk from [Release Page](https://github.com/topjohnwu/Magisk/releases) 2. Rename Magisk-*.apk to Magisk-vesion.zip and unzip it. @@ -161,9 +152,36 @@ Among them, Android-Image-Kitchen is suitable for operation on PC, and magiskboo 7. Replace `kernel` with `Image`: `mv -f Image kernel` 8. Execute `./magiskboot repack boot.img` to repack boot img, and you will get a `new-boot.img` file, flash this file to device by fastboot. +### Using magiskboot on Windows/macOS/Linux PC {#using magiskboot on PC} + +1. Download proper `magiskboot` for your OS from [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci) +2. Prepare stock boot.img and Image in your PC. +3. `chmod +x magiskboot` +4. Enter the proper directory, execute `./magiskboot unpack boot.img` to unpack `boot.img`, you will get a `kernel` file, this is your stock kernel. +5. Replace `kernel` with `Image`: `mv -f Image kernel` +6. Execute `./magiskboot repack boot.img` to repack boot img, and you will get a `new-boot.img` file, flash this file to device by fastboot. + +::: info +Official `magiskboot` can run `Linux` device normally, if you are a Linux user, you can use official build. +::: + +## Install with custom Recovery + +Prerequisite: Your device must have a custom Recovery, such as TWRP; if not or only official Recovery is available, use another method. + +Step: + +1. From the [Release page](https://github.com/tiann/KernelSU/releases) of KernelSU, download the zip package starting with AnyKernel3 that matches your phone version; for example, the phone kernel version is `android12-5.10. 66`, then you should download the file `AnyKernel3-android12-5.10.66_yyyy-MM.zip` (where `yyyy` is the year and `MM` is the month). +2. Reboot the phone into TWRP. +3. Use adb to put AnyKernel3-*.zip into the phone /sdcard and choose to install it in the TWRP GUI; or you can directly `adb sideload AnyKernel-*.zip` to install. + +PS. This method is suitable for any installation (not limited to initial installation or subsequent upgrades), as long as you use TWRP. + ## Other methods In fact, all these installation methods have only one main idea, which is to **replace the original kernel for the one provided by KernelSU**; as long as this can be achieved, it can be installed; for example, the following are other possible methods. 1. First install Magisk, get root privileges through Magisk and then use the kernel flasher to flash in the AnyKernel zip from KernelSU. 2. Use some flashing toolkit on PCs to flash in the kernel provided KernelSU. + +But if it doesn't work, please try `magiskboot` way. \ No newline at end of file diff --git a/website/docs/zh_CN/guide/installation.md b/website/docs/zh_CN/guide/installation.md index be231b8b..9a4a288b 100644 --- a/website/docs/zh_CN/guide/installation.md +++ b/website/docs/zh_CN/guide/installation.md @@ -43,6 +43,12 @@ w .x .y -zzz -k -something 请注意，内核版本中的 SubLevel 不属于 KMI 的范畴！也就是说 `5.10.101-android12-9-g30979850fc20` 与 `5.10.137-android12-9-g30979850fc20` 的 KMI 相同！ ::: +### 安全补丁级别 {#security-patch-level} + +新的 Android 设备上可能采取了防回滚机制，它不允许刷入一个安全补丁更旧的内核。比如，如果你的设备内核是 `5.10.101-android12-9-g30979850fc20`，它的安全补丁为 `2023-11`；即使你刷入与内核 KMI 一致的内核，如果安全补丁级别比 `2023-11`要老（例如`2023-06`），那么很可能会无法开机。 + +因此，在保持 KMI 一致的情况下，优先采用安全补丁级别更新的内核。 + ### 内核版本与 Android 版本 {#kernel-version-vs-android-version} 请注意：**内核版本与 Android 版本并不一定相同！** @@ -53,51 +59,22 @@ w .x .y -zzz -k -something KernelSU 的安装方法有如下几种，各自适用于不同的场景，请按需选择： -1. 使用自定义 Recovery（如 TWRP）安装 -2. 使用内核刷写 App，如 （Franco Kernel Manager）安装 -3. 使用 KernelSU 提供的 boot.img 使用 fastboot 安装 -4. 手动修补 boot.img 然后安装 - -## 使用自定义 Recovery 安装 {#install-by-recovery} - -前提：你的设备必须有自定义的 Recovery，如 TWRP；如果没有或者只有官方 Recovery，请使用其他方法。 - -步骤： - -1. 在 KernelSU 的 [Release 页面](https://github.com/tiann/KernelSU/releases) 下载与你手机版本匹配的以 AnyKernel3 开头的 zip 刷机包；例如，手机内核版本为 `android12-5.10.66`，那么你应该下载 `AnyKernel3-android12-5.10.66_yyyy-MM.zip` 这个文件（其中 `yyyy` 为年份，`MM` 为月份）。 -2. 重启手机进入 TWRP。 -3. 使用 adb 将 AnyKernel3-*.zip 放到手机 /sdcard 然后在 TWRP 图形界面选择安装；或者你也可以直接 `adb sideload AnyKernel-*.zip` 安装。 - -PS. 这种方法适用于任何情况下的安装（不限于初次安装或者后续升级），只要你用 TWRP 就可以操作。 - -## 使用内核刷写 App 安装 {#install-by-kernel-flasher} - -前提：你的设备必须已经 root。例如你已经安装了 Magisk 获取了 root，或者你已经安装了旧版本的 KernelSU 需要升级到其他版本的 KernelSU；如果你的设备无 root，请尝试其他方法。 - -步骤： - -1. 下载 AnyKernel3 的刷机包；下载方法参考 *使用自定义 Recovery 安装*那一节的内容。 -2. 打开内核刷写 App 使用提供的 AnyKernel3 刷机包刷入。 - -如果你之前没有用过内核刷写 App，那么下面几个是比较流行的： - -1. [Kernel Flasher](https://github.com/capntrips/KernelFlasher/releases) -2. [Franco Kernel Manager](https://play.google.com/store/apps/details?id=com.franco.kernel) -3. [Ex Kernel Manager](https://play.google.com/store/apps/details?id=flar2.exkernelmanager) - -PS. 这种方法在升级 KernelSU 的时候较为方便，无需电脑即可完成（注意备份！）。 +1. 使用 KernelSU 提供的**通用内核镜像**使用 fastboot 安装 +2. 使用内核刷写 App（如 KernelFlasher）安装 +3. 手动修补 boot.img 然后安装 +4. 使用自定义 Recovery（如 TWRP）安装 ## 使用 KernelSU 提供的 boot.img 安装 {#install-by-kernelsu-boot-image} -这种方法无需你有 TWRP，也不需要你的手机有 root 权限；适用于你初次安装 KernelSU。 +如果你设备的 `boot.img` 采用常用的压缩格式，那么可以采用 KernelSU 提供的的通用内核镜像直接刷入，它不需要 TWRP 或者自行修补镜像。 ### 找到合适的 boot.img {#found-propery-image} KernelSU 为 GKI 设备提供了通用的 boot.img，您应该将 boot.img 刷写到设备的 boot 分区。 -您可以从 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下载 boot.img, 请注意您应该使用正确版本的 boot.img. 例如，如果您的设备显示内核是 `android12-5.10.101`, 需要下载 `android-5.10.101_yyyy-MM.boot-.img`. +您可以从 [GitHub Release](https://github.com/tiann/KernelSU/releases) 下载 boot.img, 请注意您应该使用正确版本的 boot.img。如果您不知道应该下载哪一个文件，请仔细阅读本文档中关于 [KMI](#kmi) 和 [安全补丁级别](#security-patch-level)的描述。 -其中 `` 指的是你的官方 boot.img 的内核压缩格式，请检查您原有 boot.img 的内核压缩格式，您应该使用正确的格式，例如 `lz4`、`gz`；如果是用不正确的压缩格式，刷入 boot 后可能无法开机。 +通常情况下，同一个 KMI 和 安全补丁级别下会有三个不同格式的 boot 文件，它们除了内核压缩格式不同之外都一样。请检查您原有 boot.img 的内核压缩格式，您应该使用正确的格式，例如 `lz4`、`gz`；如果是用不正确的压缩格式，刷入 boot 后可能无法开机。 ::: info 1. 您可以通过 magiskboot 来获取你原来 boot 的压缩格式；当然您也可以询问与您机型相同的其他更有经验的童鞋。另外，内核的压缩格式通常不会发生变化，如果您使用某个压缩格式成功开机，后续可优先尝试这个格式。 @@ -125,32 +102,47 @@ fastboot flash boot boot.img fastboot reboot ``` +## 使用内核刷写 App 安装 {#install-by-kernel-flasher} + +步骤： + +1. 下载 AnyKernel3 的刷机包，如果你不知道下载哪一个，请仔细查阅上述文档中关于 [KMI](#kmi) 和 [安全补丁级别](#security-patch-level)的描述；下载错误的刷机包很可能导致无法开机，请注意备份。 +2. 打开内核刷写 App（授予必要的 root 权限），使用提供的 AnyKernel3 刷机包刷入。 + +这种方法需要内核刷写 App 拥有 root 权限，你可以用如下几种方法实现： + +1. 你的设备已经获取了 root 权限，比如你已经安装好了 KernelSU 想升级到最新的版本，又或者你通过其他方法（如 Magisk）获取了 root。 +2. 如果你的手机没有 root，但手机支持 `fastboot boot boot.img` 这种临时启动的方法，你可以用 KernelSU 提供的 GKI 镜像临时启动你的设备，获取临时的 root 权限，然后使用内核刷写器刷入获取永久 root 权限。 + + +If you haven’t used kernel flashing apps before, the following are recommended: + +1. [Kernel Flasher](https://github.com/capntrips/KernelFlasher/releases) +2. [Franco Kernel Manager](https://play.google.com/store/apps/details?id=com.franco.kernel) +3. [Ex Kernel Manager](https://play.google.com/store/apps/details?id=flar2.exkernelmanager) + ## 手动修补 boot.img {#patch-boot-image} 对于某些设备来说，其 boot.img 格式不那么常见，比如不是 `lz4`, `gz` 和未压缩；最典型的就是 Pixel，它 boot.img 的格式是 `lz4_legacy` 压缩，ramdisk 可能是 `gz` 也可能是 `lz4_legacy` 压缩；此时如果你直接刷入 KernelSU 提供的 boot.img，手机可能无法开机；这时候，你可以通过手动修补 boot.img 来实现。 -修补方法总体有两种： +任何情况下都推荐使用 `magiskboot` 来修补 boot 镜像，有两个方法： -1. [Android-Image-Kitchen](https://forum.xda-developers.com/t/tool-android-image-kitchen-unpack-repack-kernel-ramdisk-win-android-linux-mac.2073775/) -2. [magiskboot](https://github.com/topjohnwu/Magisk/releases) +1. [magiskboot](https://github.com/topjohnwu/Magisk/releases) +2. [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci) -其中，Android-Image-Kitchen 适用于 PC 上操作，magiskboot 需要手机配合。 +Magisk 官方提供的 `magiskboot` 只能运行在 Android/Linux 设备上，如果你想在 macOS/Windows 上使用 `magiskboot` 可以使用第二个方法。 + +::: tip +不再推荐使用 Android-Image-Kitchen，因为它可能没有合理地处理 boot 元数据（比如安全补丁级别），从而导致某些设备上会无法启动。 +::: ### 准备 {#patch-preparation} 1. 获取你手机的原厂 boot.img；你可以通过你手机的线刷包解压后之间获取，如果你是卡刷包，那你也许需要[payload-dumper-go](https://github.com/ssut/payload-dumper-go) -2. 下载 KernelSU 提供的与你设备 KMI 版本一致的 AnyKernel3 刷机包（可以参考 *自定义 TWRP 刷入一节*)。 +2. 下载 KernelSU 提供的与你设备 KMI 版本一致的 AnyKernel3 刷机包；如果您不知道应该下载哪一个文件，请仔细阅读本文档中关于 [KMI](#kmi) 和 [安全补丁级别](#security-patch-level)的描述。 3. 解压缩 AnyKernel3 刷机包，获取其中的 `Image` 文件，此文件为 KernelSU 的内核文件。 -### 使用 Android-Image-Kitchen {#using-android-image-kitchen} - -1. 下载 Android-Image-Kitchen 至你电脑 -2. 将手机原厂 boot.img 放入 Android-Image-Kitchen 根目录 -3. 在 Android-Image-Kitchen 根目录执行 `./unpackimg.sh boot.img`；此命名会将 boot.img 拆开，你会得到若干文件。 -4. 将`split_img` 目录中的 `boot.img-kernel` 替换为你从 AnyKernel3 解压出来的 `Image`（注意名字改为 boot.img-kernel)。 -5. 在 Android-Image-Kitchecn 根目录执行 `./repackimg.sh`；此时你会得到一个 `image-new.img` 的文件；使用此 boot.img 通过 fastboot 刷入即可（刷入方法参考上一节）。 - -### 使用 magiskboot {#using magiskboot} +### 在 Android 设备上使用 magiskboot {#using magiskboot on Android} 1. 在 Magisk 的 [Release 页面](https://github.com/topjohnwu/Magisk/releases) 下载最新的 Magisk 安装包。 2. 将 Magisk-*.apk 重命名为 Magisk-vesion.zip 然后解压缩。 @@ -161,9 +153,36 @@ fastboot reboot 7. 使用 `Image` 替换 `kernel`: `mv -f Image kernel` 8. 执行 `./magiskboot repack boot.img` 打包 img，此时你会得到一个 `new-boot.img` 的文件，使用这个文件 fastboot 刷入设备即可。 +### 在 macOS/Windows/Linux 上使用 magiskboot {#using magiskboot on PC} + +1. 在 [magiskboot_build](https://github.com/ookiineko/magiskboot_build/releases/tag/last-ci) 下载适合你操作系统的 `magiskboot` 二进制文件。 +2. 在你的 PC 上准备好设备原厂的 boot.img 和 KernelSU 的 Image。 +3. `chmod +x magiskboot` +4. 在你 PC 上合适的目录执行 `./magiskboot unpack boot.img` 来解包 `boot.img`, 你会得到一个 `kernel` 文件，这个文件是你设备原厂的 kernel。 +5. 使用 `Image` 替换 `kernel`: `mv -f Image kernel` +6. 执行 `./magiskboot repack boot.img` 打包 img，此时你会得到一个 `new-boot.img` 的文件，使用这个文件 fastboot 刷入设备即可。 + +:::info +Magisk 官方的 `magiskboot` 可以在 Linux 设备上执行，如果你是 Linux 用户，可以直接用官方版本。 +::: + +## 使用自定义 Recovery 安装 {#install-by-recovery} + +前提：你的设备必须有自定义的 Recovery，如 TWRP；如果没有或者只有官方 Recovery，请使用其他方法。 + +步骤： + +1. 在 KernelSU 的 [Release 页面](https://github.com/tiann/KernelSU/releases) 下载与你手机版本匹配的以 AnyKernel3 开头的 zip 刷机包；如果你不知道下载哪一个，请仔细查阅上述文档中关于**KMI**和**安全补丁级别**的描述；下载错误的刷机包很可能导致无法开机，请注意备份。 +2. 重启手机进入 TWRP。 +3. 使用 adb 将 AnyKernel3-*.zip 放到手机 /sdcard 然后在 TWRP 图形界面选择安装；或者你也可以直接 `adb sideload AnyKernel-*.zip` 安装。 + +PS. 这种方法适用于任何情况下的安装（不限于初次安装或者后续升级），只要你用 TWRP 就可以操作。 + ## 其他变通方法 {#other-methods} 其实所有这些安装方法的主旨只有一个，那就是**替换原厂的内核为 KernelSU 提供的内核**；只要能实现这个目的，就可以安装；比如以下是其他可行的方法： 1. 首先安装 Magisk，通过 Magisk 获取 root 权限后使用内核刷写器刷入 KernelSU 的 AnyKernel 包。 2. 使用某些 PC 上的刷机工具箱刷入 KernelSU 提供的内核。 + +如果这些方法导致无法开机，请优先尝试用 `magiskboot` 的方法。 \ No newline at end of file