TheArchive/Magisk
1
0
Fork 0
mirror of https://github.com/topjohnwu/Magisk.git synced 2024-11-23 10:05:23 +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
resetprop -> 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
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`.
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 tool also supports a variaty of CPIO operations that can modify CPIO archives without any extracting and repacking involved.
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.
```
Usage: ./magiskboot <action> [args...]
Usage: magiskboot <action> [args...]
Supported actions:
--unpack <bootimg>
Unpack <bootimg> to kernel, ramdisk.cpio, and if available, second, dtb,
and extra into the current directory. Return values:
0:valid 1:error 2:chromeos 3:ELF32 4:ELF64
unpack [-h] <bootimg>
Unpack <bootimg> to, if available, kernel, kernel_dtb, ramdisk.cpio,
second, dtb, extra, and recovery_dtbo into current directory.
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 kernel, ramdisk.cpio[.ext], second, dtb... from current directory
repack <origbootimg> [outbootimg]
Repack boot image components from current directory
to [outbootimg], or new-boot.img if not specified.
It will compress ramdisk.cpio with the same method used in <origbootimg>,
or attempt to find ramdisk.cpio.[ext], and repack directly with the
compressed ramdisk file
It will compress ramdisk.cpio and kernel with the same method in
<origbootimg> if the file provided is not already compressed.
--hexpatch <file> <hexpattern1> <hexpattern2>
hexpatch <file> <hexpattern1> <hexpattern2>
Search <hexpattern1> in <file>, and replace with <hexpattern2>
--cpio <incpio> [commands...]
cpio <incpio> [commands...]
Do cpio commands to <incpio> (modifications are done directly)
Each command is a single argument, use quotes if necessary
Supported commands:
exists ENTRY
Return 0 if ENTRY exists, else return 1
rm [-r] ENTRY
Remove ENTRY, specify [-r] to remove recursively
mkdir MODE ENTRY
@ -65,20 +66,14 @@ Supported actions:
0:stock 1:Magisk 2:unsupported (phh, SuperSU, Xposed)
patch KEEPVERITY KEEPFORCEENCRYPT
Ramdisk patches. KEEP**** are boolean values
backup ORIG [SHA1]
backup ORIG
Create ramdisk backups from ORIG
SHA1 of stock boot image is optional
restore
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
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)
Supported commands:
dump
@ -90,25 +85,25 @@ Supported actions:
patch
Search for fstab and remove verity/avb
--compress[=method] <infile> [outfile]
compress[=method] <infile> [outfile]
Compress <infile> with [method] (default: gzip), optionally to [outfile]
<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]
<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>
--cleanup
cleanup
Cleanup the current working directory
```
### 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
(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...]
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
--magisk inject built-in rules for a minimal
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
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;
multiple policy statements can be provided in a single command
The statements has a format of "<action> [args...]"
Use '*' in args to represent every possible match.
Collections wrapped in curly brackets can also be used as args.
The statements has a format of "<rule_name> [args...]"
Multiple types and permissions can be grouped into collections
wrapped in curly brackets.
'*' represents a collection containing all valid matches.
Supported policy statements:
Type 1:
"<action> source-class target-class permission-class permission"
Action: allow, deny, auditallow, auditdeny
"<rule_name> source_type target_type class perm_set"
Rules: allow, deny, auditallow, dontaudit
Type 2:
"<action> source-class target-class permission-class ioctl range"
Action: allowxperm, auditallowxperm, dontauditxperm
"<rule_name> source_type target_type class operation xperm_set"
Rules: allowxperm, auditallowxperm, dontauditxperm
* The only supported operation is ioctl
* The only supported xperm_set format is range ([low-high])
Type 3:
"<action> class"
Action: create, permissive, enforcing
"<rule_name> class"
Rules: create, permissive, enforcing
Type 4:
"attradd class attribute"
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:
- typetrans does not support the all match '*' syntax
- permission-class cannot be collections
- source-class and target-class can also be attributes
* Type 4 - 6 does not support collections
* Object classes cannot be collections
* 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:
allow source1 target1 permission-class { all-permissions }
allow source1 target2 permission-class { all-permissions }
allow source2 target1 permission-class { all-permissions }
allow source2 target2 permission-class { all-permissions }
allow s1 t1 class { all permissions }
allow s1 t2 class { all permissions }
allow s2 t1 class { all permissions }
allow s2 t2 class { all permissions }
```
### 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]...]
@ -187,18 +191,21 @@ Options:
-v print running daemon version
-V print running daemon version code
--list list all available applets
--install [SOURCE] DIR symlink all applets to DIR. SOURCE is optional
--daemon manually start magisk daemon
--[init trigger] start service for init trigger
Advanced Options (Internal APIs):
--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 SRC DEST clone SRC to DEST
--sqlite SQL exec SQL to Magisk database
Supported init triggers:
startup, post-fs-data, service
post-fs-data, service, boot-complete
Supported applets:
magisk, su, resetprop, magiskhide, imgtool
magisk, su, resetprop, magiskhide
```
### 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.
```
Usage: magiskhide [--options [arguments...] ]
Usage: magiskhide [--option [arguments...] ]
Options:
--status Return the status of magiskhide
--enable Start magiskhide
--disable Stop magiskhide
--add PROCESS Add PROCESS to the hide list
--rm PROCESS Remove PROCESS from the hide list
--ls Print out 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
--add PKG [PROC] Add a new target to the hide list
--rm PKG [PROC] Remove from the hide list
--ls List the current hide list
```

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

@ -19,12 +19,12 @@ static void usage(char *arg0) {
"\n"
"Supported actions:\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"
" If '-h' is provided, it will dump header info to 'header',\n"
" which will be parsed when repacking.\n"
" Return values:\n"
" 0:valid 1:error 2:chromeos 3:ELF32 4:ELF64\n"
" 0:valid 1:error 2:chromeos\n"
"\n"
" repack <origbootimg> [outbootimg]\n"
" Repack boot image components from current directory\n"