バックアップとリストア

EMQXは分散ストレージスキーマを採用しており、システムの高可用性を確保するためにクラスター転送機能も導入しています。

このページでは、システム障害時のデータ損失を防ぐために、運用データおよび設定ファイルのバックアップ方法について説明します。

機能説明

EMQXはデータのインポートおよびエクスポートを実現するCLIコマンドを提供しており、バックアップとリカバリーを行えます。EMQX 4.xのコマンドと似ていますが、エクスポートファイルの形式は4.xとは互換性がありません。

• EMQX 4.xでは、EMQXの設定と組み込みデータベースの必要なデータをすべて単一のJSONファイルに保存していました。
• EMQX 5.xでは、エクスポートされたデータがtarファイル形式で圧縮されており、大量のユーザーデータをより効率的かつ構造的に扱えます。

CLIコマンドに加え、EMQX EnterpriseではEMQXダッシュボードにデータバックアップとリカバリーのページがあり、そこでデータのインポートとエクスポートが可能です。

EMQXがインポートおよびエクスポートをサポートするデータは以下の通りです。

• EMQXの設定リライトファイルの内容：
  • 認証および認可設定
  • ルール、コネクター、Sink/Source
  • リスナー、ゲートウェイ設定
  • その他EMQX設定
• 組み込みデータベース（Mnesia）データ
  • ダッシュボードユーザーおよびREST APIキー
  • クライアント認証資格情報（組み込みデータベースのパスワード認証、強化認証）
  • PSK認証データ
  • 認可ルール
  • ブラックリストデータ
  • 保持メッセージ
• EMQXデータディレクトリ（node.data_dir）に保存されたSSL/TLS証明書
• EMQXデータディレクトリに保存された認可用acl.confファイル

重要なお知らせ

• 組み込みデータベースの認証資格情報およびネームスペースに関連する認可ルールは、個別のネームスペース単位でのエクスポートやインポートはできません。これらのレコードをバックアップまたはリストアするにはグローバルバックアップを使用してください。グローバルバックアップはすべてのネームスペースのレコードをまとめて処理します。
• バックアップにはEMQXデータディレクトリに保存されたSSL/TLS証明書およびacl.confファイルのみが含まれます。バックアップをインポートする前に、データディレクトリ外に保存されている証明書やacl.confファイルは別途適切な場所にコピーしてください。

バックアップファイルの詳細

• エクスポートされるファイル名の形式はemqx-export-YYYY-MM-DD-HH-mm-ss.sss.tar.gzで、エクスポート先ディレクトリは<EMQX data directory>/backupです。
• EMQX v5.7.1以降では、保持メッセージの保存方法がram（メモリ）に設定されていてもバックアップされます。

エクスポート

データは稼働中の任意のクラスターのノードからエクスポート可能です。

EMQX 6.3.0以降、エクスポートされたバックアップにはノードのセキュリティプロファイルがMETA.hoconに記録されます。EMQXはインポート時にこのメタデータを用いてプロファイルの互換性をチェックします。

インポート

データをインポートするにはEMQXノードが稼働中である必要があり、インポート操作が成功するためには以下の条件を満たす必要があります。

• コアノード＋レプリカノードモードが有効な場合、データのインポートはコアノードでのみ実行可能です。実際のインポート動作には影響しません。データはコアノードおよびレプリカノードを含むすべてのクラスターのノードにレプリケートされます。コアノードで操作することで正しいデータインポートが保証されます。
• データファイルの名前を変更してはいけません。

上記の条件を満たさない場合、インポート処理は中止され、対応するエラーメッセージが表示されます。

データインポート中は、対象のEMQXクラスターに存在しないデータは挿入され、競合がある場合は更新されます。既存のデータが削除されることはありません。

注意事項

まれに既存データとインポートデータの互換性がない場合があります。例えば、EMQXクラスターが組み込みデータベース認証を使用し、ソルトの位置を「サフィックス（接尾）」に設定している一方、インポートデータが「プレフィックス（接頭）」に設定している場合、インポート後は新しい設定が有効となり、以前作成した古いユーザー資格情報は機能しなくなります。

したがって、データをクリアせずにEMQXクラスターにデータをインポートする場合は十分に注意してください。

セキュリティプロファイルの互換性

セキュリティプロファイルはノードのセキュリティ関連のデフォルト動作セットを選択します。EMQXはlegacyとhardenedのプロファイルを提供しています。EMQX 6.3.0以降、インポート時にバックアップに記録されたセキュリティプロファイルをチェックします。バックアップファイルのアップロード時にはこのチェックは実行されず、データの復元も行われません。

バックアップのセキュリティプロファイル	対象ノードのセキュリティプロファイル	デフォルトのインポート結果
hardened	hardened	許可される
legacy	hardened	明示的に不一致を許可しない限り拒否される
EMQX 6.3.0以前に作成されたバックアップなど、セキュリティプロファイルのメタデータがない場合	hardened	legacyとして扱われ、明示的に不一致を許可しない限り拒否される
任意のプロファイル	legacy	許可される

