Метамодуль

Метамодули — это революционная функция в KernelSU, которая передает критически важные возможности модульной системы от основного демона к подключаемым модулям. Это архитектурное изменение сохраняет стабильность и безопасность KernelSU, одновременно раскрывая больший потенциал для инноваций в экосистеме модулей.

Что такое Метамодуль?

Метамодуль — это специальный тип модуля KernelSU, который предоставляет основную инфраструктурную функциональность для модульной системы. В отличие от обычных модулей, которые модифицируют системные файлы, метамодули контролируют способ установки и монтирования обычных модулей.

Метамодули — это механизм расширения на основе плагинов, который позволяет полностью настраивать инфраструктуру управления модулями KernelSU. Делегируя логику монтирования и установки метамодулям, KernelSU избегает превращения в уязвимую точку обнаружения, одновременно поддерживая различные стратегии реализации.

Ключевые характеристики:

• Роль инфраструктуры: Метамодули предоставляют сервисы, от которых зависят обычные модули
• Единственный экземпляр: Одновременно может быть установлен только один метамодуль
• Приоритетное выполнение: Скрипты метамодулей выполняются перед скриптами обычных модулей
• Специальные хуки: Предоставляет три скрипта-хука для установки, монтирования и очистки

Зачем нужны Метамодули?

Традиционные решения для получения root встраивают логику монтирования в свое ядро, что делает их более легко обнаруживаемыми и сложными для развития. Архитектура метамодулей KernelSU решает эти проблемы через разделение ответственности.

Стратегические преимущества:

• Уменьшение поверхности обнаружения: Сам KernelSU не выполняет монтирование, уменьшая векторы обнаружения
• Стабильность: Основной демон остается стабильным, в то время как реализации монтирования могут развиваться
• Инновации: Сообщество может разрабатывать альтернативные стратегии монтирования без форка KernelSU
• Выбор: Пользователи могут выбрать реализацию, которая лучше всего соответствует их потребностям

Гибкость монтирования:

• Без монтирования: Для пользователей с модулями только без монтирования полностью избегайте накладных расходов на монтирование
• Монтирование OverlayFS: Традиционный подход с поддержкой слоя чтения-записи (через meta-overlayfs)
• Magic mount: Монтирование, совместимое с Magisk, для лучшей совместимости с приложениями
• Пользовательские реализации: Наложения на основе FUSE, пользовательские монтирования VFS или совершенно новые подходы

Помимо монтирования:

• Расширяемость: Добавляйте функции, такие как поддержка модулей ядра, без изменения основного KernelSU
• Модульность: Обновляйте реализации независимо от выпусков KernelSU
• Настройка: Создавайте специализированные решения для конкретных устройств или случаев использования

ВАЖНО

Без установленного метамодуля модули НЕ будут смонтированы. Свежие установки KernelSU требуют установки метамодуля (например, meta-overlayfs) для работы модулей.

Для Пользователей

Установка Метамодуля

Установите метамодуль так же, как обычные модули:

1. Загрузите ZIP-файл метамодуля (например, meta-overlayfs.zip)
2. Откройте приложение KernelSU Manager
3. Нажмите на плавающую кнопку действия (➕)
4. Выберите ZIP-файл метамодуля
5. Перезагрузите устройство

Метамодуль meta-overlayfs — это официальная эталонная реализация, которая обеспечивает традиционное монтирование модулей на основе overlayfs с поддержкой образов ext4.

Проверка Активного Метамодуля

Вы можете проверить, какой метамодуль в настоящее время активен, на странице модулей приложения KernelSU Manager. Активный метамодуль будет отображаться в вашем списке модулей со своим специальным обозначением.

Удаление Метамодуля

ПРЕДУПРЕЖДЕНИЕ

Удаление метамодуля повлияет на ВСЕ модули. После удаления модули больше не будут монтироваться, пока вы не установите другой метамодуль.

Для удаления:

1. Откройте KernelSU Manager
2. Найдите метамодуль в списке модулей
3. Нажмите удалить (вы увидите специальное предупреждение)
4. Подтвердите действие
5. Перезагрузите устройство

После удаления вы должны установить другой метамодуль, если хотите, чтобы модули продолжали работать.

