TheArchive/Magisk
1
0
Fork 0
mirror of https://github.com/topjohnwu/Magisk.git synced 2024-11-23 18:15:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update tools docs

Browse Source
This commit is contained in:
topjohnwu 2019-03-28 04:54:06 -04:00
parent 66eb1078fe
commit e784212283
2 changed files with 74 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
docs/tools.md
View File

@ -10,43 +10,44 @@ magisk /* binary */
magiskhide -> magisk magiskhide -> magisk
resetprop -> magisk resetprop -> magisk
su -> magisk su -> magisk
imgtool -> magisk
``` ```
Note: The Magisk zip you download only contains `magiskboot` and `magiskinit`. The binary `magisk` is compressed and embedded into `magiskinit`. Push `magiskinit` to your device and run `./magiskinit -x magisk <path>` to extract `magisk` out of the binary. Note: The Magisk zip you download only contains `magiskboot`, `magiskinit`, and `magiskinit64`. The binary `magisk` is compressed and embedded into `magiskinit(64)`. Push `magiskinit(64)` to your device and run `./magiskinit(64) -x magisk <path>` to extract `magisk` out of the binary.
### magiskboot ### magiskboot
A tool to unpack / repack boot images, parse / patch / extract cpio, patch dtb, hex patch binaries, and compress / decompress files with multiple algorithms. A tool to unpack / repack boot images, parse / patch / extract cpio, patch dtb, hex patch binaries, and compress / decompress files with multiple algorithms.
`magiskboot` natively supports (which means it does not rely on external tools) common compression formats including `gzip`, `lz4`, `lz4_legacy` ([only used on LG](https://events.static.linuxfound.org/sites/events/files/lcjpcojp13_klee.pdf)), `lzma`, `xz`, and `bzip2`. `magiskboot` natively supports (which means it does not rely on external tools) common compression formats including `gzip`, `lz4`, `lz4_legacy` ([only used on LG](https://events.static.linuxfound.org/sites/events/files/lcjpcojp13_klee.pdf)), `lzma`, `xz`, and `bzip2`.
The concept of `magiskboot` is to make boot image modification much simpler. For unpacking, it parses the header and all sections in the image (kernel, ramdisk, second, dtb, extra), detect compression format used in each section, and decompress while extraction. Each extracted sections are raw data, ready for direct modification. For repacking, the original boot image is required so the original headers can be used, changing only the necessary entries such as section sizes and checksum, and finally compress each sections back with the original format. The concept of `magiskboot` is to make boot image modification simpler. For unpacking, it parses the header and extracts all sections in the image, decompressing on-the-fly if compression is detected in any sections. For repacking, the original boot image is required so the original headers can be used, changing only the necessary entries such as section sizes and checksum. All sections will be compressed back to the original format if required. The tool also supports many CPIO and DTB operations.
The tool also supports a variaty of CPIO operations that can modify CPIO archives without any extracting and repacking involved.
``` ```
Usage: ./magiskboot <action> [args...] Usage: magiskboot <action> [args...]
Supported actions: Supported actions:
--unpack <bootimg> unpack [-h] <bootimg>
Unpack <bootimg> to kernel, ramdisk.cpio, and if available, second, dtb, Unpack <bootimg> to, if available, kernel, kernel_dtb, ramdisk.cpio,
and extra into the current directory. Return values: second, dtb, extra, and recovery_dtbo into current directory.
0:valid 1:error 2:chromeos 3:ELF32 4:ELF64 If '-h' is provided, it will dump header info to 'header',
which will be parsed when repacking.
Return values:
0:valid 1:error 2:chromeos
--repack <origbootimg> [outbootimg] repack <origbootimg> [outbootimg]
Repack kernel, ramdisk.cpio[.ext], second, dtb... from current directory Repack boot image components from current directory
to [outbootimg], or new-boot.img if not specified. to [outbootimg], or new-boot.img if not specified.
It will compress ramdisk.cpio with the same method used in <origbootimg>, It will compress ramdisk.cpio and kernel with the same method in
or attempt to find ramdisk.cpio.[ext], and repack directly with the <origbootimg> if the file provided is not already compressed.
compressed ramdisk file
--hexpatch <file> <hexpattern1> <hexpattern2> hexpatch <file> <hexpattern1> <hexpattern2>
Search <hexpattern1> in <file>, and replace with <hexpattern2> Search <hexpattern1> in <file>, and replace with <hexpattern2>
--cpio <incpio> [commands...] cpio <incpio> [commands...]
Do cpio commands to <incpio> (modifications are done directly) Do cpio commands to <incpio> (modifications are done directly)
Each command is a single argument, use quotes if necessary Each command is a single argument, use quotes if necessary
Supported commands: Supported commands:
exists ENTRY
Return 0 if ENTRY exists, else return 1
rm [-r] ENTRY rm [-r] ENTRY
Remove ENTRY, specify [-r] to remove recursively Remove ENTRY, specify [-r] to remove recursively
mkdir MODE ENTRY mkdir MODE ENTRY
@ -65,20 +66,14 @@ Supported actions:
0:stock 1:Magisk 2:unsupported (phh, SuperSU, Xposed) 0:stock 1:Magisk 2:unsupported (phh, SuperSU, Xposed)
patch KEEPVERITY KEEPFORCEENCRYPT patch KEEPVERITY KEEPFORCEENCRYPT
Ramdisk patches. KEEP**** are boolean values Ramdisk patches. KEEP**** are boolean values
backup ORIG [SHA1] backup ORIG
Create ramdisk backups from ORIG Create ramdisk backups from ORIG
SHA1 of stock boot image is optional
restore restore
Restore ramdisk from ramdisk backup stored within incpio Restore ramdisk from ramdisk backup stored within incpio
magisk ORIG KEEPVERITY KEEPFORCEENCRYPT [SHA1]
Do Magisk patches and backups all in one step
Create ramdisk backups from ORIG
KEEP**** are boolean values
SHA1 of stock boot image is optional
sha1 sha1
Print stock boot SHA1 if previously stored Print stock boot SHA1 if previously backed up in ramdisk
--dtb-<cmd> <dtb> dtb-<cmd> <dtb>
Do dtb related cmds to <dtb> (modifications are done directly) Do dtb related cmds to <dtb> (modifications are done directly)
Supported commands: Supported commands:
dump dump
@ -90,25 +85,25 @@ Supported actions:
patch patch
Search for fstab and remove verity/avb Search for fstab and remove verity/avb
--compress[=method] <infile> [outfile] compress[=method] <infile> [outfile]
Compress <infile> with [method] (default: gzip), optionally to [outfile] Compress <infile> with [method] (default: gzip), optionally to [outfile]
<infile>/[outfile] can be '-' to be STDIN/STDOUT <infile>/[outfile] can be '-' to be STDIN/STDOUT
Supported methods: gzip xz lzma bzip2 lz4 lz4_legacy Supported methods: bzip2 gzip lz4 lz4_legacy lzma xz
--decompress <infile> [outfile] decompress <infile> [outfile]
Detect method and decompress <infile>, optionally to [outfile] Detect method and decompress <infile>, optionally to [outfile]
<infile>/[outfile] can be '-' to be STDIN/STDOUT <infile>/[outfile] can be '-' to be STDIN/STDOUT
Supported methods: gzip xz lzma bzip2 lz4 lz4_legacy Supported methods: bzip2 gzip lz4 lz4_legacy lzma xz
--sha1 <file> sha1 <file>
Print the SHA1 checksum for <file> Print the SHA1 checksum for <file>
--cleanup cleanup
Cleanup the current working directory Cleanup the current working directory
``` ```
### magiskinit ### magiskinit
This binary will replace `init` in the ramdisk of a Magisk patched boot image. It is required for supporting devices using system as root (most A/B devices, plus some odd-balls like Huawei EMUI 9), but the tool is extended to support all traditional devices so the same installation setup could be used on all devices. More details can be found in the **Pre-Init** section in [Magisk Booting Process](details.md#magisk-booting-process). This binary will replace `init` in the ramdisk of a Magisk patched boot image. It is originally created for supporting devices using system-as-root, but the tool is extended to support all devices and became a crucial part of Magisk. More details can be found in the **Pre-Init** section in [Magisk Booting Process](details.md#magisk-booting-process).
### magiskpolicy ### magiskpolicy
(This tool is aliased to `supolicy` for compatibility with SuperSU's sepolicy tool) (This tool is aliased to `supolicy` for compatibility with SuperSU's sepolicy tool)
@ -121,13 +116,15 @@ All processes spawned from the Magisk daemon, including root shells and all its
Usage: magiskpolicy [--options...] [policy statements...] Usage: magiskpolicy [--options...] [policy statements...]
Options: Options:
--help show help message for policy statements
--load FILE load policies from FILE
--load-split load from preloaded sepolicy or compile
split policies
--compile-split compile split cil policies
--save FILE save policies to FILE
--live directly apply sepolicy live --live directly apply sepolicy live
--magisk inject built-in rules for a minimal --magisk inject built-in rules for a minimal
Magisk selinux environment Magisk selinux environment
--load FILE load policies from FILE
--compile-split compile and load split cil policies
from system and vendor just like init
--save FILE save policies to FILE
If neither --load or --compile-split is specified, it will load If neither --load or --compile-split is specified, it will load
from current live policies (/sys/fs/selinux/policy) from current live policies (/sys/fs/selinux/policy)
@ -136,47 +133,54 @@ One policy statement should be treated as one parameter;
this means a full policy statement should be enclosed in quotes; this means a full policy statement should be enclosed in quotes;
multiple policy statements can be provided in a single command multiple policy statements can be provided in a single command
The statements has a format of "<action> [args...]" The statements has a format of "<rule_name> [args...]"
Use '*' in args to represent every possible match. Multiple types and permissions can be grouped into collections
Collections wrapped in curly brackets can also be used as args. wrapped in curly brackets.
'*' represents a collection containing all valid matches.
Supported policy statements: Supported policy statements:
Type 1: Type 1:
"<action> source-class target-class permission-class permission" "<rule_name> source_type target_type class perm_set"
Action: allow, deny, auditallow, auditdeny Rules: allow, deny, auditallow, dontaudit
Type 2: Type 2:
"<action> source-class target-class permission-class ioctl range" "<rule_name> source_type target_type class operation xperm_set"
Action: allowxperm, auditallowxperm, dontauditxperm Rules: allowxperm, auditallowxperm, dontauditxperm
* The only supported operation is ioctl
* The only supported xperm_set format is range ([low-high])
Type 3: Type 3:
"<action> class" "<rule_name> class"
Action: create, permissive, enforcing Rules: create, permissive, enforcing
Type 4: Type 4:
"attradd class attribute" "attradd class attribute"
Type 5: Type 5:
"typetrans source-class target-class permission-class default-class (optional: object-name)" "<rule_name> source_type target_type class default_type"
Rules: type_transition, type_change, type_member
Type 6:
"name_transition source_type target_type class default_type object_name"
Notes: Notes:
- typetrans does not support the all match '*' syntax * Type 4 - 6 does not support collections
- permission-class cannot be collections * Object classes cannot be collections
- source-class and target-class can also be attributes * source_type and target_type can also be attributes
Example: allow { source1 source2 } { target1 target2 } permission-class * Example: allow { s1 s2 } { t1 t2 } class *
Will be expanded to: Will be expanded to:
allow source1 target1 permission-class { all-permissions } allow s1 t1 class { all permissions }
allow source1 target2 permission-class { all-permissions } allow s1 t2 class { all permissions }
allow source2 target1 permission-class { all-permissions } allow s2 t1 class { all permissions }
allow source2 target2 permission-class { all-permissions } allow s2 t2 class { all permissions }
``` ```
### magisk ### magisk
When the magisk binary is called with the name `magisk`, it works as an utility tool with many helper functions and the entry points for `init` to start Magisk services. When the magisk binary is called with the name `magisk`, it works as an utility tool with many helper functions and the entry points for several Magisk services.
``` ```
Usage: magisk [applet [arguments]...] Usage: magisk [applet [arguments]...]
@ -187,18 +191,21 @@ Options:
-v print running daemon version -v print running daemon version
-V print running daemon version code -V print running daemon version code
--list list all available applets --list list all available applets
--install [SOURCE] DIR symlink all applets to DIR. SOURCE is optional
--daemon manually start magisk daemon --daemon manually start magisk daemon
--[init trigger] start service for init trigger --[init trigger] start service for init trigger
Advanced Options (Internal APIs):
--unlock-blocks set BLKROSET flag to OFF for all block devices --unlock-blocks set BLKROSET flag to OFF for all block devices
--restorecon fix selinux context on Magisk files and folders --restorecon restore selinux context on Magisk files
--clone-attr SRC DEST clone permission, owner, and selinux context --clone-attr SRC DEST clone permission, owner, and selinux context
--clone SRC DEST clone SRC to DEST
--sqlite SQL exec SQL to Magisk database
Supported init triggers: Supported init triggers:
startup, post-fs-data, service post-fs-data, service, boot-complete
Supported applets: Supported applets:
magisk, su, resetprop, magiskhide, imgtool magisk, su, resetprop, magiskhide
``` ```
### su ### su
@ -248,27 +255,13 @@ Flags:
An applet of `magisk`, the CLI to control MagiskHide. Use this tool to communicate with the daemon to change MagiskHide settings. An applet of `magisk`, the CLI to control MagiskHide. Use this tool to communicate with the daemon to change MagiskHide settings.
``` ```
Usage: magiskhide [--options [arguments...] ] Usage: magiskhide [--option [arguments...] ]
Options: Options:
--status Return the status of magiskhide
--enable Start magiskhide --enable Start magiskhide
--disable Stop magiskhide --disable Stop magiskhide
--add PROCESS Add PROCESS to the hide list --add PKG [PROC] Add a new target to the hide list
--rm PROCESS Remove PROCESS from the hide list --rm PKG [PROC] Remove from the hide list
--ls Print out the current hide list --ls List the current hide list
```
### imgtool
An applet of `magisk`, a collection of common commands used to create and manage `ext4` images.
```
Usage: imgtool <action> [args...]
Actions:
create IMG SIZE create ext4 image. SIZE is interpreted in MB
resize IMG SIZE resize ext4 image. SIZE is interpreted in MB
mount IMG PATH mount IMG to PATH and prints the loop device
umount PATH LOOP unmount PATH and delete LOOP device
merge SRC TGT merge SRC to TGT
trim IMG trim IMG to save space
``` ```

4
native/jni/magiskboot/main.cpp
View File

@ -19,12 +19,12 @@ static void usage(char *arg0) {
"\n" "\n"
"Supported actions:\n" "Supported actions:\n"
" unpack [-h] <bootimg>\n" " unpack [-h] <bootimg>\n"
" Unpack <bootimg> to, if available, kernel, ramdisk.cpio,\n" " Unpack <bootimg> to, if available, kernel, kernel_dtb, ramdisk.cpio,\n"
" second, dtb, extra, and recovery_dtbo into current directory.\n" " second, dtb, extra, and recovery_dtbo into current directory.\n"
" If '-h' is provided, it will dump header info to 'header',\n" " If '-h' is provided, it will dump header info to 'header',\n"
" which will be parsed when repacking.\n" " which will be parsed when repacking.\n"
" Return values:\n" " Return values:\n"
" 0:valid 1:error 2:chromeos 3:ELF32 4:ELF64\n" " 0:valid 1:error 2:chromeos\n"
"\n" "\n"
" repack <origbootimg> [outbootimg]\n" " repack <origbootimg> [outbootimg]\n"
" Repack boot image components from current directory\n" " Repack boot image components from current directory\n"