Script chạy một lần

Script chạy một lần (one-shot script) là một tệp ZIP mà trình quản lý KernelSU chạy một lần thay vì cài đặt. Nó được đóng gói giống như một module, nhưng không có gì được giữ lại trên thiết bị: trình quản lý giải nén ZIP vào một thư mục riêng, hỏi các tham số mà nó khai báo, hiển thị mã nguồn action.sh và chạy nó trong root shell. Hãy dùng nó cho các tác vụ như mở khóa một cài đặt ẩn hoặc xuất log; mọi thứ cần chạy khi khởi động hoặc sửa đổi các phân vùng hệ thống nên là một module.

Cấu trúc gói

<id>-<version>.zip
├── module.prop      # the usual module.prop fields + oneshot=true
├── action.sh        # required: the script the manager runs
├── params.json      # optional: parameters asked before running
├── customize.sh     # optional: only used if the ZIP is installed as a module
└── other files      # data the script reads via $MODPATH

module.prop sử dụng các trường giống như một module và bổ sung oneshot:

id=example_script
name=Example Script
version=v1
versionCode=1
author=Alice
description=Does a thing once
oneshot=true

oneshot được đọc giống như metamodule: giá trị, bỏ qua khoảng trắng xung quanh, là 1 hoặc true (không phân biệt hoa thường). Bất kỳ giá trị nào khác, hoặc không có dòng oneshot, đều có nghĩa là một module thông thường.

Không đưa vào các tệp chỉ dành cho module như post-fs-data.sh, service.sh, system.prop, sepolicy.rule hoặc thư mục system/: chúng không bao giờ được sử dụng trong một lần chạy one-shot. Script chạy một lần không thể là metamodule.

Chạy script

Có hai cách để chạy một script chạy một lần:

• Từ kho module: các mục trong registry KernelSU Modules có kind: script hiển thị huy hiệu "Script" và nút Run thay vì Cài đặt. Tệp tải xuống được kiểm tra theo kích thước và SHA-256 của registry, và module.prop phải mang id đã đăng ký.
• Từ tệp ZIP cục bộ: nếu bạn chọn một tệp ZIP duy nhất từ bộ nhớ (hoặc mở nó từ một ứng dụng khác) và module.prop của nó có oneshot=true, trang chạy sẽ mở ra thay vì trình cài đặt. Trang này cũng cung cấp tùy chọn Install as module anyway.

Trước khi chạy, trình quản lý kiểm tra rằng module.prop khai báo oneshot với một id hợp lệ và action.sh tồn tại ở thư mục gốc của ZIP, sau đó giải nén ZIP. Các đường dẫn tuyệt đối, .., liên kết tượng trưng và tệp đặc biệt bị từ chối, và nội dung giải nén bị giới hạn ở 64 MiB và 4096 mục.

Trang chạy hiển thị biểu mẫu tham số, mã nguồn action.sh và lần chạy gần nhất trên thiết bị này. Sau khi xác nhận, trình quản lý chạy script trong một root shell mới ở mount namespace toàn cục, giống như nút hành động (Action) của module:

cd <dir> && <env> /data/adb/ksu/bin/busybox sh ./action.sh </dev/null

Đầu ra được hiển thị giống như đầu ra của Action và có thể được lưu lại. Thư mục giải nén sẽ bị xóa sau đó. Trình quản lý chỉ ghi nhớ lần chạy gần nhất (phiên bản và mã thoát); không có trạng thái đã cài đặt và không kiểm tra cập nhật.

Biến môi trường

Biến	Giá trị
ASH_STANDALONE	1
KSU	true
KSU_VER, KSU_VER_CODE, KSU_KERNEL_VER_CODE	các phiên bản KernelSU, giống như với module
KSU_LATE_LOAD	1 chỉ trong chế độ late-load
KSU_MODULE	ID của script
KSU_ONESHOT	1, để phân biệt lần chạy one-shot với nút Action của một module đã cài đặt
MODPATH	thư mục giải nén; hãy đọc các tệp dữ liệu của bạn từ đây
PATH	$PATH:/data/adb/ksu/bin
KSU_PARAM_<KEY>	mỗi tham số một biến, xem params.json

Stdin là /dev/null, vì vậy script không thể đọc đầu vào một cách tương tác; hãy khai báo tham số thay thế.

