ContextQMD
Back to Kernelsu

メタモジュール

website/docs/ja_JP/guide/metamodule.md

3.2.421.0 KB
Original Source

メタモジュール

メタモジュールは、KernelSU の革命的な機能であり、モジュールシステムの重要な機能をコアデーモンからプラグイン可能なモジュールに移行します。このアーキテクチャの転換により、KernelSU の安定性とセキュリティを維持しながら、モジュールエコシステムのより大きなイノベーションの可能性を解き放ちます。

メタモジュールとは?

メタモジュールは、モジュールシステムのコアインフラストラクチャ機能を提供する特別なタイプの KernelSU モジュールです。システムファイルを変更する通常のモジュールとは異なり、メタモジュールは通常のモジュールのインストールとマウントの方法を制御します。

メタモジュールは、KernelSU のモジュール管理インフラストラクチャの完全なカスタマイズを可能にするプラグインベースの拡張メカニズムです。マウントとインストールのロジックをメタモジュールに委任することで、KernelSU は脆弱な検出ポイントになることを避けながら、多様な実装戦略を可能にします。

主な特徴:

  • インフラストラクチャの役割: メタモジュールは通常のモジュールが依存するサービスを提供します
  • 単一インスタンス: 一度に1つのメタモジュールのみインストールできます
  • 優先実行: メタモジュールスクリプトは通常のモジュールスクリプトの前に実行されます
  • 特別なフック: インストール、マウント、クリーンアップのための3つのフックスクリプトを提供します

なぜメタモジュールが必要なのか?

従来のルートソリューションは、マウントロジックをコアに組み込んでおり、検出されやすく、進化させることが困難です。KernelSU のメタモジュールアーキテクチャは、関心の分離によってこれらの問題を解決します。

戦略的優位性:

  • 検出面の削減: KernelSU 自体はマウントを実行しないため、検出ベクトルが減少します
  • 安定性: コアデーモンは安定したままで、マウント実装は進化し続けることができます
  • イノベーション: コミュニティは KernelSU をフォークすることなく、代替マウント戦略を開発できます
  • 選択: ユーザーは自分のニーズに最適な実装を選択できます

マウントの柔軟性:

  • マウントなし: マウントレスモジュールのみを使用するユーザーは、マウントのオーバーヘッドを完全に回避できます
  • OverlayFS マウント: 読み書きレイヤーサポートを備えた従来のアプローチ(meta-overlayfs 経由)
  • マジックマウント: より良いアプリ互換性のための Magisk 互換マウント
  • カスタム実装: FUSE ベースのオーバーレイ、カスタム VFS マウント、または全く新しいアプローチ

マウントを超えて:

  • 拡張性: コア KernelSU を変更することなく、カーネルモジュールサポートなどの機能を追加できます
  • モジュール性: KernelSU リリースとは独立して実装を更新できます
  • カスタマイズ: 特定のデバイスやユースケースに特化したソリューションを作成できます

::: warning 重要 メタモジュールがインストールされていない場合、モジュールはマウントされません。新規の KernelSU インストールでは、モジュールを機能させるためにメタモジュール(meta-overlayfs など)をインストールする必要があります。 :::

ユーザー向け

メタモジュールのインストール

通常のモジュールと同じ方法でメタモジュールをインストールします:

  1. メタモジュール ZIP ファイル(例: meta-overlayfs.zip)をダウンロードします
  2. KernelSU Manager アプリを開きます
  3. フローティングアクションボタン(➕)をタップします
  4. メタモジュール ZIP ファイルを選択します
  5. デバイスを再起動します

meta-overlayfs メタモジュールは、ext4 イメージサポートを備えた従来の overlayfs ベースのモジュールマウントを提供する公式リファレンス実装です。

アクティブなメタモジュールの確認

KernelSU Manager アプリのモジュールページで、現在アクティブなメタモジュールを確認できます。アクティブなメタモジュールは、特別な指定とともにモジュールリストに表示されます。

メタモジュールのアンインストール

::: danger 警告 メタモジュールをアンインストールすると、すべてのモジュールに影響します。削除後、別のメタモジュールをインストールするまで、モジュールはマウントされなくなります。 :::

アンインストール手順:

  1. KernelSU Manager を開きます
  2. モジュールリストでメタモジュールを見つけます
  3. アンインストールをタップします(特別な警告が表示されます)
  4. アクションを確認します
  5. デバイスを再起動します

アンインストール後、モジュールが引き続き動作するようにするには、別のメタモジュールをインストールする必要があります。

単一メタモジュールの制約

一度に1つのメタモジュールのみインストールできます。2つ目のメタモジュールをインストールしようとすると、KernelSU は競合を避けるためにインストールを防止します。

メタモジュールを切り替える手順:

  1. すべての通常のモジュールをアンインストールします
  2. 現在のメタモジュールをアンインストールします
  3. 再起動します
  4. 新しいメタモジュールをインストールします
  5. 通常のモジュールを再インストールします
  6. 再度再起動します

モジュール開発者向け

通常の KernelSU モジュールを開発している場合、メタモジュールについてあまり心配する必要はありません。ユーザーが互換性のあるメタモジュール(meta-overlayfs など)をインストールしていれば、モジュールは動作します。

