バックアップとリストア

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ファイル

重要なお知らせ

• 組み込みデータベースの認証情報およびNamespaceに関連する認可ルールは、個別のNamespace単位でのエクスポートやインポートはできません。これらのレコードをバックアップまたはリストアするには、グローバルバックアップを使用してください。グローバルバックアップはすべてのNamespaceのレコードをまとめて処理します。
• バックアップには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に存在しない場合は挿入され（insert）、競合がある場合は更新されます（update）。インポート処理は既存のEMQXクラスターのデータを削除しません。

特記事項

稀に、既存データとインポートデータの互換性がない場合があります。例えば、EMQXクラスターが組み込みデータベース認証を使用し、saltの位置を「suffix」に設定している一方で、インポートデータは「prefix」に設定している場合です。インポート後は新しい設定が有効となり、以前作成された古いユーザー認証情報は機能しなくなります。

そのため、データをクリアせずに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または特定のNamespaceでバックアップファイルを管理できます。Namespace管理者は割り当てられたNamespace内のバックアップファイルを管理およびダウンロードできますが、Globalや他のNamespaceのバックアップファイルにはアクセスできません。

TIP

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

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

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

   Namespace管理者はセレクターが表示されず、割り当てられたNamespaceのバックアップ操作に制限されます。

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

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

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

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

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

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

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

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のバックアップファイルに適用されます。Namespace管理者の場合、EMQXはこのパラメータを無視し、割り当てられたNamespaceに操作を適用します。

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_dir "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