Update documentation

2020-03-23 04:24:20 -07:00 · 2020-03-23 04:24:20 -07:00 · ffaa264bd3
commit ffaa264bd3
parent ba7cb47383
8 changed files with 90 additions and 115 deletions
--- a/README.MD
+++ b/README.MD
@ -1,41 +1,65 @@
-# Magisk
+![](docs/images/logo.png)
 [Downloads](https://github.com/topjohnwu/Magisk/releases) \| [Documentation](https://topjohnwu.github.io/Magisk/) \| [XDA Thread](https://forum.xda-developers.com/apps/magisk/official-magisk-v7-universal-systemless-t3473445)
 ## Introduction
-Magisk is a suite of open source tools for customizing Android, supporting devices higher than Android 4.2 (API 17). It covers the fundamental parts for Android customization: root, boot scripts, SELinux patches, AVB2.0 / dm-verity / forceencrypt removals etc.
+Magisk is a suite of open source tools for customizing Android, supporting devices higher than Android 4.2. It covers fundamental parts of Android customization: root, boot scripts, SELinux patches, AVB2.0 / dm-verity / forceencrypt removals etc.
-Furthermore, Magisk provides a **Systemless Interface** to alter the system (or vendor) arbitrarily while the actual partitions stay completely intact. With its systemless nature along with several other hacks, Magisk can almost perfectly hide modifications within userspace. Note that since 2020.3, the CTS check of [Google's SafetyNet API](https://developer.android.com/training/safetynet/index.html) will **NOT** pass.
+Here are some feature highlights:
 - **MagiskSU**: Provide root access to your device
 - **Magisk Modules**: Modify read-only partitions by installing modules
 - **MagiskHide**: Hide Magisk from root detections / system integrity checks
 ## Download
 [![](https://img.shields.io/badge/Magisk%20Manager-v7.5.1-green)](https://github.com/topjohnwu/Magisk/releases/download/manager-v7.5.1/MagiskManager-v7.5.1.apk)
 [![](https://img.shields.io/badge/Magisk-v20.3-blue)](https://github.com/topjohnwu/Magisk/releases/download/v20.3/Magisk-v20.3.zip)
 [![](https://img.shields.io/badge/Magisk%20Beta-v20.4-blue)](https://github.com/topjohnwu/Magisk/releases/download/v20.4/Magisk-v20.4.zip)
 <br>
 [![](https://img.shields.io/badge/Magisk%20Manager-Canary-red)](https://raw.githubusercontent.com/topjohnwu/magisk_files/canary/app-release.apk)
 [![](https://img.shields.io/badge/Magisk%20Manager-Canary%20Debug-red)](https://raw.githubusercontent.com/topjohnwu/magisk_files/canary/app-debug.apk)
 ## Useful Links
 - [Installation Instruction](https://topjohnwu.github.io/Magisk/install.html)
 - [OTA Upgrade Guide](https://topjohnwu.github.io/Magisk/ota.html)
 - [Full Official Docs](https://topjohnwu.github.io/Magisk/)
 - [Magisk Troubleshoot Wiki](https://www.didgeridoohan.com/magisk/HomePage) (by [@Didgeridoohan](https://github.com/Didgeridoohan))
 ## Android Version Support
 - Android 4.2+: MagiskSU and Magisk Modules Only
 - Android 4.4+: All core features available
 - Android 6.0+: Guaranteed MagiskHide support
 - Android 7.0+: Full MagiskHide protection
 - Android 9.0+: Magisk Manager stealth mode
 ## Bug Reports
-**Only reports using debug canary builds will be accepted.** \
+Canary Channels are cutting edge builds for those adventurous. To access canary builds, install either Canary Magisk Manager, switch to a Canary Channel in settings and upgrade.
 Access canary builds by upgrading to either canary Magisk Manager:
 - [Canary Manager (Release)](https://raw.githubusercontent.com/topjohnwu/magisk_files/canary/app-release.apk)
 - [Canary Manager (Debug)](https://raw.githubusercontent.com/topjohnwu/magisk_files/canary/app-debug.apk)
-For installation issues, upload both boot image and install logs. \
+**Only bug reports from Canary DEBUG builds will be accepted.**
-For Magisk issues, upload boot logcat or dmesg. \
+
 For installation issues, upload both boot image and install logs.<br>
 For Magisk issues, upload boot logcat or dmesg.<br>
 For Magisk Manager crashes, record and upload the logcat when the crash occurs.
-## Building Environment Requirements
+## Building Magisk
-  Python 3: run `build.py` script
+- Clone sources: `git clone --recurse-submodules https://github.com/topjohnwu/Magisk.git`
-  Java Development Kit (JDK) 8: Compile Magisk Manager and sign zips
+- Magisk builds on any OS Android Studio supports. Install Android Studio and import the project.
-  Latest Android SDK: set `ANDROID_HOME` environment variable to the path to Android SDK
+- Python 3.6+. For Windows only, install Colorama with `pip install colorama` in admin shell.
-  Android NDK: Install NDK along with SDK (`$ANDROID_HOME/ndk-bundle`), or optionally specify a custom path `ANDROID_NDK_HOME`
+- Use the JDK bundled in Android Studio:
-  (Windows Only) Python package Colorama: Install with `pip install colorama`, used for ANSI color codes
+	- macOS: `export JAVA_HOME="/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home"`
 	- Linux: `export PATH="/path/to/androidstudio/jre/bin:$PATH"`
 	- Windows: Add `C:\Path\To\Android Studio\jre\bin` to environment variable `PATH`
 - Set environment variable `ANDROID_HOME` to the SDK folder
 - Download / clone [FrankeNDK](https://github.com/topjohnwu/FrankeNDK) and set environment variable `ANDROID_NDK_HOME` to the folder
 -  Set configurations in `config.prop`. A sample file `config.prop.sample` is provided.
 -  Run `build.py` to see help messages. For each supported actions, use `-h` to access help (e.g. `./build.py all -h`)
 -  By default, the script build everything in debug mode. If you want to build Magisk Manager in release mode (with the `-r, --release` flag), you need a Java Keystore (only `JKS` format is supported) to sign APKs and zips. For more information, check [Google's Documentation](https://developer.android.com/studio/publish/app-signing.html#generate-key).
-## Building Notes and Instructions
+## Translation Contributions
 -  Clone sources with submodules: `git clone --recurse-submodules https://github.com/topjohnwu/Magisk.git`
 -  Building is supported on macOS, Linux, and Windows. Official releases are built and tested with [FrankeNDK](https://github.com/topjohnwu/FrankeNDK); point `ANDROID_NDK_HOME` to FrankeNDK if you want to use it for compiling.
 -  Set configurations in `config.prop`. A sample file `config.prop.sample` is provided as an example.
 -  Run `build.py` with argument `-h` to see the built-in help message. The `-h` option also works for each supported actions, e.g. `./build.py binary -h`
 -  By default, `build.py` build binaries and Magisk Manager in debug mode. If you want to build Magisk Manager in release mode (via the `-r, --release` flag), you need a Java Keystore file `release-key.jks` (only `JKS` format is supported) to sign APKs and zips. For more information, check out [Google's Official Documentation](https://developer.android.com/studio/publish/app-signing.html#signing-manually).
 ## Translations
 Default string resources for Magisk Manager and its stub APK are located here:
--- a/docs/README.md
+++ b/docs/README.md
@ -1,10 +1,8 @@
 # Magisk Documentation
-(Updated on 2020.2.1)
+(Updated on 2020.3.23)
- [Installation](install.md)
+- [Installation Instructions](install.md)
- [Tutorials](tutorials.md)
+- [OTA Upgrade Guides](ota.md)
    - [OTA Installation](tutorials.md#ota-installation)
    - [Best Practices for MagiskHide](tutorials.md#best-practices-for-magiskhide)
 The following sections are for developers
--- a/docs/images/flashfire.png
+++ b/docs/images/flashfire.png
--- a/docs/images/hide_manager.png
+++ b/docs/images/hide_manager.png
--- a/docs/images/logo.png
+++ b/docs/images/logo.png
--- a/docs/images/safetynet.png
+++ b/docs/images/safetynet.png
--- a/docs/ota.md
+++ b/docs/ota.md
@ -0,0 +1,37 @@
 ## OTA Upgrade Guides
 Magisk does not modify most read-only partitions, which means applying official OTAs is much simpler. Here are the tutorials for several different kind of devices to apply OTAs and preserve Magisk after the installation (if possible). This is just a general guide as procedures for each device may vary.
 **NOTE: In order to apply OTAs, you HAVE to make sure you haven't modified and read-only partitons yourself (such as `/system` or `/vendor`) in any way. Even remounting the partition to rw will tamper block verification!!**
 ### Prerequisites
 - Please disable *Automatic system updates* in developer options, so it won't install OTAs without your acknowledgement.
 <p align="center"><img src="images/disable_auto_ota.png" width="250"/></p>
 - When an OTA is available, first go to (Magisk Manager → Uninstall → Restore Images). **Do not reboot or you will have Magisk uninstalled.** This will restore partitions modified by Magisk back to stock from backups made at install in order to pass pre-OTA block verifications. **This step is required before doing any of the following steps written below!**
 <p align="center"><img src="images/restore_img.png" width="300"/></p>
 ### Devices with A/B Partitions
 It is possible to have the OTA installed to the inactive slot and have Magisk Manager install Magisk onto the updated partitions. The out-of-the-box OTA installation works seamlessly and Magisk can be preserved after the installation.
 - After restoring stock images, apply OTAs as you normally would (Settings → System → System Update).
 - Wait for the installation to be fully done (both step 1 and step 2 of the OTA), **do not press the "Restart now" or "Reboot" button!** Instead, go to (Magisk Manager → Install → Install to Inactive Slot) to install Magisk to the updated slot.
 <p align="center"><img src="images/ota_done.png" width="250"/> <img src="images/install_inactive_slot.png" width="250"/></p>
 - After installation is done, press the reboot button in Magisk Manager. Under-the-hood Magisk Manager forces your device to switch to the updated slot, bypassing any possible post-OTA verifications.
 <p align="center"><img src="images/manager_reboot.png" width="250"/></p>
 ### "Non A/B" Devices
 Unfortunately, there are no real good ways to apply OTAs on these devices. The following tutorial will not preserve Magisk; you will have to manually re-root your device after the upgrade, and this will require access to a computer. These are simply "best practices".
 - To properly install OTAs, you must have your stock recovery installed on your device. If you have custom recovery installed, you can restore it from your previous backup, or dumps found online, or factory images provided by OEMs.
 If you decide to start by installing Magisk without touching your recovery partition, you have a few choices, either way you will end up with a Magisk rooted device, but recovery remains stock untouched:
    - If supported, use `fastboot boot <recovery_img>` to boot the custom recovery and install Magisk.
    - If you have a copy of your stock image dump, install Magisk by using Magisk Manager's "patch images" feature
 - Once you restored back to stock recovery and other images, download the OTA. Optionally, once you have downloaded the OTA update zip, find a way to extract the zip (as it usually involved root)
 - Apply the OTA and reboot your device. This will use the official stock OTA installation mechanism of your device to upgrade your system.
 - Once it's done you will be left with an upgraded, 100% stock, un-rooted device. You will have to manually flash Magisk back. Consider using the methods stated in step 1. to flash Magisk without touching the recovery partition if you want to receive stock OTAs frequently.
--- a/docs/tutorials.md
+++ b/docs/tutorials.md
@ -1,84 +0,0 @@
 # Tutorials
 ## OTA Installation
 Magisk does modifications systemless-ly, which means applying official OTAs is much simpler. Here I provide a few tutorials for several different kind of devices to apply OTAs and preserve Magisk after the installation if possible.
 **NOTE: In order to apply OTAs, you HAVE to make sure you haven't modified `/system` (and `/vendor` if available) in any way. Even remounting the partition to rw will tamper block verification!!**
 ### Prerequisites
 - Please disable *Automatic system updates* in developer options, so it won't install OTAs without your acknowledgement.
 <p align="center"><img src="images/disable_auto_ota.png" width="250"/></p>
 - When an OTA is available, first go to (Magisk Manager → Uninstall → Restore Images). **Do not reboot or you will have Magisk uninstalled.** This will restore your boot (and dtbo if applicable) back to 100% untouched stock images in order to pass pre-OTA block verifications. **This step is required before doing any of the following steps written below!**
 <p align="center"><img src="images/restore_img.png" width="300"/></p>
 ### Devices with A/B Partitions
 Due to the fact that these devices have two separate partitions, it is possible to have the OTA installed to the inactive slot and have Magisk Manager to install Magisk onto the updated partition. The out-of-the-box OTA installation works seamlessly and Magisk can be preserved after the installation.
 - After restoring stock boot image, apply OTAs as you normally would (Settings → System → System Update).
 - Wait for the installation to be fully done (both step 1 and step 2 of the OTA), **do not press the "Restart now" or "Reboot" button!** Instead, go to (Magisk Manager → Install → Install to Inactive Slot) and install Magisk to the slot that the OTA engine just updated.
 <p align="center"><img src="images/ota_done.png" width="250"/> <img src="images/install_inactive_slot.png" width="250"/></p>
 - After installation is done, press the reboot button in Magisk Manager. Under-the-hood Magisk Manager forces your device to switch to the updated slot, bypassing any possible post-OTA verifications.
 <p align="center"><img src="images/manager_reboot.png" width="250"/></p>
 - After the reboot, your device should be fully updated, and most importantly, Magisk is still installed to the updated system!
 ### Devices with FlashFire Support
 (If you are using a device with A/B partitions, I **strongly** recommend you to use the method stated above since it uses the stock OTA installation mechanism and will always work under any circumstances)
 The [FlashFire](https://play.google.com/store/apps/details?id=eu.chainfire.flash) app developed by Chainfire is a great app to apply OTAs and preserve root at the same time. However, there is a very high chance that it does not support your device/system combination, and unfortunately the app is no longer maintained by Chainfire so no additonal compatibility would be added in the future.
 - After restoring the stock boot image, download the OTA (Settings → System → System Updates), **do not press reboot to install.**
 - Open FlashFire, it should detect your OTA zip. Select OK in the popup dialog to let it do its setup.
 - Please use the options shown in the screenshot below. The key point is to disable EverRoot (or it will install SuperSU), and add a new action to flash Magisk zip **after** the OTA update.zip (the update.zip should be auto generated in the previous step).
 <p align="center"><img src="images/flashfire.png" width="250"/></p>
 - Press the big **Flash** button, after a few minutes it should reboot and updated with Magisk installed.
 ### "Non A/B" Devices - General Case
 Unfortunately, there are no real good ways to apply OTAs on these devices. The following tutorial will not preserve Magisk - you will have to manually re-root your device after the upgrade, and this will require PC access. This is a general "best practice".
 - To properly install OTAs, you must have your stock recovery installed on your device. If you have custom recovery installed, you can restore it from your previous backup, or dumps found online, or factory images provided by OEMs.
 If you decide to start by installing Magisk without touching your recovery partition, you have a few choices, either way you will end up with a Magisk rooted device, but recovery remains stock untouched:
    - If supported, use `fastboot boot <recovery_img>` to boot the custom recovery and install Magisk.
    - If you have a copy of your stock boot image dump, install Magisk by patching boot image via Magisk Manager, and manually flash it through download mode / fastboot mode / Odin.
 - Once your device has stock recovery and stock boot image restored, download the OTA. Optionally, once you have downloaded the OTA update zip, you can find a way to copy the zip out, since you are still rooted. Personally, I extract the stock boot image and recovery image from the OTA zip for future usage (to patch via Magisk Manager or restore stock recovery etc.)
 - Apply and reboot your device. This will use the official stock OTA installation mechanism of your device to upgrade your system.
 - Once it's done you will be left with an upgraded, 100% stock, un-rooted device. You will have to manually flash Magisk back. Consider using the methods stated in step 1. to flash Magisk without touching the recovery partition if you want to receive stock OTAs frequently.
 ## Best Practices for MagiskHide
 There are a lot of people confused about why their setup isn't bypassing detections as expected. Here are some of the best practices to maintain a proper environment for MagiskHide. The guidelines in the following is ordered in progression, you might not need to do everything all the way through, but you should have done previous steps before going on to the next step.
 Let's start with SafetyNet.
 - Check SafetyNet status by using Magisk Manager. Google had banned usage of old APIs, and many "SafetyNet Detection" apps might be outdated.
 - Start clean: my advice is always the easy route - **use stock ROMs**. If you prefer custom ROMs, choose stable, official builds from well-reputed teams.
 - If you cannot even pass **basicIntegrity**, there are some serious issues! Even though in theory Magisk Modules should be hidden by MagiskHide, some modules modify stuffs that MagiskHide is not sufficient. Please remove modules one by one and narrow down the problematic module(s). If it still doesn't pass, the ROM you're using is the problem.
 - If **basicIntegrity** passes but **ctsProfile** doesn't, you might be using a ROM that has never passed CTS (OEM betas, previews, China based ROMs etc.). Try out [MagiskHide Props Config](https://forum.xda-developers.com/apps/magisk/module-magiskhide-props-config-t3789228) from @Didgeridoohan and switch a known CTS-passing fingerprint from the massive list included in the module.
 At this point, SafetyNet should be fully passed. Let's change gears to notorious apps that detects all kinds of weird shit.
 <p align="center"><img src="images/safetynet.png" width="300"/></p>
 <p align="center">This is just so pleasing to look at, right?</p>
 - Add your target app to the MagiskHide list: go to the "MagiskHide" section in Magisk Manager, and check the app you want to hide. **Do NOT add a large number of apps to the list!** This behavior will not only very likely to break MagiskHide, **but also Magisk itself or even the whole system** (`magiskd` crashes, system bogged down etc.). Remember: only enable those you are SURE you needed!
 - Note that apps installed in adopted storage is currently unsupported to be added to the hide list.
 - Hide Magisk Manager: go to (Settings → Hide Magisk Manager) to repackage the app with a random package name.
 <p align="center"><img src="images/hide_manager.png" width="300"/></p>
 - Remove sensitive apps: after dealing with Magisk Manager, uninstall Xposed Installer, Lucky Patcher, other root managers, anything you think is suspicious.
 - Remove sensitive files: starting from Magisk Manager v5.9.0, `/sdcard/MagiskManager` is no longer used. Remove that specific folder if exists, and then remove any files and folders that have sensitive names (e.g. magisk, supersu, xposed etc.) in your internal storage. Yes, there are apps scanning through all your files, are you freaking out now?
 - Disable USB debugging (ADB): some apps does not allow your device to have usb debugging enabled. Disable it in developer options.
 - Disable developer options: it's just ridiculous at this point.
 - Uninstall Magisk Manager: this is the last thing you should try. Sometimes the hiding technique used in Magisk Manager is just not good enough (it is improving, like recently added code obfuscation), try uninstalling and see if it works. If it does, report to me and I will hack up a solution ASAP.