知っておくべきこと:

  • マウントにはメタモジュールが必要: モジュール内の system ディレクトリは、ユーザーがマウント機能を提供するメタモジュールをインストールしている場合にのみマウントされます
  • コード変更不要: 既存のモジュールは変更なしで引き続き動作します

::: tip Magisk モジュール開発に精通している場合、メタモジュールをインストールすると、Magisk 互換のマウントを提供するため、モジュールは KernelSU でも同じように動作します。 :::

メタモジュール開発者向け

メタモジュールを作成すると、KernelSU がモジュールのインストール、マウント、アンインストールを処理する方法をカスタマイズできます。

基本要件

メタモジュールは、module.prop の特別なプロパティによって識別されます:

txt
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)プロパティは、これをメタモジュールとしてマークします。このプロパティがない場合、モジュールは通常のモジュールとして扱われます。

ファイル構造

メタモジュール構造:

txt
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/                  (必要に応じてシステムレス変更)
└── [その他のファイル]

メタモジュールは、特別なメタモジュールフックに加えて、すべての標準モジュール機能(ライフサイクルスクリプトなど)を使用できます。

フックスクリプト

メタモジュールは最大3つの特別なフックスクリプトを提供できます:

1. metamount.sh - マウントハンドラー

目的: 起動中にモジュールがマウントされる方法を制御します。

実行タイミング: post-fs-data ステージ中、モジュールスクリプトが実行される前。

環境変数:

  • MODDIR: メタモジュールのディレクトリパス(例: /data/adb/modules/my_metamodule)
  • すべての標準 KernelSU 環境変数

責任:

  • すべての有効なモジュールをシステムレスにマウントする
  • skip_mount フラグをチェックする
  • モジュール固有のマウント要件を処理する

::: danger 重要な要件 マウント操作を実行する際、ソース/デバイス名を "KSU" に設定する必要があります。これにより、マウントが KernelSU に属していることが識別されます。

例(正しい):

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

最新のマウント API の場合、ソース文字列を設定します:

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

これは、KernelSU がマウントを適切に識別して管理するために不可欠です。 :::

スクリプト例:

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

# 例: シンプルなバインドマウント実装
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

ユースケース:

  • ファイルを処理する
  • シンボリックリンクをクリーンアップする
  • 割り当てられたリソースを解放する
  • 内部追跡を更新する

スクリプト例:

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

実行順序

起動実行順序を理解することは、メタモジュール開発にとって重要です:

txt
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 はシンボリックリンクを作成します:

sh
/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 がマウントハンドラーを実装する方法は次のとおりです:

sh
#!/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 マウント:

  • 真のシステムレス変更のためのカーネル overlayfs を使用
  • 複数のパーティション(system、vendor、product、system_ext、odm、oem)をサポート
  • /data/adb/modules/.rw/ を介した読み書きレイヤーサポート

ソース識別:

rust
// meta-overlayfs/src/mount.rs から
fsconfig_set_string(fs, "source", "KSU")?;  // 必須!

これにより、すべてのオーバーレイマウントに対して dev=KSU が設定され、適切な識別が可能になります。

ベストプラクティス

メタモジュールを開発する際:

  1. マウント操作には常にソースを "KSU" に設定する - カーネルアンマウントと zygisksu アンマウントが正しくアンマウントするためにこれが必要です
  2. エラーを適切に処理する - 起動プロセスは時間に敏感です
  3. 標準フラグを尊重する - skip_mount と disable をサポートします
  4. 操作をログに記録する - デバッグには echo またはロギングを使用します
  5. 徹底的にテストする - マウントエラーは起動ループを引き起こす可能性があります
  6. 動作を文書化する - メタモジュールが何をするかを明確に説明します
  7. 移行パスを提供する - ユーザーが他のソリューションから切り替えるのを支援します

メタモジュールのテスト

リリース前に:

  1. クリーンな KernelSU セットアップでインストールをテストする
  2. さまざまなモジュールタイプでマウントを検証する
  3. 一般的なモジュールとの互換性をチェックする
  4. アンインストールとクリーンアップをテストする
  5. 起動パフォーマンスを検証する(metamount.sh はブロッキングです!)
  6. 起動ループを避けるために適切なエラー処理を確保する

よくある質問

メタモジュールは必要ですか?

ユーザー向け: マウントが必要なモジュールを使用したい場合のみ。スクリプトを実行するだけでシステムファイルを変更しないモジュールのみを使用する場合は、メタモジュールは必要ありません。

モジュール開発者向け: いいえ、通常どおりモジュールを開発します。モジュールがマウントを必要とする場合にのみ、ユーザーはメタモジュールが必要です。

上級ユーザー向け: マウント動作をカスタマイズしたい場合、または代替マウント実装を作成したい場合のみ。

複数のメタモジュールを持つことはできますか?

いいえ。一度に1つのメタモジュールのみインストールできます。これにより、競合が防止され、予測可能な動作が保証されます。

唯一のメタモジュールをアンインストールするとどうなりますか?

モジュールはマウントされなくなります。デバイスは正常に起動しますが、別のメタモジュールをインストールするまで、モジュールの変更は適用されません。

meta-overlayfs は必須ですか?

いいえ。ほとんどのモジュールと互換性のある標準の overlayfs マウントを提供します。異なる動作が必要な場合は、独自のメタモジュールを作成できます。

関連項目