この表はセキュリティプロファイルチェックのみを示しています。不一致を許可するとこのチェックのみがバイパスされ、その他のバックアップ互換性チェックはすべて適用されます。

重要なお知らせ

legacyで取得されたデータをhardenedノードにリストアすると、復元後のデプロイメントの挙動が変わる可能性があります。

• node.default_listener_addressが設定されていない対象ノードでは、ポートのみ設定されたMQTTおよびダッシュボードのHTTPリスナーは全ネットワークインターフェースではなくループバックにバインドされます。
• 空または完全に無効化された認証チェーンはすべてのクライアントを拒否します（許可しません）。
• 復元されたダッシュボードアカウントでデフォルトパスワードを使用している場合、ログインできません。
• legacyでは無視されていた認証および認可バックエンドの失敗が操作拒否の原因となります。

セキュリティプロファイルの違いについてはセキュリティプロファイルの違いを確認のうえ、不一致を許可してください。

ダッシュボードでのバックアップファイル管理

グローバル管理者はGlobalまたは特定のネームスペースでバックアップファイルを管理できます。ネームスペース管理者は割り当てられたネームスペースのバックアップファイルを管理およびダウンロードできますが、Globalや他のネームスペースのバックアップファイルにはアクセスできません。

TIP

• ダッシュボードによるバックアップとリカバリーはEMQX Enterpriseエディションv5.4.0以降で利用可能です。
• CLIでエクスポートしたバックアップファイルもダッシュボードのバックアップとリカバリー画面で管理できます。

1. ダッシュボードにログインし、System -> Backup & Restoreに移動します。

2. グローバル管理者の場合、ネームスペースセレクターからGlobalまたは特定のネームスペースを選択します。選択したスコープのバックアップファイル一覧が読み込まれます。ネームスペースを選択した場合、一覧上部の通知で対象ネームスペースを確認してください。

   ネームスペース管理者はセレクターが表示されません。EMQXは割り当てられたネームスペースにバックアップ操作を制限します。

3. データをエクスポートするにはCreateをクリックします。グローバル管理者はGlobalビューでのみバックアップを作成できます。特定のネームスペースを選択した場合、Createは無効になります。ネームスペース管理者は割り当てられたネームスペースのバックアップを作成できます。

   バックアップファイル一覧には以下の情報が表示されます。

   • File Name：バックアップファイル名
   • Node Name：バックアップファイルが保存されているノード名。バックアップがそのノードのみのデータを含むわけではありません。
   • Created At：バックアップ作成日時
   • File Size：バックアップファイルサイズ

4. 選択したスコープにバックアップファイルを追加するにはUploadをクリックします。ファイルのアップロードはデータの復元を行いません。特定のネームスペースにアップロードした場合、成功メッセージに対象ネームスペースが表示されます。アップロード成功後、ファイルがバックアップファイル一覧に表示されていることを確認してください。

5. バックアップファイルを管理するには、Actions列の以下のボタンをクリックします。

   • Download：バックアップファイルをローカルデバイスにダウンロードします。
   • Delete：選択したスコープからバックアップファイルを削除します。
   • Restore：選択したスコープにバックアップファイルをインポートします。特定のネームスペースを選択している場合、復元確認ダイアログで対象ネームスペースを確認してください。Allow Security Profile Mismatchのチェックボックスはデフォルトでオフです。セキュリティプロファイルの互換性を確認しリスクを受け入れた場合のみ選択してください。復元成功後、成功メッセージに対象ネームスペースが表示されていることを確認してください。

特定ネームスペースビューではアップロード、ダウンロード、削除、復元操作はそのネームスペースに適用されます。グローバル管理者はこのビューでバックアップファイルを管理および復元できますが、バックアップの作成はできません。

REST APIによるバックアップファイル管理

グローバル管理者は以下のエンドポイントに対してオプションのnamespaceクエリパラメーターを渡せます。

• GET /api/v5/data/files：バックアップファイル一覧取得
• POST /api/v5/data/files：バックアップファイルアップロード
• GET /api/v5/data/files/{filename}：バックアップファイルダウンロード
• DELETE /api/v5/data/files/{filename}：バックアップファイル削除
• POST /api/v5/data/import：バックアップファイルインポート

グローバル管理者がnamespaceを省略した場合、操作はGlobalのバックアップファイルに適用されます。ネームスペース管理者の場合、EMQXはこのパラメーターを無視し、割り当てられたネームスペースに操作を適用します。

POST /api/v5/data/importのリクエストボディのオプションallow_security_profile_mismatchはデフォルトでfalseです。legacyプロファイルでエクスポートされたバックアップやセキュリティプロファイルのメタデータがないバックアップをhardenedノードに互換性リスクを受け入れてインポートする場合のみtrueに設定してください。例：