Ограничение Единственного Метамодуля

Одновременно может быть установлен только один метамодуль. Если вы попытаетесь установить второй метамодуль, KernelSU предотвратит установку, чтобы избежать конфликтов.

Для переключения метамодулей:

1. Удалите все обычные модули
2. Удалите текущий метамодуль
3. Перезагрузите
4. Установите новый метамодуль
5. Переустановите обычные модули
6. Перезагрузите снова

Для Разработчиков Модулей

Если вы разрабатываете обычные модули KernelSU, вам не нужно слишком беспокоиться о метамодулях. Ваши модули будут работать, пока у пользователей установлен совместимый метамодуль (например, meta-overlayfs).

Что вам нужно знать:

• Монтирование требует метамодуль: Директория system в вашем модуле будет смонтирована только если у пользователя установлен метамодуль, предоставляющий функциональность монтирования
• Изменения кода не требуются: Существующие модули продолжают работать без изменений

TIP

Если вы знакомы с разработкой модулей Magisk, ваши модули будут работать точно так же в KernelSU при установленном метамодуле, так как он предоставляет монтирование, совместимое с Magisk.

Для Разработчиков Метамодулей

Создание метамодуля позволяет вам настроить, как KernelSU обрабатывает установку модулей, монтирование и удаление.

Базовые Требования

Метамодуль идентифицируется специальным свойством в module.prop:

id=my_metamodule
name=My Custom Metamodule
version=1.0
versionCode=1
author=Your Name
description=Custom module mounting implementation
metamodule=1

Свойство metamodule=1 (или metamodule=true) помечает это как метамодуль. Без этого свойства модуль будет рассматриваться как обычный модуль.

Структура Файлов

Структура метамодуля:

my_metamodule/
├── module.prop              (должен включать metamodule=1)
│
│      *** Специфичные хуки метамодуля ***
├── metamount.sh             (опционально: пользовательский обработчик монтирования)
├── metainstall.sh           (опционально: хук установки для обычных модулей)
├── metauninstall.sh         (опционально: хук очистки для обычных модулей)
│
│      *** Стандартные файлы модуля (все опциональные) ***
├── customize.sh             (настройка установки)
├── post-fs-data.sh          (скрипт этапа post-fs-data)
├── service.sh               (скрипт late_start service)
├── boot-completed.sh        (скрипт завершения загрузки)
├── uninstall.sh             (скрипт удаления самого метамодуля)
├── system/                  (системные модификации, если необходимо)
└── [любые дополнительные файлы]

Метамодули могут использовать все стандартные функции модулей (скрипты жизненного цикла и т. д.) в дополнение к своим специальным хукам метамодуля.

Скрипты-Хуки

Метамодули могут предоставлять до трех специальных скриптов-хуков:

1. metamount.sh - Обработчик Монтирования

Назначение: Контролирует способ монтирования модулей во время загрузки.

Когда выполняется: Во время этапа post-fs-data, перед выполнением любых скриптов модулей.

Переменные окружения:

• MODDIR: Путь к директории метамодуля (например, /data/adb/modules/my_metamodule)
• Все стандартные переменные окружения KernelSU

Обязанности:

• Монтировать все включенные модули системно
• Проверять флаги skip_mount
• Обрабатывать специфичные требования монтирования модулей

КРИТИЧЕСКОЕ ТРЕБОВАНИЕ

При выполнении операций монтирования вы ДОЛЖНЫ установить имя источника/устройства в "KSU". Это идентифицирует монтирования как принадлежащие KernelSU.

Пример (правильный):

mount -t overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work KSU /target

Для современных API монтирования установите строку источника:

fsconfig_set_string(fs, "source", "KSU")?;

Это необходимо для правильной идентификации и управления монтированиями KernelSU.

Пример скрипта:

#!/system/bin/sh
MODDIR="${0%/*}"

# Пример: Простая реализация 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
        # Монтирование с source=KSU (ОБЯЗАТЕЛЬНО!)
        mount -o bind,dev=KSU "$module/system" /system
    fi
done

2. metainstall.sh - Хук Установки

Назначение: Настроить способ установки обычных модулей.

