website/docs/pt_BR/guide/module.md
O KernelSU fornece um mecanismo de módulo que consegue modificar o diretório do sistema enquanto mantém a integridade da partição do sistema. Esse mecanismo é conhecido como "sem sistema".
O mecanismo de módulos do KernelSU é quase o mesmo do Magisk. Se você já está familiarizado com o desenvolvimento de módulos Magisk, o desenvolvimento de módulos KernelSU é muito semelhante. Você pode pular a introdução dos módulos abaixo e só precisa ler Diferenças com Magisk.
::: warning METAMODULE NECESSÁRIO APENAS PARA MODIFICAÇÃO DE ARQUIVOS DO SISTEMA
KernelSU usa uma arquitetura metamodule para montar o diretório system. Somente se seu módulo precisar modificar arquivos /system (via diretório system), você precisa instalar um metamodule (como meta-overlayfs). Outros recursos de módulos como scripts, regras sepolicy e system.prop funcionam sem um metamodule.
:::
Os módulos do KernelSU suportam a exibição de interfaces e a interação com os usuários. Para mais detalhes, consulte a documentação do WebUI.
O KernelSU fornece um sistema de configuração integrado que permite que os módulos armazenem configurações de chave-valor persistentes ou temporárias. Para mais detalhes, consulte a documentação de Configuração de Módulo.
O KernelSU vem com um recurso binário BusyBox completo (incluindo suporte completo ao SELinux). O executável está localizado em /data/adb/ksu/bin/busybox. O BusyBox do KernelSU suporta "ASH Standalone Shell Mode" alternável em tempo de execução. O que este Modo Autônomo significa é que ao executar no shell ash do BusyBox, cada comando usará diretamente o miniaplicativo dentro do BusyBox, independentemente do que estiver definido em PATH. Por exemplo, comandos como ls, rm, chmod NÃO usarão o que está em PATH (no caso do Android, por padrão será /system/bin/ls, /system/bin/rm e /system/bin/chmod respectivamente), mas em vez disso chamará diretamente os miniaplicativos internos do BusyBox. Isso garante que os scripts sempre sejam executados em um ambiente previsível e sempre tenham o conjunto completo de comandos, independentemente da versão do Android em que estão sendo executados. Para forçar um comando a NÃO usar o BusyBox, você deve chamar o executável com caminhos completos.
Cada script shell executado no contexto do KernelSU será executado no shell ash do BusyBox com o Modo Autônomo ativado. Para o que é relevante para desenvolvedores terceirizados, isso inclui todos os scripts de inicialização e scripts de instalação de módulos.
Para aqueles que desejam usar o recurso Modo Autônomo fora do KernelSU, existem 2 maneiras de ativá-los:
ASH_STANDALONE como 1.
Exemplo: ASH_STANDALONE=1 /data/adb/ksu/bin/busybox sh <script>/data/adb/ksu/bin/busybox sh -o standalone <script>Para garantir que todos os shells sh subsequentes executados também sejam executados no Modo Autônomo, a opção 1 é o método preferido (e é isso que o KernelSU e o gerenciador do KernelSU usam internamente), pois as variáveis de ambiente são herdadas para os subprocesso.
::: tip DIFERENÇAS COM MAGISK O BusyBox do KernelSU agora está usando o arquivo binário compilado diretamente do projeto Magisk. Obrigado ao Magisk! Portanto, você não precisa se preocupar com problemas de compatibilidade entre scripts BusyBox no Magisk e KernelSU porque eles são exatamente iguais! :::
Um módulo KernelSU é uma pasta colocada em /data/adb/modules com a estrutura abaixo:
/data/adb/modules
├── .
├── .
|
├── $MODID <--- A pasta é nomeada com o ID do módulo
│ │
│ │ *** Identidade do módulo ***
│ │
│ ├── module.prop <--- Este arquivo armazena os metadados do módulo
│ │
│ │ *** Conteúdo principal ***
│ │
│ ├── system <--- Esta pasta será montada se skip_mount não existir
│ │ ├── ...
│ │ ├── ...
│ │ └── ...
│ │
│ │ *** Sinalizadores de status ***
│ │
│ ├── skip_mount <--- Se existir, o KernelSU não montará sua pasta de sistema
│ ├── disable <--- Se existir, o módulo será desativado
│ ├── remove <--- Se existir, o módulo será removido na próxima reinicialização
│ │
│ │ *** Arquivos opcionais ***
│ │
│ ├── post-fs-data.sh <--- Este script será executado em post-fs-data
│ ├── post-mount.sh <--- Este script será executado em post-mount
│ ├── service.sh <--- Este script será executado no serviço late_start
│ ├── boot-completed.sh <--- Este script será executado na inicialização concluída
| ├── uninstall.sh <--- Este script será executado quando o KernelSU remover seu módulo
| ├── action.sh <--- Este script será executado quando o usuário clicar no botão Ação no KernelSU
│ ├── system.prop <--- As propriedades neste arquivo serão carregadas como propriedades do sistema por resetprop
│ ├── sepolicy.rule <--- Regras adicionais do sepolicy personalizadas
│ │
│ │ *** Gerado automaticamente, NÃO CRIE OU MODIFIQUE MANUALMENTE ***
│ │
│ ├── vendor <--- Um link simbólico para $MODID/system/vendor
│ ├── product <--- Um link simbólico para $MODID/system/product
│ ├── system_ext <--- Um link simbólico para $MODID/system/system_ext
│ │
│ │ *** Quaisquer arquivos/pastas adicionais são permitidos ***
│ │
│ ├── ...
│ └── ...
|
├── another_module
│ ├── .
│ └── .
├── .
├── .
::: tip DIFERENÇAS COM MAGISK O KernelSU não possui suporte integrado para o Zygisk, portanto não há conteúdo relacionado ao Zygisk no módulo. No entanto, você pode usar ZygiskNext para suportar módulos Zygisk. Neste caso, o conteúdo do módulo Zygisk é idêntico ao suportado pelo Magisk. :::
module.prop é um arquivo de configuração para um módulo. No KernelSU, se um módulo não contiver este arquivo, ele não será reconhecido como um módulo. O formato deste arquivo é o seguinte:
id=<string>
name=<string>
version=<string>
versionCode=<int>
author=<string>
description=<string>
updateJson=<url> (opcional)
actionIcon=<path> (opcional)
webuiIcon=<path> (opcional)
id deve corresponder a esta expressão regular: ^[a-zA-Z][a-zA-Z0-9._-]+$
Exemplo: ✓ a_module, ✓ a.module, ✓ module-101, ✗ a module, ✗ 1_module, ✗ -a-module
Este é o identificador exclusivo do seu módulo. Você não deve alterá-lo depois de publicado.
versionCode deve ser um número inteiro. Isso é usado para comparar versões.
Outros que não foram mencionados acima podem ser qualquer string de linha única.
Certifique-se de usar o tipo de quebra de linha UNIX (LF) e não o Windows (CR+LF) ou Macintosh (CR).
actionIcon e webuiIcon são caminhos de imagem opcionais usados como ícones
padrão para o atalho de ação do módulo e o atalho WebUI do módulo no
aplicativo gerenciador. Esses caminhos devem ser relativos ao diretório raiz do módulo.
Por exemplo, actionIcon=icon/icon.png será resolvido como <MODDIR>/icon/icon.png.
::: tip DESCRIÇÃO DINÂMICA
O campo description pode ser substituído dinamicamente em tempo de execução usando o sistema de configuração de módulos. Veja Substituindo a Descrição do Módulo para detalhes.
:::
Por favor, leia a seção Scripts de inicialização para entender a diferença entre post-fs-data.sh e service.sh. Para a maioria dos desenvolvedores de módulos, service.sh deve ser bom o suficiente se você precisar apenas executar um script de inicialização. Se precisar executar o script após a inicialização ser concluída, use boot-completed.sh. Se você quiser fazer algo após montar OverlayFS, use post-mount.sh.
Em todos os scripts do seu módulo, use MODDIR=${0%/*} para obter o caminho do diretório base do seu módulo, NÃO codifique o caminho do seu módulo nos scripts.
::: tip DIFERENÇAS COM MAGISK
Você pode usar a variável de ambiente KSU para determinar se um script está sendo executado no KernelSU ou Magisk. Se estiver executando no KernelSU, esse valor será definido como true.
:::
systemO conteúdo deste diretório será sobreposto à partição /system do sistema usando OverlayFS após a inicialização do sistema. Isso significa que:
Se você deseja excluir um arquivo ou pasta no diretório original do sistema, você precisa criar um arquivo com o mesmo nome do arquivo/pasta no diretório do módulo usando mknod filename c 0 0. Dessa forma, o sistema OverlayFS irá automaticamente "branquear" este arquivo como se ele tivesse sido excluído (a partição /system não foi realmente alterada).
Você também pode declarar uma variável chamada REMOVE contendo uma lista de diretórios em customize.sh para executar operações de remoção, e o KernelSU executará automaticamente mknod <TARGET> c 0 0 nos diretórios correspondentes do módulo. Por exemplo:
REMOVE="
/system/app/YouTube
/system/app/Bloatware
"
A lista acima irá executar mknod $MODPATH/system/app/YouTube c 0 0 e mknod $MODPATH/system/app/Bloatware c 0 0, /system/app/YouTube e /system/app/Bloatware serão removidos após o módulo entrar em vigor.
Se você deseja substituir um diretório no sistema, você precisa criar um diretório com o mesmo caminho no diretório do módulo e, em seguida, definir o atributo setfattr -n trusted.overlay.opaque -v y <TARGET> para este diretório. Desta forma, o sistema OverlayFS substituirá automaticamente o diretório correspondente no sistema (sem alterar a partição /system).
Você pode declarar uma variável chamada REPLACE em seu arquivo customize.sh, que inclui uma lista de diretórios a serem substituídos, e o KernelSU executará automaticamente as operações correspondentes em seu diretório de módulo. Por exemplo:
REPLACE="
/system/app/YouTube
/system/app/Bloatware
"
Esta lista criará automaticamente os diretórios $MODPATH/system/app/YouTube e $MODPATH/system/app/Bloatware e, em seguida, executará setfattr -n trusted.overlay.opaque -v y $MODPATH/system/app/YouTube e setfattr -n trusted.overlay.opaque -v y $MODPATH/system/app/Bloatware. Após o módulo entrar em vigor, /system/app/YouTube e /system/app/Bloatware serão substituídos por diretórios vazios.
::: tip DIFERENÇAS COM MAGISK
O mecanismo sem sistema do KernelSU é implementado através do OverlayFS do kernel, enquanto o Magisk atualmente usa montagem mágica (montagem de ligação). Os dois métodos de implementação têm diferenças significativas, mas o objetivo final é o mesmo: modificar os arquivos /system sem modificar fisicamente a partição /system.
:::
Se você estiver interessado em OverlayFS, é recomendável ler a documentação sobre OverlayFS do kernel Linux.
Este arquivo segue o mesmo formato de build.prop. Cada linha é composta por [key]=[value].
Se o seu módulo exigir alguns patches adicionais do sepolicy, adicione essas regras a este arquivo. Cada linha neste arquivo será tratada como uma declaração de política.
Um instalador do módulo KernelSU é um módulo KernelSU empacotado em um arquivo ZIP que pode ser atualizado no gerenciador do KernelSU. O instalador do módulo KernelSU mais simples é apenas um módulo KernelSU compactado como um arquivo ZIP.
module.zip
│
├── customize.sh <--- (Opcional, mais detalhes posteriormente)
│ Este script será fornecido por update-binary
├── ...
├── ... /* O resto dos arquivos do módulo */
│
::: warning AVISO O módulo KernelSU NÃO é compatível para instalação no Recovery personalizado! :::
Se você precisar personalizar o processo de instalação do módulo, opcionalmente você pode criar um script no instalador chamado customize.sh. Este script será sourced (não executado) pelo script do instalador do módulo depois que todos os arquivos forem extraídos e as permissões padrão e o contexto secundário forem aplicados. Isso é muito útil se o seu módulo exigir configuração adicional com base na ABI do dispositivo ou se você precisar definir permissões/secontext especiais para alguns dos arquivos do seu módulo.
Se você quiser controlar e personalizar totalmente o processo de instalação, declare SKIPUNZIP=1 em customize.sh para pular todas as etapas de instalação padrão. Ao fazer isso, seu customize.sh será responsável por instalar tudo sozinho.
O script customize.sh é executado no shell BusyBox ash do KernelSU com o Modo Autônomo ativado. As seguintes variáveis e funções estão disponíveis:
KSU (bool): uma variável para marcar que o script está sendo executado no ambiente KernelSU, e o valor desta variável sempre será true. Você pode usá-lo para distinguir entre KernelSU e Magisk.KSU_VER (string): a string da versão do KernelSU atualmente instalado (ex.: v0.4.0).KSU_VER_CODE (int): o código da versão do KernelSU atualmente instalado no espaço do usuário (ex.: 10672).KSU_KERNEL_VER_CODE (int): o código da versão do KernelSU atualmente instalado no espaço do kernel (ex.: 10672).BOOTMODE (bool): sempre será true no KernelSU.MODPATH (path): o caminho onde os arquivos do seu módulo devem ser instalados.TMPDIR (path): um lugar onde você pode armazenar arquivos temporariamente.ZIPFILE (path): ZIP de instalação do seu módulo.ARCH (string): a arquitetura da CPU do dispositivo. O valor é arm, arm64, x86 ou x64.IS64BIT (bool): true se $ARCH for arm64 ou x64.API (int): o nível da API (versão do Android) do dispositivo (ex.: 23 para Android 6.0).::: warning AVISO
No KernelSU, MAGISK_VER_CODE é sempre 25200 e MAGISK_VER é sempre v25.2. Por favor, não use essas duas variáveis para determinar se ele está sendo executado no KernelSU ou não.
:::
ui_print <msg>
imprima <msg> no console
Evite usar 'echo', pois ele não será exibido no console de recovery personalizado
abort <msg>
imprima mensagem de erro <msg> para consolar e encerrar a instalação
Evite usar 'exit', pois isso irá pular as etapas de limpeza de encerramento
set_perm <target> <owner> <group> <permission> [context]
se [context] não estiver definido, o padrão é "u:object_r:system_file:s0"
esta função é uma abreviação para os seguintes comandos:
chown owner.group target
chmod permission target
chcon context target
set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission> [context]
se [context] não está definido, o padrão é "u:object_r:system_file:s0"
para todos os arquivos em <directory>, ele chamará:
set_perm arquivo proprietário do grupo filepermission
para todos os diretórios em <directory> (incluindo ele mesmo), ele vai ligar:
set_perm dir owner group dirpermission context
No KernelSU, os scripts são divididos em dois tipos com base em seu modo de execução: modo post-fs-data e modo de serviço late_start.
setprop irá bloquear o processo de inicialização! Por favor, use resetprop -n <prop_name> <prop_value> em vez disso.No KernelSU, os scripts de inicialização são divididos em dois tipos com base no local de armazenamento: scripts gerais e scripts de módulo.
/data/adb/post-fs-data.d, /data/adb/service.d, /data/adb/post-mount.d ou /data/adb/boot-completed.d.chmod +x script.sh).post-fs-data.d são executados no modo post-fs-data e os scripts em service.d são executados no modo de serviço late_start.post-fs-data.sh é executado no modo post-fs-data, service.sh é executado no modo de serviço late_start, boot-completed.sh é executado na inicialização concluída e post-mount.sh é executado no OverlayFS montado.Todos os scripts de inicialização serão executados no shell BusyBox ash do KernelSU com o Modo Autônomo ativado.
A seguir está o processo de inicialização relevante para o Android (algumas partes foram omitidas), que inclui a operação do KernelSU (com asteriscos iniciais) e pode ajudá-lo a entender melhor o propósito desses scripts de módulo:
0. Bootloader (nada nesta tela)
load patched boot.img
load kernel:
- Modo GKI: kernel GKI com KernelSU integrado
- Modo LKM: kernel stock
...
1. kernel exec init (logo OEM na tela):
- Modo GKI: stock init
- Modo LKM: exec ksuinit, insmod kernelsu.ko, exec stock init
mount /dev, /dev/pts, /proc, /sys, etc.
property-init -> read default props
read init.rc
...
early-init -> init -> late_init
early-fs
start vold
fs
mount /vendor, /system, /persist, etc.
post-fs-data
*verificação do modo de segurança
*executar scripts gerais em post-fs-data.d/
*carregar sepolicy.rule
*montar tmpfs
*executar scripts de módulo post-fs-data.sh
**(Zygisk)./bin/zygisk-ptrace64 monitor
*(pré)carregamento de system.prop (igual a resetprop -n)
*remontar módulos em /system
*executar scripts gerais em post-mount.d/
*executar scripts de módulo post-mount.sh
zygote-start
load_all_props_action
*executar resetprop (defina adereços reais para resetprop com a opção -n)
... -> boot
class_start core
start-service logd, console, vold, etc.
class_start main
start-service adb, netd (iptables), zygote, etc.
2. kernel2user init (animação da ROM na tela, inicie pelo serviço bootanim)
*executar scripts gerais em service.d/
*executar scripts de módulo service.sh
*definir adereços para resetprop sem a opção -p
**(Zygisk) hook zygote (iniciar o zygiskd)
**(Zygisk) montar zygisksu/module.prop
iniciar apps do sistema (início automático)
...
inicialização completa (transmitir evento ACTION_BOOT_COMPLETED)
*executar scripts gerais em boot-completed.d/
*executar scripts de módulo boot-completed.sh
3. Operável pelo usuário (tela de bloqueio)
insira a senha para descriptografar /data/data
*conjunto real de adereços para resetprop com opção -p
iniciar apps de usuário (início automático)
Se você estiver interessado na linguagem de inicialização do Android, é recomendável ler sua documentação.
Além do fluxo de inicialização padrão descrito acima, o KernelSU suporta um modo late-load para cenários de LKM (Loadable Kernel Module). Neste modo, o módulo do kernel KernelSU é carregado após o sistema ter sido totalmente iniciado, em vez de durante o processo init.
O late-load é acionado executando o comando ksud late-load. Este comando:
kernelsu.ko correspondente dos recursos incorporados.Como o sistema já está totalmente em execução, certos mecanismos de tempo de inicialização estão indisponíveis ou são desnecessários.
| Comportamento | Inicialização padrão | Modo late-load |
|---|---|---|
| Módulo do kernel carregado pelo init (PID 1) | Sim | Não (carregado após inicialização) |
| Hooks kprobe do ksud (execve/read/fstat/input) | Sim | Ignorado |
| Detecção de modo seguro (tecla de volume) | Sim | Sempre desativado |
| Captura de log de inicialização (logcat/dmesg) | Sim | Ignorado |
| Verificação de coexistência com Magisk | Sim | Ignorado |
Evento post-fs-data reportado ao kernel | Sim | Ignorado |
Evento boot-completed reportado ao kernel | Sim | Definido diretamente durante init |
Scripts post-fs-data.sh / post-fs-data.d/ | Sim | Substituído pelo estágio late-load |
Carregamento de system.prop | Sim | Sim |
| Montagem OverlayFS (metamodule) | Sim | Sim |
Scripts post-mount.sh / post-mount.d/ | Sim | Sim |
Scripts service.sh / service.d/ | Sim | Sim |
Scripts boot-completed.sh / boot-completed.d/ | Sim | Sim |
Variável de ambiente KSU_LATE_LOAD | Não definida | Definida como 1 |
Flag de info do kernel 0x4 | Não definida | Definida |
No modo late-load, a ordem de execução dos scripts é:
ksud late-load:
1. Carregar kernelsu.ko (se ainda não carregado)
2. Extrair binários, processar atualizações de módulos, carregar regras SELinux, inicializar features
3. Executar scripts late-load.d/ e scripts late-load dos módulos (bloqueante)
4. Carregar system.prop (resetprop -n)
5. Executar script de montagem do metamodule (OverlayFS)
6. Executar scripts post-mount.d/ e post-mount.sh dos módulos (bloqueante)
7. Executar scripts service.d/ e service.sh dos módulos (não bloqueante)
8. Executar scripts boot-completed.d/ e boot-completed.sh dos módulos (não bloqueante)
Módulos podem fornecer um script late-load.sh que é executado apenas no modo late-load, como substituto do post-fs-data.sh. Este script é executado antes da montagem do OverlayFS, similar ao post-fs-data.sh no fluxo padrão.
Além disso, scripts gerais podem ser colocados em /data/adb/late-load.d/ para serem executados neste estágio.
Módulos podem detectar o modo late-load verificando a variável de ambiente KSU_LATE_LOAD:
if [ "$KSU_LATE_LOAD" = "1" ]; then
# Executando no modo late-load
echo "Late-load mode detected"
fi
Isso permite que os módulos ajustem seu comportamento de acordo, por exemplo, pulando operações que só são necessárias durante a inicialização antecipada.