MarcoBuster/Magisk
1
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
topjohnwu 2019-02-03 23:37:38 -05:00
parent 6ee08b6717
commit dc91041edd
3 changed files with 169 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/README.md
View File

@ -1,6 +1,11 @@
# Magisk Documentations
(Updated on 2018.12.9)
(Updated on 2019.2.3)
- [Installation](install.md)
- [Prerequisite](install.md#prerequisite)
- [Custom Recovery](install.md#custom-recovery)
- [Boot Image Patching](install.md#boot-image-patching)
- [Huawei](install.md#huawei)
- [Tutorials](tutorials.md)
- [OTA Installation](tutorials.md#ota-installation)
- [Best Practices for MagiskHide](tutorials.md#best-practices-for-magiskhide)
@ -14,10 +19,10 @@ The followings are for developers
- [Magic Mount](details.md#magic-mount)
- [Simple Mount](details.md#simple-mount)
- [Miscellaneous](details.md#Miscellaneous)
- [Installation](install.md)
- [Systemless](install.md#systemless)
- [System Only](install.md#system-only)
- [Exploits](install.md#Exploits)
- [Deployment](deploy.md)
- [Systemless](deploy.md#systemless)
- [System Only](deploy.md#system-only)
- [Exploits](deploy.md#exploits)
- [Magisk Tools](tools.md)
- [Developer Guides](guides.md)
- [Scripts](guides.md#scripts)
@ -26,4 +31,3 @@ The followings are for developers
- [Submit Modules to Magisk-Modules-Repo](https://github.com/Magisk-Modules-Repo/submission)
- [Remove Files](guides.md#remove-files)
- [Remove Folders](guides.md#remove-folders)

114
docs/deploy.md Normal file
View File

@ -0,0 +1,114 @@
# Deployment
(Note: This is not a user tutorial for installing Magisk, this is an explaination of how Magisk can be installed, and a guide for developers to properly deploy Magisk in various different situations)
## Systemless
When a user flashes a Magisk zip in custom recoveries or have boot images patched in Magisk Manager, Magisk is installed in this way. This is the only officially supported method to install Magisk on a device. The systemless method installs Magisk into a boot image's ramdisk CPIO, sometimes require additional patches to the kernel.
With the introduction of `magiskinit`, the systemless installation process has become extremely simple as nearly all setup and patches are done at runtime after the device is booted up. Replacing `init` in `rootfs` with our own implementation is required for rooting system-as-root devices systemless-ly - that is why `magiskinit` was created in the first place.
Here are some background knowledge about system-as-root devices:
- No recovery partition. Recovery and system shares the same kernel in boot, and the ramdisk in the boot image is actually the recovery's ramdisk.
- The root folder (`/`) and `/system` are both stored in the system partition.
- When the device boots up, a bootloader will set flags in cmdline so the kernel can decide where to mount `rootfs`: if booting in recovery mode, mount `rootfs` from ramdisk; if not, mount `rootfs` from system with dm-verity enabled.
To install anything systemless-ly, our only choice is to install Magisk files into the ramdisk in boot image. The soultion used in Magisk is to patch the kernel to always boot as recovery mode regardlessly, and we do the `rootfs` construction and booting ourselves. For more details about how `magiskinit` works, check the **Pre-Init** section of [Magisk Booting Process](details.md#magisk-booting-process).
Here are the bare minimum commands to install Magisk into a stock boot image. Be aware that the actual Magisk installation is far more complicated, the following commands will work but should be treat as proof-of-concepts.
```
# Push 2 binaries, magiskboot and magiskinit to the device
# Assume the 2 binaries are in the current directory and
# both have executing permissions.
# The path to stock boot image, can be a file or an on-device block
BOOTIMAGE=<path to boot>
# First unpack the image
./magiskboot --unpack $BOOTIMAGE
# In normal cases, after unpacking you should get at least kernel and ramdisk.cpio
# Patch ramdisk
./magiskboot --cpio ramdisk.cpio \
"mkdir 000 .backup" \ # create a folder to store our init backup
"mv init .backup/init" \ # backup the original init
"add 750 init magiskinit" # replace init with magiskinit
# Patch kernel to always use ramdisk as rootfs
# You only need to do this on system-as-root devices
./magiskboot --hexpatch kernel \
736B69705F696E697472616D6673 \
77616E745F696E697472616D6673
# Repack the boot image
./magiskboot --repack $BOOTIMAGE
# The patched image should be located in new-boot.img
```
## System Only
WIP
```
# Currently not available
```
## Exploits
**(Note: Magisk could only be used as root)**
Occasionally, there would be exploits in certain devices that could lead to full fledged root. On modern Android, it is possible to use MagiskSU if you can gain a shell with the following conditions:
- Effective UID should be privileged (root, or `euid=0`)
- Have the ability to reload `sepolicy` (which 99.9% of the time means SELinux permissive)
Once you got a proper root shell, you should have `magiskinit` somewhere on the device. The basic idea is try to live patch `sepolicy` with `magiskpolicy`, and start `magiskd` with `magisk --daemon`. Here are some examples you could use as a reference.
If dm-verity is enforced (no system r/w allowed)
```
# Assume magiskinit is in current directory
# All commands are required to run on each reboot
# Live patch selinux
ln -s ./magiskinit magiskpolicy
./magiskpolicy --live --magisk "allow magisk * * *"
# Mount tmpfs to /sbin
mount -t tmpfs tmpfs /sbin
chmod 755 /sbin
chcon u:object_r:magisk_file:s0 /sbin
# Add files to /sbin
./magiskinit -x magisk /sbin/magisk
cp -a magiskpolicy /sbin
/sbin/magisk --install /sbin
# Launch magisk daemon
/sbin/magisk --daemon
# (Optional) switch back to enforced
setenforce 1
```
If dm-verity is not enforced (can modify system)
```
# Assume magiskinit is in current directory
# The following commands should only need to run once
# Mount system rw
mount -o rw,remount /system
# Add files to system
./magiskinit -x magisk /system/xbin/magisk
cp -a magiskinit /system/xbin
ln -s /system/xbin/magiskinit /system/xbin/magiskpolicy
/system/xbin/magisk --install /system/xbin
# The following commands should run on each reboot
/system/xbin/magiskpolicy --live --magisk "allow magisk * * *"
/system/xbin/magisk --daemon
```

151
docs/install.md
View File

@ -1,119 +1,58 @@
# Installation
(Note: This is not a user tutorial for installing Magisk, this is an explaination of how Magisk can be installed, and a guide for developers to properly deploy Magisk in various different situations)
If you already have Magisk installed, it is **strongly recommended to upgrade directly via Magisk Manager**.
The following tutorial is for first time users. For Huawei users, please check the specific section for more information.
## Systemless
When a user flashes a Magisk zip in custom recoveries or have boot images patched in Magisk Manager, Magisk is installed in this way. This is the only officially supported method to install Magisk on a device. The systemless method installs Magisk into a boot image's ramdisk CPIO, sometimes require additional patches to the kernel.
## Prerequisite
- 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
With the introduction of `magiskinit`, the systemless installation process has become extremely simple as nearly all setup and patches are done at runtime after the device is booted up. Replacing `init` in `rootfs` with our own implementation is required for rooting system-as-root devices systemless-ly - that is why `magiskinit` was created in the first place.
## Custom Recovery
If your device have custom recovery support, the easiest way is to install it through custom recoveries, such as TWRP.
Here are some background knowledge about system-as-root devices:
- 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
- No recovery partition. Recovery and system shares the same kernel in boot, and the ramdisk in the boot image is actually the recovery's ramdisk.
- The root folder (`/`) and `/system` are both stored in the system partition.
- When the device boots up, a bootloader will set flags in cmdline so the kernel can decide where to mount `rootfs`: if booting in recovery mode, mount `rootfs` from ramdisk; if not, mount `rootfs` from system with dm-verity enabled.
## Boot Image Patching
This is the "cool" way to install Magisk on your device. Either your device does not have proper custom recoveries, your device is using the A/B partition scheme and you don't want to mix recovery and boot images together, or you have other concerns (e.g. [OTA Installation](tutorials.md#ota-installation)), you should use this method instead.
To install anything systemless-ly, our only choice is to install Magisk files into the ramdisk in boot image. The soultion used in Magisk is to patch the kernel to always boot as recovery mode regardlessly, and we do the `rootfs` construction and booting ourselves. For more details about how `magiskinit` works, check the **Pre-Init** section of [Magisk Booting Process](details.md#magisk-booting-process).
In order to use this method, you are required to obtain a copy of the stock boot image, which can be found by extracting OEM provided factory images, or extracted from OTA update zips. If you are unable to obtain one yourself, someone on the Internet might share it somewhere. The following instructions will guide you through the process after you have the copy of boot image.
Here are the bare minimum commands to install Magisk into a stock boot image. Be aware that the actual Magisk installation is far more complicated, the following commands will work but should be treat as proof-of-concepts.
- Copy the boot image to your device
- Download and install the latest Magisk Manager
- If you're planning to flash the patched boot image through ODIN (Samsung only), go to **Settings > Update Settings > Patched Boot Output Format**, and select *.img.tar*, or else leave it as the default (*.img*)
- Press **Install > Install > Patch Boot Image File**, and select your stock boot image file
- Magisk Manager will install Magisk to your boot image, and store it in \
`[Internal Storage]/Download/patched_boot.img[.tar]`
- Copy the patched boot image from your device to your PC. If you can't find it via MTP, you can pull the file with ADB: \
`adb pull /sdcard/Download/patched_boot.img[.tar]`
- Flash the patched boot image to your device and reboot. Here is the command if using fastboot on most devices: \
`fastboot flash boot /path/to/patched_boot.img`
```
# Push 2 binaries, magiskboot and magiskinit to the device
## 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 does not have this partition. Depending on what EMUI version your device is running the instructions are slightly different. Even if you have switched to a custom ROM, you shall still know which version of EMUI you are running before switching.
# Assume the 2 binaries are in the current directory and
# both have executing permissions.
### 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 the 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!)
# The path to stock boot image, can be a file or an on-device block
BOOTIMAGE=<path to boot>
### EMUI 8
For EMUI 8 devices, your device have a partition named `ramdisk`, which will be where Magisk is going to be installed.
# First unpack the image
./magiskboot --unpack $BOOTIMAGE
- If you plan to use custom recoveries, simply follow the instructions for custom recovery above. \
Note that to install TWRP, you will first download the TWRP recovery image, and use \
`fastboot flash recovery_ramdisk /path/to/twrp.img` to install the custom recovery.
- 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 install the patched image back to your device, here is the fastboot command: \
`fastboot flash ramdisk /path/to/patched_boot.img`. \
Be aware you are flashing to `ramdisk`, not `boot`!
# In normal cases, after unpacking you should get at least kernel and ramdisk.cpio
### EMUI 9
For EMUI 9 devices, the `ramdisk` partition no longer exists. As a workaround, Magisk will be installed to the `recovery_ramdisk` partition. **This means that you HAVE TO boot to recovery every time you reboot. This also means that you CANNOT have Magisk and custom recoveries at the same time!** To boot to recovery, press **Power + Volume Up** when booting your device.
# Patch ramdisk
./magiskboot --cpio ramdisk.cpio \
"mkdir 000 .backup" \ # create a folder to store our init backup
"mv init .backup/init" \ # backup the original init
"add 750 init magiskinit" # replace init with magiskinit
# Patch kernel to always use ramdisk as rootfs
# You only need to do this on system-as-root devices
./magiskboot --hexpatch kernel \
736B69705F696E697472616D6673 \
77616E745F696E697472616D6673
# Repack the boot image
./magiskboot --repack $BOOTIMAGE
# The patched image should be located in new-boot.img
```
## System Only
**(Note 1: MagiskHide will never work with this installation method)**
**(Note 2: Current tools are not updated to support this yet)**
Installing Magisk to the system partition without patching boot images is only possible if your device is a system-as-root device. It is impossible on traditional devices since we could not patch `sepolicy` without modifying the boot image. The basic concept is the same as systemless, but we do the modifications directly to the root directory in the system image.
This could be useful for rooting Treble GSI system images with Magisk.
```
# Currently not available
```
## Exploits
**(Note: Magisk could only be used as root)**
Occasionally, there would be exploits in certain devices that could lead to full fledged root. On modern Android, it is possible to use MagiskSU if you can gain a shell with the following conditions:
- Effective UID should be privileged (root, or `euid=0`)
- Have the ability to reload `sepolicy` (which 99.9% of the time means SELinux permissive)
Once you got a proper root shell, you should have `magiskinit` somewhere on the device. The basic idea is try to live patch `sepolicy` with `magiskpolicy`, and start `magiskd` with `magisk --daemon`. Here are some examples you could use as a reference.
If dm-verity is enforced (no system r/w allowed)
```
# Assume magiskinit is in current directory
# All commands are required to run on each reboot
# Live patch selinux
ln -s ./magiskinit magiskpolicy
./magiskpolicy --live --magisk "allow magisk * * *"
# Mount tmpfs to /sbin
mount -t tmpfs tmpfs /sbin
chmod 755 /sbin
chcon u:object_r:magisk_file:s0 /sbin
# Add files to /sbin
./magiskinit -x magisk /sbin/magisk
cp -a magiskpolicy /sbin
/sbin/magisk --install /sbin
# Launch magisk daemon
/sbin/magisk --daemon
# (Optional) switch back to enforced
setenforce 1
```
If dm-verity is not enforced (can modify system)
```
# Assume magiskinit is in current directory
# The following commands should only need to run once
# Mount system rw
mount -o rw,remount /system
# Add files to system
./magiskinit -x magisk /system/xbin/magisk
cp -a magiskinit /system/xbin
ln -s /system/xbin/magiskinit /system/xbin/magiskpolicy
/system/xbin/magisk --install /system/xbin
# The following commands should run on each reboot
/system/xbin/magiskpolicy --live --magisk "allow magisk * * *"
/system/xbin/magisk --daemon
```
- If you plan to use custom recoveries, simply follow the instructions for custom recovery above. \
Note that to install TWRP, you will first download the TWRP recovery image, and use \
`fastboot flash recovery_ramdisk /path/to/twrp.img` to install the custom recovery. \
**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 install the patched image back to your device, here is the fastboot command: \
`fastboot flash recovery_ramdisk /path/to/patched_boot.img`. \
Be aware you are flashing to `recovery_ramdisk`, not `boot` nor `ramdisk`!