Когда выполняется: Во время установки модуля, после извлечения файлов, но до завершения установки. Этот скрипт подключается (не выполняется) встроенным установщиком, аналогично работе customize.sh.

Переменные окружения и функции:

Этот скрипт наследует все переменные и функции из встроенного install.sh:

• Переменные: MODPATH, TMPDIR, ZIPFILE, ARCH, API, IS64BIT, KSU, KSU_VER, KSU_VER_CODE, BOOTMODE и т. д.
• Функции:
  • ui_print <msg> - Вывести сообщение в консоль
  • abort <msg> - Вывести ошибку и завершить установку
  • set_perm <target> <owner> <group> <permission> [context] - Установить права доступа к файлу
  • set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission> [context] - Установить права рекурсивно
  • install_module - Вызвать встроенный процесс установки модуля

Случаи использования:

• Обработка файлов модуля до или после встроенной установки (вызовите install_module, когда готово)
• Перемещение файлов модуля
• Проверка совместимости модуля
• Настройка специальных структур каталогов
• Инициализация специфичных для модуля ресурсов

Примечание: Этот скрипт НЕ вызывается при установке самого метамодуля.

3. metauninstall.sh - Хук Очистки

Назначение: Очистить ресурсы при удалении обычных модулей.

Когда выполняется: Во время удаления модуля, перед удалением каталога модуля.

Переменные окружения:

• MODULE_ID: ID удаляемого модуля

Случаи использования:

• Обработка файлов
• Очистка символических ссылок
• Освобождение выделенных ресурсов
• Обновление внутреннего отслеживания

Пример скрипта:

#!/system/bin/sh
# Вызывается при удалении обычных модулей
MODULE_ID="$1"
IMG_MNT="/data/adb/metamodule/mnt"

# Удалить файлы модуля из образа
if [ -d "$IMG_MNT/$MODULE_ID" ]; then
    rm -rf "$IMG_MNT/$MODULE_ID"
fi

Порядок Выполнения

Понимание порядка выполнения загрузки критически важно для разработки метамодулей:

этап post-fs-data:
  1. Выполняются общие скрипты post-fs-data.d
  2. Очистка модулей, restorecon, загрузка sepolicy.rule
  3. Выполняется post-fs-data.sh метамодуля (если существует)
  4. Выполняются post-fs-data.sh обычных модулей
  5. Загружается system.prop
  6. Выполняется metamount.sh метамодуля
     └─> Монтирует все модули системно
  7. Выполняется этап post-mount.d
     - Общие скрипты post-mount.d
     - post-mount.sh метамодуля (если существует)
     - post-mount.sh обычных модулей

этап service:
  1. Выполняются общие скрипты service.d
  2. Выполняется service.sh метамодуля (если существует)
  3. Выполняются service.sh обычных модулей

этап boot-completed:
  1. Выполняются общие скрипты boot-completed.d
  2. Выполняется boot-completed.sh метамодуля (если существует)
  3. Выполняются boot-completed.sh обычных модулей

Ключевые моменты:

• metamount.sh выполняется ПОСЛЕ всех скриптов post-fs-data (как метамодуля, так и обычных модулей)
• Скрипты жизненного цикла метамодуля (post-fs-data.sh, service.sh, boot-completed.sh) всегда выполняются перед скриптами обычных модулей
• Общие скрипты в каталогах .d выполняются перед скриптами метамодуля
• Этап post-mount выполняется после завершения монтирования

Механизм Символических Ссылок

При установке метамодуля KernelSU создает символическую ссылку:

/data/adb/metamodule -> /data/adb/modules/<metamodule_id>

Это обеспечивает стабильный путь для доступа к активному метамодулю независимо от его ID.

Преимущества:

• Постоянный путь доступа
• Простое обнаружение активного метамодуля
• Упрощение конфигурации

Реальный Пример: meta-overlayfs

Метамодуль meta-overlayfs является официальной эталонной реализацией. Он демонстрирует лучшие практики разработки метамодулей.

Архитектура

meta-overlayfs использует архитектуру с двумя каталогами:

1. Каталог метаданных: /data/adb/modules/

   • Содержит module.prop, disable, маркеры skip_mount
   • Быстро сканируется во время загрузки
   • Малый объем хранения