{
  "filename": "emqx-export-2026-09-01-08-30-00.000.tar.gz",
  "allow_security_profile_mismatch": true
}

CLI例

このセクションではコマンドラインインターフェースを使ったデータのインポートとエクスポート方法を示します。

1. データをエクスポートします。エクスポートファイルの名前形式はemqx-export-YYYY-MM-DD-HH-mm-ss.sss.tar.gzで、エクスポート先ディレクトリは<EMQX data directory>/backupです。

   $ ./emqx ctl data export
   "data/backup/emqx-export-2023-06-19-15-14-19.947.tar.gz"へのデータエクスポートを開始しています...
   クラスター設定をエクスポートしています...
   EMQXデータディレクトリから追加ファイルをエクスポートしています: "data"...
   組み込みデータベースをエクスポートしています...
   emqx_adminデータベーステーブルをエクスポートしています...
   emqx_authn_mnesiaデータベーステーブルをエクスポートしています...
   emqx_enhanced_authn_scram_mnesiaデータベーステーブルをエクスポートしています...
   emqx_appデータベーステーブルをエクスポートしています...
   emqx_aclデータベーステーブルをエクスポートしています...
   emqx_pskデータベーステーブルをエクスポートしています...
   emqx_bannedデータベーステーブルをエクスポートしています...
   データは正常にdata/backup/emqx-export-2023-06-19-15-14-19.947.tar.gzにエクスポートされました。

2. データをインポートします。インポートするファイル名は絶対パスまたは相対パスで指定可能です。ファイルが<EMQX data directory>/backupディレクトリにある場合はパスなしのベース名でも指定できます。例：

   # 絶対パスでファイルをインポート
   $ ./emqx ctl data import /tmp/emqx-export-2023-06-19-15-14-19.947.tar.gz
   "/tmp/emqx-export-2023-06-19-15-14-19.947.tar.gz"からデータをインポートしています...
   クラスター設定をインポートしています...
   組み込みデータベースをインポートしています...
   emqx_bannedデータベーステーブルをインポートしています...
   emqx_pskデータベーステーブルをインポートしています...
   emqx_aclデータベーステーブルをインポートしています...
   emqx_appデータベーステーブルをインポートしています...
   emqx_enhanced_authn_scram_mnesiaデータベーステーブルをインポートしています...
   emqx_authn_mnesiaデータベーステーブルをインポートしています...
   emqx_adminデータベーステーブルをインポートしています...
   データは正常にインポートされました。
   
   # EMQXルートディレクトリからの相対パスでファイルをインポート
   $ ./emqx ctl data import ../../../tmp/emqx-export-2023-06-21-13-28-06.418.tar.gz
   "../../../tmp/emqx-export-2023-06-21-13-28-06.418.tar.gz"からデータをインポートしています...
   クラスター設定をインポートしています...
   組み込みデータベースをインポートしています...
   emqx_enhanced_authn_scram_mnesiaデータベーステーブルをインポートしています...
   emqx_authn_mnesiaデータベーステーブルをインポートしています...
   emqx_adminデータベーステーブルをインポートしています...
   emqx_aclデータベーステーブルをインポートしています...
   emqx_bannedデータベーステーブルをインポートしています...
   emqx_pskデータベーステーブルをインポートしています...
   emqx_appデータベーステーブルをインポートしています...
   データは正常にインポートされました。
   
   # `<EMQX data directory>/backup`ディレクトリからファイルをインポート
   $ cp /tmp/emqx-export-2023-06-21-13-28-06.418.tar.gz /opt/emqx/data/backup/
   $ ./emqx ctl data import emqx-export-2023-06-21-13-28-06.418.tar.gz
   "data/backup/emqx-export-2023-06-21-13-28-06.418.tar.gz"からデータをインポートしています...
   クラスター設定をインポートしています...
   組み込みデータベースをインポートしています...
   emqx_enhanced_authn_scram_mnesiaデータベーステーブルをインポートしています...
   emqx_authn_mnesiaデータベーステーブルをインポートしています...
   emqx_adminデータベーステーブルをインポートしています...
   emqx_aclデータベーステーブルをインポートしています...
   emqx_bannedデータベーステーブルをインポートしています...
   emqx_pskデータベーステーブルをインポートしています...
   emqx_appデータベーステーブルをインポートしています...
   データは正常にインポートされました。

   legacyプロファイルでエクスポートされたバックアップやセキュリティプロファイルのメタデータがないバックアップを互換性リスクを確認したうえでhardenedノードにインポートする場合は、--allow-security-profile-mismatchを付けて実行してください。

   ./emqx ctl data import emqx-export-2026-09-01-08-30-00.000.tar.gz --allow-security-profile-mismatch