Magisk/docs/tools.md

283 lines
12 KiB
Markdown
Raw Normal View History

2018-10-16 00:04:51 +02:00
# Magisk Tools
2018-10-15 06:46:37 +02:00
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:
2018-01-08 15:33:55 +01:00
```
magiskboot /* binary */
magiskinit /* binary */
magiskpolicy -> magiskinit
2018-10-15 06:46:37 +02:00
supolicy -> magiskinit
2018-01-08 15:33:55 +01:00
magisk /* binary */
magiskhide -> magisk
resetprop -> magisk
su -> magisk
```
2019-03-28 09:54:06 +01:00
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.
2018-10-15 06:46:37 +02:00
2018-01-08 15:33:55 +01:00
### magiskboot
2018-10-15 06:46:37 +02:00
A tool to unpack / repack boot images, parse / patch / extract cpio, patch dtb, hex patch binaries, and compress / decompress files with multiple algorithms.
2018-01-08 15:33:55 +01:00
2018-10-15 06:46:37 +02:00
`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`.
2018-01-08 15:33:55 +01:00
2019-03-28 09:54:06 +01:00
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.
2018-01-08 15:33:55 +01:00
```
2019-03-28 09:54:06 +01:00
Usage: magiskboot <action> [args...]
2018-01-08 15:33:55 +01:00
Supported actions:
2020-01-02 06:46:59 +01:00
unpack [-n] [-h] <bootimg>
2019-03-28 09:54:06 +01:00
Unpack <bootimg> to, if available, kernel, kernel_dtb, ramdisk.cpio,
second, dtb, extra, and recovery_dtbo into current directory.
2020-01-02 06:46:59 +01:00
If '-n' is provided, it will not attempt to decompress kernel or
ramdisk.cpio from their original formats.
2019-03-28 09:54:06 +01:00
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
2019-09-19 11:00:29 +02:00
repack [-n] <origbootimg> [outbootimg]
2019-03-28 09:54:06 +01:00
Repack boot image components from current directory
2018-10-15 06:46:37 +02:00
to [outbootimg], or new-boot.img if not specified.
2019-09-19 11:00:29 +02:00
If '-n' is provided, it will not attempt to recompress ramdisk.cpio,
otherwise it will compress ramdisk.cpio and kernel with the same method
in <origbootimg> if the file provided is not already compressed.
2018-10-15 06:46:37 +02:00
2019-03-28 09:54:06 +01:00
hexpatch <file> <hexpattern1> <hexpattern2>
2018-10-15 06:46:37 +02:00
Search <hexpattern1> in <file>, and replace with <hexpattern2>
2019-03-28 09:54:06 +01:00
cpio <incpio> [commands...]
2020-10-03 06:47:47 +02:00
Do cpio commands to <incpio> (modifications are done in-place)
2020-01-02 06:46:59 +01:00
Each command is a single argument, add quotes for each command
2018-10-15 06:46:37 +02:00
Supported commands:
2019-03-28 09:54:06 +01:00
exists ENTRY
Return 0 if ENTRY exists, else return 1
2018-10-15 06:46:37 +02:00
rm [-r] ENTRY
Remove ENTRY, specify [-r] to remove recursively
mkdir MODE ENTRY
Create directory ENTRY in permissions MODE
ln TARGET ENTRY
Create a symlink to TARGET with the name ENTRY
mv SOURCE DEST
Move SOURCE to DEST
add MODE ENTRY INFILE
Add INFILE as ENTRY in permissions MODE; replaces ENTRY if exists
extract [ENTRY OUT]
Extract ENTRY to OUT, or extract all entries to current directory
test
Test the current cpio's patch status
Return values:
0:stock 1:Magisk 2:unsupported (phh, SuperSU, Xposed)
2020-01-02 06:46:59 +01:00
patch
2020-10-03 06:47:47 +02:00
Apply ramdisk patches
Configure with env variables: KEEPVERITY KEEPFORCEENCRYPT
2019-03-28 09:54:06 +01:00
backup ORIG
2018-10-15 06:46:37 +02:00
Create ramdisk backups from ORIG
restore
Restore ramdisk from ramdisk backup stored within incpio
sha1
2019-03-28 09:54:06 +01:00
Print stock boot SHA1 if previously backed up in ramdisk
2018-10-15 06:46:37 +02:00
2020-01-02 06:46:59 +01:00
dtb <input> <action> [args...]
Do dtb related actions to <input>
Supported actions:
print [-f]
Print all contents of dtb for debugging
Specify [-f] to only print fstab nodes
2020-10-03 06:47:47 +02:00
patch
2018-10-15 06:46:37 +02:00
Search for fstab and remove verity/avb
2020-10-03 06:47:47 +02:00
Modifications are done directly to the file in-place
Configure with env variables: KEEPVERITY
2020-01-02 06:46:59 +01:00
split <input>
Split image.*-dtb into kernel + kernel_dtb
sha1 <file>
Print the SHA1 checksum for <file>
cleanup
Cleanup the current working directory
2018-10-15 06:46:37 +02:00
2019-03-28 09:54:06 +01:00
compress[=method] <infile> [outfile]
2018-10-15 06:46:37 +02:00
Compress <infile> with [method] (default: gzip), optionally to [outfile]
<infile>/[outfile] can be '-' to be STDIN/STDOUT
2020-11-13 13:32:20 +01:00
Supported methods: bzip2 gzip lz4 lz4_legacy lz4_lg lzma xz
2018-10-15 06:46:37 +02:00
2019-03-28 09:54:06 +01:00
decompress <infile> [outfile]
2018-10-15 06:46:37 +02:00
Detect method and decompress <infile>, optionally to [outfile]
<infile>/[outfile] can be '-' to be STDIN/STDOUT
2020-11-13 13:32:20 +01:00
Supported methods: bzip2 gzip lz4 lz4_legacy lz4_lg lzma xz
2018-01-08 15:33:55 +01:00
```
### magiskinit
2019-03-28 09:54:06 +01:00
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).
2018-01-08 15:33:55 +01:00
### magiskpolicy
(This tool is aliased to `supolicy` for compatibility with SuperSU's sepolicy tool)
2018-10-15 06:46:37 +02:00
An applet of `magiskinit`. This tool could be used for advanced developers to modify SELinux policies. In common scenarios like Linux server admins, they would directly modify the SELinux policy sources (`*.te`) and recompile the `sepolicy` binary, but here on Android we directly patch the binary file (or runtime policies).
2018-01-08 15:33:55 +01:00
2018-10-15 06:46:37 +02:00
All processes spawned from the Magisk daemon, including root shells and all its forks, are running in the context `u:r:magisk:s0`. The rule used on all Magisk installed systems can be viewed as stock `sepolicy` with these patches: `magiskpolicy --magisk 'allow magisk * * *'`.
2018-01-08 15:33:55 +01:00
```
2018-10-15 06:46:37 +02:00
Usage: magiskpolicy [--options...] [policy statements...]
2018-01-08 15:33:55 +01:00
Options:
2019-03-28 09:54:06 +01:00
--help show help message for policy statements
--load FILE load policies from FILE
2020-01-02 06:45:08 +01:00
--load-split load from precompiled sepolicy or compile
2019-03-28 09:54:06 +01:00
split policies
--compile-split compile split cil policies
--save FILE save policies to FILE
2018-10-15 06:46:37 +02:00
--live directly apply sepolicy live
--magisk inject built-in rules for a minimal
Magisk selinux environment
2020-01-02 06:45:08 +01:00
--apply FILE apply rules from FILE, read and parsed
line by line as policy statements
2018-01-08 15:33:55 +01:00
2018-10-15 06:46:37 +02:00
If neither --load or --compile-split is specified, it will load
from current live policies (/sys/fs/selinux/policy)
2018-01-08 15:33:55 +01:00
One policy statement should be treated as one parameter;
2020-10-03 06:47:47 +02:00
this means each policy statement should be enclosed in quotes.
2020-01-02 06:45:08 +01:00
Multiple policy statements can be provided in a single command.
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
Statements has a format of "<rule_name> [args...]".
Arguments labeled with (^) can accept one or more entries. Multiple
entries consist of a space separated list enclosed in braces ({}).
Arguments labeled with (*) are the same as (^), but additionally
support the match-all operator (*).
Example: "allow { s1 s2 } { t1 t2 } class *"
Will be expanded to:
allow s1 t1 class { all-permissions-of-class }
allow s1 t2 class { all-permissions-of-class }
allow s2 t1 class { all-permissions-of-class }
allow s2 t2 class { all-permissions-of-class }
2018-01-08 15:33:55 +01:00
Supported policy statements:
2020-10-03 06:47:47 +02:00
"allow *source_type *target_type *class *perm_set"
"deny *source_type *target_type *class *perm_set"
"auditallow *source_type *target_type *class *perm_set"
"dontaudit *source_type *target_type *class *perm_set"
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"allowxperm *source_type *target_type *class operation xperm_set"
"auditallowxperm *source_type *target_type *class operation xperm_set"
"dontauditxperm *source_type *target_type *class operation xperm_set"
- The only supported operation is 'ioctl'
- xperm_set format is either 'low-high', 'value', or '*'.
'*' will be treated as '0x0000-0xFFFF'.
All values should be written in hexadecimal.
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"permissive ^type"
"enforce ^type"
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"typeattribute ^type ^attribute"
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"type type_name ^(attribute)"
- Argument 'attribute' is optional, default to 'domain'
2019-03-28 09:54:06 +01:00
2020-10-03 06:47:47 +02:00
"attribute attribute_name"
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"type_transition source_type target_type class default_type (object_name)"
- Argument 'object_name' is optional
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"type_change source_type target_type class default_type"
"type_member source_type target_type class default_type"
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
"genfscon fs_name partial_path fs_context"
2018-01-08 15:33:55 +01:00
```
### magisk
2020-10-03 06:47:47 +02:00
When the magisk binary is called with the name `magisk`, it works as a utility tool with many helper functions and the entry points for several Magisk services.
2018-01-08 15:33:55 +01:00
```
Usage: magisk [applet [arguments]...]
or: magisk [options]...
Options:
-c print current binary version
-v print running daemon version
-V print running daemon version code
--list list all available applets
2019-09-19 11:00:29 +02:00
--remove-modules remove all modules and reboot
2020-10-03 06:47:47 +02:00
--install-module ZIP install a module zip file
2019-03-28 09:54:06 +01:00
Advanced Options (Internal APIs):
2020-10-03 06:47:47 +02:00
--daemon manually start magisk daemon
--[init trigger] start service for init trigger
Supported init triggers:
post-fs-data, service, boot-complete
2018-01-08 15:33:55 +01:00
--unlock-blocks set BLKROSET flag to OFF for all block devices
2019-03-28 09:54:06 +01:00
--restorecon restore selinux context on Magisk files
2018-01-08 15:33:55 +01:00
--clone-attr SRC DEST clone permission, owner, and selinux context
2019-03-28 09:54:06 +01:00
--clone SRC DEST clone SRC to DEST
2019-09-19 11:00:29 +02:00
--sqlite SQL exec SQL commands to Magisk database
2020-10-03 06:47:47 +02:00
--path print Magisk tmpfs mount path
2018-01-08 15:33:55 +01:00
2020-10-03 06:47:47 +02:00
Available applets:
2019-09-19 11:00:29 +02:00
su, resetprop, magiskhide
2018-01-08 15:33:55 +01:00
```
### su
2018-10-15 06:46:37 +02:00
An applet of `magisk`, the MagiskSU entry point. Good old `su` command.
2018-01-08 15:33:55 +01:00
```
Usage: su [options] [-] [user [argument...]]
Options:
-c, --command COMMAND pass COMMAND to the invoked shell
-h, --help display this help message and exit
-, -l, --login pretend the shell to be a login shell
-m, -p,
--preserve-environment preserve the entire environment
-s, --shell SHELL use SHELL instead of the default /system/bin/sh
-v, --version display version number and exit
2018-10-15 06:46:37 +02:00
-V display version code and exit
2018-01-08 15:33:55 +01:00
-mm, -M,
2018-10-15 06:46:37 +02:00
--mount-master force run in the global mount namespace
2018-01-08 15:33:55 +01:00
```
2018-10-15 06:46:37 +02:00
Note: even though the `-Z, --context` option is not listed above, the option still exists for CLI compatibility with apps designed for SuperSU. However the option is silently ignored since it's no longer relevant.
2018-01-08 15:33:55 +01:00
### resetprop
2018-10-15 06:46:37 +02:00
An applet of `magisk`. An advanced system property manipulation utility. Check the [Resetprop Details](details.md#resetprop) for more background information.
2018-01-08 15:33:55 +01:00
```
Usage: resetprop [flags] [options...]
Options:
-h, --help show this message
(no arguments) print all properties
NAME get property
NAME VALUE set property entry NAME with VALUE
--file FILE load props from FILE
--delete NAME delete property
Flags:
-v print verbose output to stderr
2020-11-13 13:32:20 +01:00
-n set props without going through property_service
(this flag only affects setprop)
-p read/write props from/to persistent storage
(this flag only affects getprop and delprop)
2018-01-08 15:33:55 +01:00
```
### magiskhide
An applet of `magisk`, the CLI to control MagiskHide. Use this tool to communicate with the daemon to change MagiskHide settings.
```
2019-09-19 11:00:29 +02:00
Usage: magiskhide [action [arguments...] ]
Actions:
status Return the status of magiskhide
enable Start magiskhide
disable Stop magiskhide
add PKG [PROC] Add a new target to the hide list
rm PKG [PROC] Remove target(s) from the hide list
ls Print the current hide list
exec CMDs... Execute commands in isolated mount
namespace and do all hide unmounts
2018-10-15 06:46:37 +02:00
```