2. Каталог содержимого: /data/adb/metamodule/mnt/

   • Содержит фактические файлы модулей (system, vendor, product и т. д.)
   • Хранится в образе ext4 (modules.img)
   • Оптимизировано по пространству с функциями ext4

Реализация metamount.sh

Вот как meta-overlayfs реализует обработчик монтирования:

#!/system/bin/sh
MODDIR="${0%/*}"
IMG_FILE="$MODDIR/modules.img"
MNT_DIR="$MODDIR/mnt"

# Монтировать образ ext4, если он еще не смонтирован
if ! mountpoint -q "$MNT_DIR"; then
    mkdir -p "$MNT_DIR"
    mount -t ext4 -o loop,rw,noatime "$IMG_FILE" "$MNT_DIR"
fi

# Установить переменные окружения для поддержки двух каталогов
export MODULE_METADATA_DIR="/data/adb/modules"
export MODULE_CONTENT_DIR="$MNT_DIR"

# Выполнить бинарный файл монтирования
# (Фактическая логика монтирования находится в бинарном файле Rust)
"$MODDIR/meta-overlayfs"

Ключевые Особенности

Монтирование Overlayfs:

• Использует kernel overlayfs для настоящих системных модификаций
• Поддерживает несколько разделов (system, vendor, product, system_ext, odm, oem)
• Поддержка слоя чтения-записи через /data/adb/modules/.rw/

Идентификация источника:

// Из meta-overlayfs/src/mount.rs
fsconfig_set_string(fs, "source", "KSU")?;  // ОБЯЗАТЕЛЬНО!

Это устанавливает dev=KSU для всех overlay монтирований, обеспечивая правильную идентификацию.

Лучшие Практики

При разработке метамодулей:

1. Всегда устанавливайте источник в "KSU" для операций монтирования - размонтированию ядра и zygisksu нужно это для правильного размонтирования
2. Обрабатывайте ошибки корректно - процессы загрузки чувствительны ко времени
3. Уважайте стандартные флаги - поддерживайте skip_mount и disable
4. Логируйте операции - используйте echo или логирование для отладки
5. Тщательно тестируйте - ошибки монтирования могут вызвать циклы загрузки
6. Документируйте поведение - ясно объясняйте, что делает ваш метамодуль
7. Предоставляйте пути миграции - помогайте пользователям переключаться с других решений

Тестирование Вашего Метамодуля

Перед выпуском:

1. Тестируйте установку на чистой настройке KernelSU
2. Проверяйте монтирование с различными типами модулей
3. Проверяйте совместимость с распространенными модулями
4. Тестируйте удаление и очистку
5. Проверяйте производительность загрузки (metamount.sh блокирует!)
6. Обеспечьте правильную обработку ошибок для избежания циклов загрузки

Часто Задаваемые Вопросы

Нужен ли мне метамодуль?

Для пользователей: Только если вы хотите использовать модули, требующие монтирования. Если вы используете только модули, которые запускают скрипты без изменения системных файлов, вам не нужен метамодуль.

Для разработчиков модулей: Нет, вы разрабатываете модули как обычно. Пользователям нужен метамодуль только если ваш модуль требует монтирования.

Для продвинутых пользователей: Только если вы хотите настроить поведение монтирования или создать альтернативные реализации монтирования.

Могу ли я иметь несколько метамодулей?

Нет. Одновременно может быть установлен только один метамодуль. Это предотвращает конфликты и обеспечивает предсказуемое поведение.

Что произойдет, если я удалю свой единственный метамодуль?

Модули больше не будут монтироваться. Ваше устройство будет загружаться нормально, но модификации модулей не будут применяться, пока вы не установите другой метамодуль.

Обязателен ли meta-overlayfs?

Нет. Он обеспечивает стандартное монтирование overlayfs, совместимое с большинством модулей. Вы можете создать свой собственный метамодуль, если вам нужно другое поведение.

См. Также

• Руководство по Модулям - Общая разработка модулей
• Разница с Magisk - Сравнение KernelSU и Magisk
• Как Собрать - Сборка KernelSU из исходного кода