website/docs/pt_BR/guide/metamodule.md
Metamódulos são um recurso revolucionário no KernelSU que transfere recursos críticos do sistema de módulos do daemon principal para módulos plugáveis. Essa mudança arquitetônica mantém a estabilidade e segurança do KernelSU enquanto libera um maior potencial de inovação para o ecossistema de módulos.
Um metamódulo é um tipo especial de módulo KernelSU que fornece funcionalidade de infraestrutura central para o sistema de módulos. Ao contrário dos módulos regulares que modificam arquivos do sistema, os metamódulos controlam como os módulos regulares são instalados e montados.
Metamódulos são um mecanismo de extensão baseado em plugins que permite a personalização completa da infraestrutura de gerenciamento de módulos do KernelSU. Ao delegar a lógica de montagem e instalação aos metamódulos, o KernelSU evita se tornar um ponto de detecção frágil enquanto permite diversas estratégias de implementação.
Características principais:
Soluções root tradicionais incorporam a lógica de montagem em seu núcleo, tornando-as mais fáceis de detectar e mais difíceis de evoluir. A arquitetura de metamódulos do KernelSU resolve esses problemas através da separação de preocupações.
Vantagens estratégicas:
Flexibilidade de montagem:
meta-overlayfs)Além da montagem:
::: warning IMPORTANTE
Sem um metamódulo instalado, os módulos NÃO serão montados. Instalações novas do KernelSU requerem a instalação de um metamódulo (como meta-overlayfs) para que os módulos funcionem.
:::
Instale um metamódulo da mesma forma que módulos regulares:
meta-overlayfs.zip)O metamódulo meta-overlayfs é a implementação de referência oficial que fornece montagem de módulos baseada em overlayfs tradicional com suporte a imagem ext4.
Você pode verificar qual metamódulo está atualmente ativo na página de Módulos do aplicativo KernelSU Manager. O metamódulo ativo será exibido na sua lista de módulos com sua designação especial.
::: danger AVISO Desinstalar um metamódulo afetará TODOS os módulos. Após a remoção, os módulos não serão mais montados até que você instale outro metamódulo. :::
Para desinstalar:
Após desinstalar, você deve instalar outro metamódulo se quiser que os módulos continuem funcionando.
Apenas um metamódulo pode ser instalado por vez. Se você tentar instalar um segundo metamódulo, o KernelSU impedirá a instalação para evitar conflitos.
Para trocar metamódulos:
Se você está desenvolvendo módulos KernelSU regulares, não precisa se preocupar muito com metamódulos. Seus módulos funcionarão desde que os usuários tenham um metamódulo compatível (como meta-overlayfs) instalado.
O que você precisa saber:
system no seu módulo só será montado se o usuário tiver um metamódulo instalado que forneça funcionalidade de montagem::: tip Se você está familiarizado com o desenvolvimento de módulos Magisk, seus módulos funcionarão da mesma forma no KernelSU quando o metamódulo estiver instalado, pois ele fornece montagem compatível com Magisk. :::
Criar um metamódulo permite que você personalize como o KernelSU lida com instalação de módulos, montagem e desinstalação.
Um metamódulo é identificado por uma propriedade especial em seu module.prop:
id=my_metamodule
name=My Custom Metamodule
version=1.0
versionCode=1
author=Your Name
description=Custom module mounting implementation
metamodule=1
A propriedade metamodule=1 (ou metamodule=true) marca isso como um metamódulo. Sem essa propriedade, o módulo será tratado como um módulo regular.
Estrutura de um metamódulo:
my_metamodule/
├── module.prop (deve incluir metamodule=1)
│
│ *** Hooks específicos de metamódulo ***
├── metamount.sh (opcional: manipulador de montagem personalizado)
├── metainstall.sh (opcional: hook de instalação para módulos regulares)
├── metauninstall.sh (opcional: hook de limpeza para módulos regulares)
│
│ *** Arquivos de módulo padrão (todos opcionais) ***
├── customize.sh (personalização de instalação)
├── post-fs-data.sh (script de estágio post-fs-data)
├── service.sh (script late_start service)
├── boot-completed.sh (script de inicialização concluída)
├── uninstall.sh (script de desinstalação do próprio metamódulo)
├── system/ (modificações systemless, se necessário)
└── [quaisquer arquivos adicionais]
Metamódulos podem usar todos os recursos de módulos padrão (scripts de ciclo de vida, etc.) além de seus hooks especiais de metamódulo.
Metamódulos podem fornecer até três scripts de hook especiais:
Propósito: Controla como os módulos são montados durante a inicialização.
Quando executado: Durante o estágio post-fs-data, antes de qualquer script de módulo ser executado.
Variáveis de ambiente:
MODDIR: O caminho do diretório do metamódulo (por exemplo, /data/adb/modules/my_metamodule)Responsabilidades:
skip_mount::: danger REQUISITO CRÍTICO
Ao realizar operações de montagem, você DEVE definir o nome da origem/dispositivo como "KSU". Isso identifica as montagens como pertencentes ao KernelSU.
Exemplo (correto):
mount -t overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work KSU /target
Para APIs de montagem modernas, defina a string de origem:
fsconfig_set_string(fs, "source", "KSU")?;
Isso é essencial para o KernelSU identificar e gerenciar adequadamente suas montagens. :::
Script de exemplo:
#!/system/bin/sh
MODDIR="${0%/*}"
# Exemplo: Implementação simples de bind mount
for module in /data/adb/modules/*; do
if [ -f "$module/disable" ] || [ -f "$module/skip_mount" ]; then
continue
fi
if [ -d "$module/system" ]; then
# Monte com source=KSU (OBRIGATÓRIO!)
mount -o bind,dev=KSU "$module/system" /system
fi
done
Propósito: Personalizar como módulos regulares são instalados.
Quando executado: Durante a instalação do módulo, após a extração dos arquivos, mas antes da conclusão da instalação. Este script é executado por source (não executado) pelo instalador embutido, semelhante a como customize.sh funciona.
Variáveis de ambiente e funções:
Este script herda todas as variáveis e funções do install.sh embutido:
MODPATH, TMPDIR, ZIPFILE, ARCH, API, IS64BIT, KSU, KSU_VER, KSU_VER_CODE, BOOTMODE, etc.ui_print <msg> - Imprime mensagem no consoleabort <msg> - Imprime erro e encerra a instalaçãoset_perm <target> <owner> <group> <permission> [context] - Define permissões de arquivoset_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission> [context] - Define permissões recursivamenteinstall_module - Chama o processo de instalação de módulo embutidoCasos de uso:
install_module quando estiver pronto)Nota: Este script NÃO é chamado ao instalar o próprio metamódulo.
Propósito: Limpar recursos quando módulos regulares são desinstalados.
Quando executado: Durante a desinstalação do módulo, antes do diretório do módulo ser removido.
Variáveis de ambiente:
MODULE_ID: O ID do módulo sendo desinstaladoCasos de uso:
Script de exemplo:
#!/system/bin/sh
# Chamado ao desinstalar módulos regulares
MODULE_ID="$1"
IMG_MNT="/data/adb/metamodule/mnt"
# Remover arquivos do módulo da imagem
if [ -d "$IMG_MNT/$MODULE_ID" ]; then
rm -rf "$IMG_MNT/$MODULE_ID"
fi
Entender a ordem de execução da inicialização é crucial para o desenvolvimento de metamódulos:
estágio post-fs-data:
1. Scripts comuns post-fs-data.d são executados
2. Limpar módulos, restorecon, carregar sepolicy.rule
3. post-fs-data.sh do metamódulo é executado (se existir)
4. post-fs-data.sh dos módulos regulares são executados
5. Carregar system.prop
6. metamount.sh do metamódulo é executado
└─> Monta todos os módulos de forma systemless
7. Estágio post-mount.d é executado
- Scripts comuns post-mount.d
- post-mount.sh do metamódulo (se existir)
- post-mount.sh dos módulos regulares
estágio service:
1. Scripts comuns service.d são executados
2. service.sh do metamódulo é executado (se existir)
3. service.sh dos módulos regulares são executados
estágio boot-completed:
1. Scripts comuns boot-completed.d são executados
2. boot-completed.sh do metamódulo é executado (se existir)
3. boot-completed.sh dos módulos regulares são executados
Pontos-chave:
metamount.sh é executado APÓS todos os scripts post-fs-data (tanto metamódulo quanto módulos regulares)post-fs-data.sh, service.sh, boot-completed.sh) sempre são executados antes dos scripts de módulos regulares.d são executados antes dos scripts de metamódulopost-mount é executado após a conclusão da montagemQuando um metamódulo é instalado, o KernelSU cria um symlink:
/data/adb/metamodule -> /data/adb/modules/<metamodule_id>
Isso fornece um caminho estável para acessar o metamódulo ativo, independentemente de seu ID.
Benefícios:
O metamódulo meta-overlayfs é a implementação de referência oficial. Ele demonstra as melhores práticas para desenvolvimento de metamódulos.
meta-overlayfs usa uma arquitetura de diretório duplo:
Diretório de metadados: /data/adb/modules/
module.prop, disable, marcadores skip_mountDiretório de conteúdo: /data/adb/metamodule/mnt/
modules.img)Veja como meta-overlayfs implementa o manipulador de montagem:
#!/system/bin/sh
MODDIR="${0%/*}"
IMG_FILE="$MODDIR/modules.img"
MNT_DIR="$MODDIR/mnt"
# Montar imagem ext4 se ainda não estiver montada
if ! mountpoint -q "$MNT_DIR"; then
mkdir -p "$MNT_DIR"
mount -t ext4 -o loop,rw,noatime "$IMG_FILE" "$MNT_DIR"
fi
# Definir variáveis de ambiente para suporte de diretório duplo
export MODULE_METADATA_DIR="/data/adb/modules"
export MODULE_CONTENT_DIR="$MNT_DIR"
# Executar binário de montagem
# (A lógica de montagem real está em um binário Rust)
"$MODDIR/meta-overlayfs"
Montagem Overlayfs:
/data/adb/modules/.rw/Identificação de origem:
// De meta-overlayfs/src/mount.rs
fsconfig_set_string(fs, "source", "KSU")?; // OBRIGATÓRIO!
Isso define dev=KSU para todas as montagens overlay, permitindo identificação adequada.
Ao desenvolver metamódulos:
skip_mount e disableecho ou logging para depuraçãoAntes de lançar:
Para usuários: Apenas se você quiser usar módulos que requerem montagem. Se você usa apenas módulos que executam scripts sem modificar arquivos do sistema, não precisa de um metamódulo.
Para desenvolvedores de módulos: Não, você desenvolve módulos normalmente. Os usuários precisam de um metamódulo apenas se seu módulo requer montagem.
Para usuários avançados: Apenas se você quiser personalizar o comportamento de montagem ou criar implementações alternativas de montagem.
Não. Apenas um metamódulo pode ser instalado por vez. Isso evita conflitos e garante comportamento previsível.
Os módulos não serão mais montados. Seu dispositivo inicializará normalmente, mas as modificações dos módulos não serão aplicadas até que você instale outro metamódulo.
Não. Ele fornece montagem overlayfs padrão compatível com a maioria dos módulos. Você pode criar seu próprio metamódulo se precisar de comportamento diferente.