Mirrors/Magisk
1
0
Fork 0
mirror of https://github.com/topjohnwu/Magisk.git synced 2025-06-12 05:07:45 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
topjohnwu
2020-10-02 21:47:47 -07:00
parent 716f06846b
commit fbb4f85ef0
11 changed files with 294 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
docs/install.md
View File

@ -1,147 +1,139 @@
# Installation
If you already have Magisk installed, it is **strongly recommended to upgrade directly via Magisk Manager**. The following tutorial is for first time users.
If you already have Magisk installed, it is **strongly recommended** to upgrade directly via Magisk Manager using the "Direct Install" method. The following tutorial is only for initial installation.
## Getting Started
- If you are using a Huawei device running **EMUI 8 and higher**, please check [its section](#huawei).
- If you are using a Samsung device that is **launched with Android 9.0** (new devices in 2019), please check [its section](#samsung-system-as-root).
Otherwise, follow the instructions in [Knowing Your Device](#knowing-your-device), and choose the right steps
Before you start:
- If your device is **NOT** A/B, but **IS** using system-as-root, then you will have to install Magisk to the recovery partition of your device. Follow the instructions in [Boot Image Patching](#boot-image-patching), but instead of using your boot image, use your recovery image. **Read through the [Magisk in Recovery](#magisk-in-recovery) section!**
- Otherwise, you can either follow the instructions in [Custom Recovery](#custom-recovery) (if your device has custom recovery available) or [Boot Image Patching](#boot-image-patching).
- This tutorial assumes you understand how to use `adb` and `fastboot`
- Your device's bootloader has to be unlocked
- Make sure to remove any "boot image mods" such as other root solutions before installing Magisk. The easiest way is to restore the boot image with factory images, or reflash a *non-prerooted* custom ROM
- If you plan to also install custom kernels, install it after Magisk
Other notes:
---
- If you plan to install custom kernels, flash the zip **AFTER** installing Magisk
- Make sure to remove any 'boot image mods' such as other root solutions. The easiest way is to restore the boot image from factory images, or reflash a *non-prerooted* custom ROM
Download and install the latest Magisk Manager. We use the app to gather some information about your device. In the home screen, you should see this:
### Knowing Your Device
If your device is running anything older than Android 7.1, skip this section as your device will not be using A/B nor system-as-root.
<p align="center"><img src="images/device_info.png" width="500"/></p>
First, you need to know whether your device is using [A/B partitions](https://source.android.com/devices/tech/ota/ab). If you don't know, use a terminal (adb shell or any terminal emulator) to check with this command:
```
getprop ro.build.ab_update
```
If the result is `true`, then your device is using A/B partitions.
Pay special attention to the **Ramdisk** info. If the result is **Yes**, congratulations, your device is perfect for installing Magisk! However, if the result is **No**, this means your device's boot partition does **NOT** include ramdisk, and unfortunately you would have to go through some hoops to make Magisk work properly.
If your device is A/B, then your device is also certainly using [system-as-root](https://source.android.com/devices/bootloader/system-as-root). To find out whether you are using system-as-root on a non-A/B device, use a terminal to check with this command:
```
getprop ro.build.system_root_image
```
If the result is `true`, then your device is using system-as-root.
> **If your device does not have boot ramdisk, read the [Magisk in Recovery](#magisk-in-recovery) section after installing. The information in that section is VERY important!**
(P.S. If you are interested more regarding system-as-root, please check [this Twitter thread](https://twitter.com/topjohnwu/status/1174392824625676288))
If you are using a Samsung device and the **SAR** result is **Yes**, please check [its own section](#samsung-system-as-root).
If you are using a Huawei device and the **SAR** result is **Yes**, please check [its own section](#huawei).
Otherwise, continue to [Patching Images](#patching-images).
(P.S.1 If your device have boot ramdisk, you can also install with [Custom Recovery](#custom-recovery))<br>
(P.S.2 If you are interested in how Android boots and how it affects Magisk, check out [this document](#boot.md))
## Patching Images
If your device have boot ramdisk, you need a copy of the `boot.img`<br>
If your device does **NOT** have boot ramdisk, you need a copy of the `recovery.img`
You should be able to extract either of them from official firmware packages, your custom ROM zip (if using one), or go to [XDA-Developers](https://forum.xda-developers.com/) and seek for resources, guides, discussions, or ask for help in your device's forum.
- Copy the boot/recovery image to your device
- Press the **Install** button in the Magisk card
- If you are patching a recovery image, make sure **"Recovery Mode"** is checked in options.<br>In most cases it should already be automatically checked.
- Choose **"Select and Patch a File"** in method, and select the stock boot/recovery image
- Magisk Manager will patch the image to `[Internal Storage]/Download/magisk_patched.img`.
- Copy the patched image to your PC with ADB:<br>
`adb pull /sdcard/Download/magisk_patched.img`
- Flash the patched boot/recovery image to your device.<br>
For most devices, reboot into fastboot mode and flash with command:<br>
`fastboot flash boot /path/to/magisk_patched.img` or <br>
`fastboot flash recovery /path/to/magisk_patched.img` if flashing a recovery image
- Reboot and voila!
## Custom Recovery
If your device has custom recovery support, the easiest way is to install it through custom recoveries, such as TWRP.
In some custom recoveries of modern devices, the installer scripts either cannot properly detect the correct device info, or the recovery environment does not meet its expectation, causing the installation to fail (or looks like success but actually bootloops). If you face any issues, use the [Patch Image](#patching-images) method as it is guaranteed to work 100% of the time. Due to this reason, we no longer recommend installing Magisk through custom recoveries on modern devices. The custom recovery installation method exists mostly for legacy support.
- Download the Magisk installer zip
- Reboot to custom recovery
- Flash the zip and reboot
- Check whether Magisk Manager is installed. If for some reason it isn't installed automatically, manually install the APK
## Boot Image Patching
You would want to choose this method if either your device does not have custom recoveries, your device is A/B and you don't want to mix recovery and boot images, or your device is using system-as-root without A/B partitions.
To use this method, you are required to obtain a copy of the stock boot/recovery image, which can be found by extracting OEM provided factory images or extracting from OTA update zips. If you are unable to obtain one yourself, you might be able to find it somewhere on the internet. The following instructions will guide you through the process after you have the copy of boot/recovery image.
- Copy the boot/recovery image to your device
- Download and install the latest Magisk Manager
- If you are patching a recovery image, **manually check "Recovery Mode" in Advanced Settings!**
- Press **Install → Install → Select and Patch a File**, and select your stock boot/recovery image file
- Magisk Manager will patch the image, and store it in `[Internal Storage]/Download/magisk_patched.img`
- Copy the patched image from your device to your PC. If you can't find it via MTP, you can pull the file with ADB: <br>
`adb pull /sdcard/Download/magisk_patched.img`
- Flash the patched boot/recovery image to your device and reboot. For most devices, here is the fastboot command: <br>
`fastboot flash boot /path/to/magisk_patched.img` or <br>
`fastboot flash recovery /path/to/magisk_patched.img` if you are patching a recovery image
- Check whether Magisk Manager is installed. If it isn't installed automatically, manually install the APK.
## Magisk in Recovery
Since some devices no longer use ramdisk in boot images, Magisk has no choice but to be installed in the recovery partition. For these devices, you will have to **boot to recovery every time** if you want Magisk. Since both Magisk and recovery lives in the same partition, what you actually end up getting when you choose to boot to recovery will be determined by **how long you press volume up**.
Each OEM and device has its own key combo to boot into recovery. For example on Samsung S10 it is **(Power + Bixby + Volume Up)**, and for Huawei it is **(Power + Volume Up)**. As soon as you press the combo and the device vibrates with a splash screen, the bootloader has already chosen which mode it is booting, either it be `boot`, `recovery`, or some OEM specific modes like `download`, `fastboot`, or `erecovery`. After the splash screen, release all buttons to boot into Magisk, since by default `recovery` mode will boot to the system with Magisk enabled. If you decide to boot to actual recovery, continue to press volume up until you see the recovery screen.
If your device does not have ramdisk in boot images, Magisk has no choice but to be installed in the recovery partition. For these devices, you will have to **reboot to recovery** every time you want Magisk.
**After installing Magisk in recovery:**
- **(Powering up normally) → (System with NO Magisk)**
- **(OEM Recovery Key Combo) → (Splash screen) → (Release all buttons) → (System with Magisk)**
- **(OEM Recovery Key Combo) → (Splash screen) → (Keep pressing volume up) → (Actual recovery)**
When Magisk is installed in your recovery, **you CANNOT use custom recoveries to install/upgrade Magisk!** The only way to install/upgrade Magisk is through Magisk Manager. The app will be aware of your device state and install to the correct partition and reboot into the correct mode.
Important Note: **You CANNOT use custom recoveries to install/upgrade Magisk!**
Since Magisk now hijacks the recovery of the device, there is a mechanism to let you *actually* boot into recovery mode when needed: it is determined by **how long you press volume up**.
Each device has its own key combo to boot into recovery, as an example for Galaxy S10 it is (Power + Bixby + Volume Up). A quick Google search should easily get you this info of your device. As soon as you press the combo and the device vibrates with a splash screen, release all buttons to boot into Magisk. If you decide to boot into actual recovery mode, continue to press volume up until you see the recovery screen.
**After installing Magisk in recovery (starting from power off):**
- **(Power up normally) → (System with NO Magisk)**
- **(Recovery Key Combo) → (Splash screen) → (Release all buttons) → (System with Magisk)**
- **(Recovery Key Combo) → (Splash screen) → (Keep pressing volume up) → (Recovery Mode)**
## Samsung (System-as-root)
**If your device is NOT launched with Android 9.0 or higher (released after 2019), you are reading the wrong section.**
**If your device is NOT launched with Android 9.0 or higher, you are reading the wrong section.**
### Before Installing Magisk
- Your device is non-A/B and uses system-as-root, so Magisk will be installed to the **recovery** partition of your device. **Please read the [Magisk in Recovery](#magisk-in-recovery) section!**
- Installing Magisk **WILL** trip KNOX
- Installing Magisk for the first time **REQUIRES** a full data wipe, backup before continue
- You have to have your bootloader unlocked before following the instructions
- Installing Magisk for the first time **REQUIRES** a full data wipe (this is **NOT** counting the data wipe when unlocking bootloader). Backup your data before continue.
### Unlocking Bootloader
Normally I wouldn't provide instructions for this, but since things had changed drastically from previous Samsung devices, and there are some caveats, I figure this would be helpful.
- Allow bootloader unlocking in Developer options → OEM unlocking
- Reboot your device to download mode. Either use `adb reboot download`, or use the key combo for your device.
Unlocking BL on modern Samsung devices have some caveats, so I figure this would be helpful.
- Allow bootloader unlocking in **Developer options → OEM unlocking**
- Reboot to download mode: reboot and press the download mode key combo for your device.
- Long press volume up to unlock the bootloader. **This will wipe your data and automatically reboot.**
Just when you think the bootloader is unlocked, it is *actually* not! Samsung introduced `VaultKeeper`, meaning the bootloader will reject any unofficial partitions before `VaultKeeper` explicitly allows it.
If you think the bootloader is fully unlocked, it is actually not! Samsung introduced `VaultKeeper`, meaning the bootloader will still reject any unofficial partitions before `VaultKeeper` explicitly allows it.
- Go through the initial setup. Skip through all the steps since data will be wiped again later when we are installing Magisk. **Connect the device to internet in the setup!**
- Enable developer options, and **confirm that the OEM unlocking option exists and grayed out!** The `VaultKeeper` service will unleash the bootloader after it confirms that the user has the OEM unlocking option enabled.
- Go through the initial setup. Skip through all the steps since data will be wiped again later when we are installing Magisk. **Connect the device to Internet during the setup.**
- Enable developer options, and **confirm that the OEM unlocking option exists and is grayed out.** This means the `VaultKeeper` service has unleashed the bootloader.
- Your bootloader now accepts unofficial images in download mode.
### Instructions
1. Download the firmware for your device.
2. Unzip the firmware and copy the **AP** tar file to your device. It is normally named as `AP_[device_model_sw_ver].tar.md5`
3. Install the latest Magisk Manager
4. In Magisk Manager: **Install → Install → Select and Patch a File** and select the AP tar file.
5. Magisk Manager will patch the whole firmware file and store the output to
`[Internal Storage]/Download/magisk_patched.tar`
6. Copy the patched file to your PC with `adb pull /sdcard/Download/magisk_patched.tar`. Do not use MTP as it is reported to corrupt files.
7. Reboot to download mode, and flash `magisk_patched.tar` as AP in Odin, together with the BL, CP and HOME_CSC files. Never flash only an AP file, as Odin can shrink your `/data` file-system if you do.<br> **Important: Uncheck "Auto Reboot" in Options!**
8. Magisk is now successfully flashed to your device! But there are still several steps before you can properly use the device.
9. We now want to boot into the stock recovery to factory reset our device. <br>
**Full data wipe is mandatory! Do not skip this step.** <br>
Press *Power + Volume Down* to exit download mode. As soon as the screen turns off, immediately press the combo key to boot to recovery (e.g. on the S10 it is *Power + Bixby + Volume Up*). Since we want to boot into stock recovery, **continue pressing the volume up button until you see the stock recovery screen**.
10. Use volume buttons to navigate through the stock recovery menu, and the power button to select an option. Choose *Wipe data/factory reset* to wipe the data of the device.
11. This time, we can finally boot to the system with Magisk. Select *Reboot system now*, and immediately press the combo key to recovery. After seeing the bootloader warning screen, release all buttons so it can boot to the system.
12. The device will automatically reboot for the first time it boots. This is completely normal and done by design.
13. After the device is booted up, do the usual initial setup. **The following steps will need an internet connection.**
14. You shall see Magisk Manager in your app drawer; if not, manually install the APK you downloaded in step 3 and continue to the next step. The app would be a stub and it shall automatically upgrade to the full Magisk Manager when you open it.
15. Magisk Manager will ask to do additional setups. Let it do its job and the app will automatically reboot your device.
16. Voila! Enjoy Magisk :)
### Additional Info
- Magisk actually patches 3 partitions on your device:
- `vbmeta`: replace with empty vbmeta image to disable partition verification
- `boot`: remove the signature of the image to prevent soft bricks
- `recovery`: this is where Magisk is actually installed
- **Never, ever** try to restore either of the 3 images mentioned back to stock! You can easily brick your device by doing so, and the only way out is to do full Odin restore following with factory reset. Just don't do it.
- If you want to upgrade your device, **never** flash the stock **AP** tar file with the reasons mentioned above. **Always** pre-patch the firmware before flashing in Odin.
- If you don't need to patch the full firmware, you can manually create a tar file with **at least** `vbmeta.img`, `boot.img`, and `recovery.img` to let Magisk Manager patch your images in the proper way.
- Use either [Frija](https://forum.xda-developers.com/s10-plus/how-to/tool-frija-samsung-firmware-downloader-t3910594) or [Samloader](https://forum.xda-developers.com/s10-plus/how-to/tool-samloader-samfirm-frija-replacement-t4105929) to download the latest firmware zip of your device directly from Samsung servers.
- Unzip the firmware and copy the `AP` tar file to your device. It is normally named as `AP_[device_model_sw_ver].tar.md5`
- Press the **Install** button in the Magisk card
- If your device does **NOT** have boot ramdisk, make sure **"Recovery Mode"** is checked in options.<br>In most cases it should already be automatically checked.
- Choose **"Select and Patch a File"** in method, and select the `AP` tar file
- Magisk Manager will patch the whole firmware file to `[Internal Storage]/Download/magisk_patched.tar`
- Copy the patched tar file to your PC with ADB:<br>
`adb pull /sdcard/Download/magisk_patched.tar`<br>
Do **NOT** use MTP as it is reported to corrupt files.
- Reboot to download mode. Open Odin on your PC, and flash `magisk_patched.tar` as `AP`, together with `BL`, `CP`, and `CSC` (**NOT** `HOME_CSC` because we want to **wipe data**) from the original firmware.
- After Odin is done, your device should reboot. You may continue with standard initial setup.
- If your device does **NOT** have boot ramdisk, reboot to recovery now to boot Android with Magisk (reason stated in [Magisk in Recovery](#magisk-in-recovery)).
- Although Magisk is installed, it still need some additional setup. Please connect to the Internet.
- Install the latest Magisk Manager and open the app. It should show a dialog asking for additional setups. Let it do its job and the app will automatically reboot your device.
- Voila! Enjoy Magisk 😃
### Additional Notes
- **Never, ever** try to restore either `boot` or `recovery` partitions back to stock! You can easily brick your device by doing so, and the only way out is to do a full Odin restore with data wipe.
- To upgrade your device with a new firmware, **NEVER** directly use the stock `AP` tar file with reasons mentioned above. **Always** pre-patch `AP` in Magisk Manager before flashing in Odin.
- Use `HOME_CSC` to preserve your data when doing a firmware upgrade. Using `CSC` is only necessary for the initial installation.
- Never just flash only `AP`, or else Odin can shrink your `/data` filesystem. Flash full `AP` + `BL` + `CP` + `HOME_CSC` when upgrading.
## Huawei
Huawei devices using Kirin processors have a different partitioning method from most common devices. Magisk is usually installed to the `boot` partition of the device, however Huawei devices do not have this partition. Depending on what EMUI version your device is running, the instructions will be slightly different.
Magisk no longer officially support modern Huawei devices as the bootloader on their devices are not unlockable, and more importantly they do not follow standard Android partitioning schemes. The following are some general guidance for the few who managed to unlock their bootloader and really want to root it.
### Obtain Stock Images
Huawei does not release official factory images, however most firmware zips can be downloaded from the [Huawei Firmware Database](http://pro-teammt.ru/firmware-database/). To extract images from `UPDATE.APP` in the zip, you have to use [Huawei Update Extractor](https://forum.xda-developers.com/showthread.php?t=2433454) (Windows only!)
Huawei devices using Kirin processors have a different partitioning method from most common devices. Magisk is usually installed to the `boot` partition of the device, however Huawei devices do not have this partition.
### EMUI 8
For EMUI 8 devices, your device has a partition named `ramdisk`, which is where Magisk is going to be installed.
Generally, follow [Patching Images](#patching-images) with some differences from the original instructions:
- If you plan to use custom recoveries, simply follow the instructions for custom recovery and you're all set.
- If you plan not to use custom recoveries, you will have to extract `RAMDISK.img` from your firmware. Follow the instructions for boot image patching above, but use the `RAMDISK.img` file instead of a boot image.
- To flash the patched image to your device, here is the fastboot command: <br>
`fastboot flash ramdisk /path/to/magisk_patched.img` <br>
Be aware you are flashing to `ramdisk`, not `boot`!
### EMUI 9 or Higher
For EMUI 9+ devices, the `ramdisk` partition no longer exists. As a workaround, Magisk will be installed to the `recovery_ramdisk` partition. **Please read the [Magisk in Recovery](#magisk-in-recovery) section before following the instructions below!**
*Note: As I tested on my Honor View 10, Huawei's kernel does not seem to be able to capture key button press events in early boot, so long pressing Volume Up does **NOT** boot to recovery on my device. Your experience may vary.*
- If you plan to use custom recoveries, simply follow the instructions for custom recovery and you're all set. <br>
**Warning: Magisk will overwrite the custom recovery.**
- If you plan not to use custom recoveries, you will have to extract `RECOVERY_RAMDIS.img` from your firmware. Follow the instructions for boot image patching above, but use the `RECOVERY_RAMDIS.img` file instead of a boot image.
- To flash the patched image to your device, here is the fastboot command: <br>
`fastboot flash recovery_ramdisk /path/to/magisk_patched.img` <br>
Be aware you are flashing to `recovery_ramdisk`, not `boot`!
- After downloading your firmware zip (you may find a lot in [Huawei Firmware Database](http://pro-teammt.ru/firmware-database/)), you have to extract images from `UPDATE.APP` in the zip with [Huawei Update Extractor](https://forum.xda-developers.com/showthread.php?t=2433454) (Windows only!)
- Regarding patching images:
- If your device has boot ramdisk, patch `RAMDISK.img` instead of `boot.img`
- If your device does **NOT** have boot ramdisk, patch `RECOVERY_RAMDIS.img` (this is not a typo) instead of `recovery.img`
- When flashing the image back with `fastboot`
- If you patched `RAMDISK.img`, flash with command `fastboot flash ramdisk magisk_patched.img`
- If you patched `RECOVERY_RAMDIS.img`, flash with command `fastboot flash recovery_ramdisk magisk_patched.img`