diff --git a/docs/README.MD b/docs/README.md similarity index 88% rename from docs/README.MD rename to docs/README.md index 19156087a..a11998c86 100644 --- a/docs/README.MD +++ b/docs/README.md @@ -1,8 +1,9 @@ # Magisk Documentations (Updated on 2018.10.15) -- [User Tutorials](tutorials.md) +- [Tutorials](tutorials.md) - [OTA Installation](tutorials.md#ota-installation) + - [Best Practices for MagiskHide](tutorials.md#best-practices-for-magiskhide) The following are for developers diff --git a/docs/details.md b/docs/details.md index 258d085e8..48139385f 100644 --- a/docs/details.md +++ b/docs/details.md @@ -1,3 +1,4 @@ +# Magisk Details ## File Structure ### Paths in "sbin tmpfs overlay" sbin tmpfs overlay is the key to hiding Magisk from detection. All Magisk binaries, applets, mirrors, mountpoints, loop devices, and other trivial stuffs are all located in the `tmpfs` mounted on `/sbin`. MagiskHide can just simply unmount `/sbin` and the bind mounts into `/system` and `/vendor` to hide all modifications easily. diff --git a/docs/guides.md b/docs/guides.md index 96f0d22dd..85f35fcce 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -1,3 +1,4 @@ +# Developer Guides ## Scripts In Magisk, you can run boot scripts in 2 different modes: **post-fs-data** and **late_start service** mode. diff --git a/docs/images/beta_channel.png b/docs/images/beta_channel.png new file mode 100644 index 000000000..21b9e1fa4 Binary files /dev/null and b/docs/images/beta_channel.png differ diff --git a/docs/images/core_only.png b/docs/images/core_only.png new file mode 100644 index 000000000..899fefbbe Binary files /dev/null and b/docs/images/core_only.png differ diff --git a/docs/images/disable_auto_ota.png b/docs/images/disable_auto_ota.png index 57d51ae7f..f7499a751 100644 Binary files a/docs/images/disable_auto_ota.png and b/docs/images/disable_auto_ota.png differ diff --git a/docs/images/flashfire.png b/docs/images/flashfire.png index 62e31151c..d19029048 100644 Binary files a/docs/images/flashfire.png and b/docs/images/flashfire.png differ diff --git a/docs/images/hide_manager.png b/docs/images/hide_manager.png new file mode 100644 index 000000000..2c3ae9e31 Binary files /dev/null and b/docs/images/hide_manager.png differ diff --git a/docs/images/install_inactive_slot.png b/docs/images/install_inactive_slot.png index 23193a6f9..fd0e1e88f 100644 Binary files a/docs/images/install_inactive_slot.png and b/docs/images/install_inactive_slot.png differ diff --git a/docs/images/manager_reboot.png b/docs/images/manager_reboot.png index 074780ebf..d1406247b 100644 Binary files a/docs/images/manager_reboot.png and b/docs/images/manager_reboot.png differ diff --git a/docs/images/ota_done.png b/docs/images/ota_done.png index 4529285dd..39de0b71c 100644 Binary files a/docs/images/ota_done.png and b/docs/images/ota_done.png differ diff --git a/docs/images/restore_img.png b/docs/images/restore_img.png index c400a697c..a62c7040d 100644 Binary files a/docs/images/restore_img.png and b/docs/images/restore_img.png differ diff --git a/docs/images/safetynet.png b/docs/images/safetynet.png new file mode 100644 index 000000000..51bce3dd9 Binary files /dev/null and b/docs/images/safetynet.png differ diff --git a/docs/tools.md b/docs/tools.md index 5637188f5..98edb18f2 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -1,4 +1,4 @@ -## Magisk Tools +# Magisk Tools Magisk comes with a huge collections of tools for installation, daemons, and utilities for developers. This documentation covers the 3 binaries and all included applets. The binaries and applets are shown below: ``` diff --git a/docs/tutorials.md b/docs/tutorials.md index 99b72323b..e868fa3e7 100644 --- a/docs/tutorials.md +++ b/docs/tutorials.md @@ -1,4 +1,4 @@ -# User Tutorials +# 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. @@ -8,40 +8,86 @@ Magisk does modifications systemless-ly, which means applying official OTAs is m **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 -1. Please disable *Automatic system updates* in developer options, so it won't install OTAs without your acknowledgement. - -1. 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!** - +- Please disable *Automatic system updates* in developer options, so it won't install OTAs without your acknowledgement. + +

+ +- 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!** + +

### 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. -1. After restoring stock boot image, apply OTAs as you normally would (Settings → System → System Update). -1. Wait for the installation to be fully done (both step 1 and step 2 of the OTA), **do not press the restart button!!** Instead, go to (Magisk Manager → Install → Install to Inactive Slot) and install Magisk to the slot that the OTA engine just updated. - -1. 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. - -1. After the reboot, your device should be fully updated, and most importantly, Magisk is still installed to the updated system! +- 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. + +

+ +- 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. + +

+ +- 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. -1. After restoring the stock boot image, download the OTA (Settings → System → System Updates), **do not press reboot to install.** -1. Open FlashFire, it should detect your OTA zip. Select OK in the popup dialog to let it do its setup. -1. 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). - -1. Press the big **Flash** button, after a few minutes it should reboot and updated with Magisk installed. +- 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). + +

+ +- Press the big **Flash** button, after a few minutes it should reboot and updated with Magisk installed. ### Legacy "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". -1. 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. +- 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 ` to boot the custom recovery and install Magisk. + - If supported, use `fastboot boot ` 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. -1. 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.) -1. Apply and reboot your device. This will use the official stock OTA installation mechanism of your device to upgrade your system. -1. 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. +- 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. + +If you've followed all practices below and still cannot succeed, consider switching to the beta channel as new MagiskHide upgrades might have not come to the stable channel yet. + +

+

Settings → Update Settings → Update Channel

+ +Let's start with SafetyNet. + +- Check SafetyNet status with Magisk Manager. Google banned the usage of old APIs, and many "SafetyNet Detection" apps you used were never updated and thus cannot provide correct information. **Trust the SafetyNet check included in Magisk Manager!** +- 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 can be hidden by MagiskHide, you should first try enabling *Core-Only Mode* and see if it makes any difference. If it still doesn't pass, the ROM you're using is the problem. If it passes, experiment and narrow down the problematic module(s). + +

+ +- 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. You will be very surprised by the results! + +At this point, SafetyNet should be fully passed. Let's change gears to notorious apps that detects all kinds of weird shit. + +

+

This is just so pleasing to look at, right?

+ +- 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 abuse MagiskHide!** I've seen some paranoid people adding *a lot* of unnecessary apps to the list. This behavior is very likely to not only break MagiskHide, **but also Magisk itself or even the whole system** (`magiskd`/`magisklogd` crashes, system bogged down). Remember: with the current MagiskHide implementation, **each additional hide target comes with a large cost**; only enable those you are SURE you needed! +- Hide Magisk Manager: go to (Settings → Hide Magisk Manager) to repackage the app with a random package name. + +

+ +- 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. + + +