Mã thoát

Mã thoát	Ý nghĩa
0	Thành công.
2	Không áp dụng cho thiết bị này; được hiển thị như một thông báo, không phải lỗi.
bất kỳ giá trị nào khác	Thất bại.

params.json

params.json là tùy chọn. Nó nằm ở thư mục gốc của ZIP, là JSON UTF-8 và có kích thước tối đa 64 KiB. Trình quản lý xây dựng biểu mẫu từ nó và truyền mọi giá trị cho action.sh dưới dạng KSU_PARAM_<KEY>.

{
  "schemaVersion": 1,
  "params": [
    {
      "key": "ENABLE_FASTBOOT",
      "type": "bool",
      "label": "Also enable fastboot",
      "description": "Optional longer help text",
      "default": true
    },
    { "key": "MODE", "type": "enum", "label": "Mode", "default": "a",
      "options": [ { "value": "a", "label": "A" }, { "value": "b" } ] },
    { "key": "NAME", "type": "string", "label": "Name", "default": "", "maxLength": 64,
      "required": false },
    { "key": "COUNT", "type": "int", "label": "Count", "default": 1, "min": 0, "max": 10 }
  ]
}

Trường	Quy tắc
schemaVersion	Phải là 1.
params	Tối đa 16 tham số.
key	^[A-Z][A-Z0-9_]{0,31}$, duy nhất. Giá trị được truyền tới script dưới dạng KSU_PARAM_<key>.
type	bool, enum, string hoặc int.
label	Bắt buộc, 1–200 ký tự. Nhãn được hiển thị đúng như khi viết (chỉ một ngôn ngữ).
description	Tùy chọn, quy tắc giống như label.

Theo từng kiểu:

Kiểu	Trường	Được truyền dưới dạng
bool	default: true / false (mặc định false).	true / false
enum	options: 1–32 mục {value, label?}; value khớp với ^[A-Za-z0-9._-]{1,64}$ và là duy nhất. default phải là một trong các giá trị (mặc định: tùy chọn đầu tiên).	giá trị của tùy chọn
string	default (mặc định ""), maxLength 1–1024 (mặc định 256), required (mặc định false; cho phép giá trị rỗng trừ khi bắt buộc). Giá trị không được chứa NUL hoặc ký tự xuống dòng.	như đã nhập
int	min / max và default tùy chọn (mặc định là min, hoặc 0 nếu không có min); số nguyên có dấu 32-bit.	số thập phân

default của mọi tham số phải thỏa mãn các ràng buộc của chính nó. Nếu params.json không hợp lệ, trình quản lý sẽ từ chối chạy script.

WARNING

Không có kiểm tra định dạng cho các giá trị string. Mọi giá trị đều được truyền trong dấu nháy đơn, vì vậy nó không bao giờ bị shell khởi chạy action.sh mở rộng, nhưng action.sh vẫn phải xác thực giá trị và đặt nó trong dấu nháy khi sử dụng.

Ví dụ

#!/system/bin/sh
# action.sh
MODPATH=${MODPATH:-${0%/*}}

if [ "$(getprop ro.miui.ui.version.name)" = "" ]; then
  echo "Not a MIUI device"
  exit 2
fi

echo "Mode: ${KSU_PARAM_MODE:-a}"
if [ "$KSU_PARAM_ENABLE_FASTBOOT" = "true" ]; then
  sh "$MODPATH/fastboot.sh" || exit 1
fi
echo "Done"

Tương thích với trình quản lý cũ

Các trình quản lý không hỗ trợ one-shot sẽ cài đặt ZIP như một module thông thường, có nút Action chạy action.sh. Hãy giữ cho action.sh cũng hoạt động trong trường hợp đó: khi ấy KSU_ONESHOT, MODPATH và KSU_PARAM_* không được đặt và thư mục làm việc là thư mục module. Hãy dùng giá trị mặc định thay thế, như trong ví dụ ở trên:

MODPATH=${MODPATH:-${0%/*}}
MODE=${KSU_PARAM_MODE:-a}

Xuất bản

Để xuất bản một script chạy một lần trên KernelSU Modules, hãy đặt kind: script trong module.yaml. Xem Script entries để biết các quy tắc của registry.