Scripts de execução única

Um script de execução única (one-shot) é um ZIP que o gerenciador do KernelSU executa uma vez em vez de instalar. Ele é empacotado como um módulo, mas nada permanece no dispositivo: o gerenciador extrai o ZIP para um diretório privado, solicita os parâmetros que ele declara, mostra o código-fonte do action.sh e o executa em um shell root. Use-o para tarefas como desbloquear uma configuração oculta ou exportar um log; qualquer coisa que precise ser executada na inicialização ou modificar as partições do sistema deve ser um módulo.

Estrutura do pacote

<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

O module.prop usa os mesmos campos de um módulo e adiciona oneshot:

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

O oneshot é lido da mesma forma que o metamodule: o valor, ignorando espaços em branco ao redor, é 1 ou true (sem diferenciar maiúsculas de minúsculas). Qualquer outro valor, ou a ausência da linha oneshot, indica um módulo comum.

Não inclua arquivos exclusivos de módulos, como post-fs-data.sh, service.sh, system.prop, sepolicy.rule ou um diretório system/: eles nunca são usados em uma execução única. Um script de execução única não pode ser um metamodule.

Executando um script

Há duas formas de executar um script de execução única:

• Pela loja de módulos: entradas do registro KernelSU Modules com kind: script exibem um selo "Script" e um botão Run em vez de Instalar. O download é verificado em relação ao tamanho e ao SHA-256 do registro, e o module.prop deve conter o id registrado.
• Por um ZIP local: se você selecionar um único ZIP do armazenamento (ou abrir um a partir de outro app) e o module.prop dele tiver oneshot=true, a página de execução será aberta em vez do instalador. A página também oferece Install as module anyway.

Antes de executar, o gerenciador verifica se o module.prop declara oneshot com um id válido e se o action.sh existe na raiz do ZIP, e então extrai o ZIP. Caminhos absolutos, .., links simbólicos e arquivos especiais são rejeitados, e o conteúdo extraído é limitado a 64 MiB e 4096 entradas.

A página de execução mostra o formulário de parâmetros, o código-fonte do action.sh e a última execução neste dispositivo. Após uma confirmação, o gerenciador executa o script em um novo shell root no namespace de montagem global, como o botão Ação de um módulo:

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

A saída é exibida como a saída da Ação e pode ser salva. O diretório extraído é removido em seguida. O gerenciador lembra apenas a última execução (versão e código de saída); não há estado de instalação nem verificação de atualizações.

Variáveis de ambiente

Variável	Valor
ASH_STANDALONE	1
KSU	true
KSU_VER, KSU_VER_CODE, KSU_KERNEL_VER_CODE	Versões do KernelSU, como para módulos
KSU_LATE_LOAD	1 apenas no modo late-load
KSU_MODULE	o ID do script
KSU_ONESHOT	1, para distinguir uma execução única do botão Ação de um módulo instalado
MODPATH	o diretório de extração; leia seus arquivos de dados a partir daqui
PATH	$PATH:/data/adb/ksu/bin
KSU_PARAM_<KEY>	uma por parâmetro, consulte params.json

O stdin é /dev/null, então o script não pode ler entradas de forma interativa; declare parâmetros em vez disso.

Códigos de saída

Código de saída	Significado
0	Sucesso.
2	Não aplicável a este dispositivo; exibido como um aviso, não como uma falha.
qualquer outro	Falha.

params.json

O params.json é opcional. Ele fica na raiz do ZIP, é um JSON em UTF-8 e tem no máximo 64 KiB. O gerenciador cria um formulário a partir dele e passa cada valor ao action.sh como 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 }
  ]
}

Campo	Regra
schemaVersion	Deve ser 1.
params	Até 16 parâmetros.
key	^[A-Z][A-Z0-9_]{0,31}$, único. O valor chega ao script como KSU_PARAM_<key>.
type	bool, enum, string ou int.
label	Obrigatório, de 1 a 200 caracteres. Os rótulos são exibidos como foram escritos (em um único idioma).
description	Opcional, mesmas regras de label.

Por tipo:

Tipo	Campos	Passado como
bool	default: true / false (padrão false).	true / false
enum	options: de 1 a 32 entradas {value, label?}; value corresponde a ^[A-Za-z0-9._-]{1,64}$ e é único. default deve ser um dos valores (padrão: a primeira opção).	o valor da opção
string	default (padrão ""), maxLength de 1 a 1024 (padrão 256), required (padrão false; um valor vazio é permitido, a menos que seja obrigatório). Os valores não podem conter NUL nem quebras de linha.	como digitado
int	min / max e default opcionais (padrão min, ou 0 sem min); inteiros com sinal de 32 bits.	decimal

O default de cada parâmetro deve satisfazer suas próprias restrições. Se o params.json for inválido, o gerenciador se recusa a executar o script.

WARNING

Não há verificação de formato para valores string. Cada valor é passado entre aspas simples, então nunca é expandido pelo shell que inicia o action.sh, mas o action.sh ainda deve validá-lo e colocá-lo entre aspas ao usá-lo.

Exemplo

#!/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"

Compatibilidade com gerenciadores antigos

Gerenciadores sem suporte a execução única instalam o ZIP como um módulo comum cujo botão Ação executa o action.sh. Mantenha o action.sh funcionando também nesse caso: nele, KSU_ONESHOT, MODPATH e KSU_PARAM_* não são definidos e o diretório de trabalho é o diretório do módulo. Use valores padrão como alternativa, como no exemplo acima:

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

Publicação

Para publicar um script de execução única no KernelSU Modules, defina kind: script no module.yaml. Consulte Script entries para as regras do registro.