バックアップとリストア
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ノードが稼働中であり、以下の条件を満たす必要があります。
- ダッシュボードまたは
POST /api/v5/data/import経由でデータをインポートする場合、クラスター内のすべての稼働中ノードは同じメジャーおよびマイナーバージョンを使用している必要があります。パッチバージョンは異なっても構いません。ノードのバージョンがこの要件を満たさないか、ノードのバージョンが取得できない場合、EMQXはインポート開始前にリクエストを拒否し、HTTP400レスポンスとBAD_REQUESTエラーコードを返します。エラーメッセージには各ノードとそのmajor.minorバージョンが一覧表示され、バージョンが不明な場合はunknownと表示されます。再試行前に、すべての稼働中ノードのバージョンが取得可能であり、かつ同じメジャー・マイナーバージョンであることを確認してください。 - コアノード＋レプリカノードモードが有効な場合、データインポートはコアノードでのみ実行可能です。実際のインポート動作には影響なく、データはコアノードおよびレプリカノードを含むすべてのクラスター・ノードに複製されます。コアノードで操作することで正しいデータインポートが保証されます。
- データファイルの名前を変更してはいけません。
上記のいずれかの条件を満たさない場合、インポート処理は中断され、対応するエラーメッセージが表示されます。
データインポート中は、対象のEMQXクラスターに存在しないデータは挿入され、競合がある場合は更新されます。インポート処理は既存のデータを削除しません。
ネームスペース単位のインポート動作
EMQX 6.3.0以降、特定のネームスペースにバックアップをインポートする場合、そのネームスペースでサポートされる設定ルートのみが適用されます。バックアップ内のネームスペース設定にクラスター全体のルート（認証、認可、ExHook、リスナーなど）が含まれている場合、EMQXはそれらのルートをスキップし、グローバル設定には書き込みません。グローバルインポートではクラスター全体の設定が適用されます。
EMQXはスキップしたルートを一覧表示するdata_import_skipped_global_roots警告をログに記録し、同じバックアップのサポートされるルートのインポートを続行します。クラスター全体のルートのスキップはインポート全体の失敗にはなりません。CLI経由のインポートではコマンド出力にスキップされたルートが表示されます。ダッシュボードやREST API経由のインポートでは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でエクスポートしたバックアップファイルもダッシュボードのバックアップとリカバリページで管理できます。
ダッシュボードにログインし、System -> Backup & Restoreに移動します。
グローバル管理者の場合、ネームスペースセレクターからGlobalまたは特定のネームスペースを選択します。選択したスコープのバックアップファイル一覧が読み込まれます。ネームスペースを選択した場合、一覧上部の通知で対象ネームスペースを確認してください。
ネームスペース管理者はセレクターが表示されず、割り当てられたネームスペースのバックアップ操作に制限されます。
データをエクスポートするには、Createをクリックします。グローバル管理者はGlobalビューでのみバックアップを作成できます。特定のネームスペースを選択した場合、Createは無効化されます。ネームスペース管理者は割り当てられたネームスペースでバックアップを作成できます。
バックアップファイル一覧には以下の情報が表示されます。
- File Name：バックアップファイル名
- Node Name：バックアップファイルが保存されているノード名（バックアップがそのノードのデータのみを含むことを意味しません）
- Created At：バックアップ作成日時
- File Size：バックアップファイルサイズ
バックアップファイルを選択したスコープに追加するには、Uploadをクリックします。ファイルのアップロードはデータの復元を行いません。特定のネームスペースの場合、成功メッセージに対象ネームスペースが表示されます。アップロード成功後、バックアップファイル一覧にファイルが表示されていることを確認してください。
バックアップファイルを管理するには、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のバックアップファイルに適用されます。ネームスペース管理者の場合、パラメーターは無視され、割り当てられたネームスペースに操作が適用されます。
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例
このセクションでは、コマンドラインインターフェースを使用したデータのインポートおよびエクスポート方法を示します。
データをエクスポートします。エクスポートされるファイル名の形式は
emqx-export-YYYY-MM-DD-HH-mm-ss.sss.tar.gzで、エクスポート先ディレクトリは<EMQX data directory>/backupです。bash$ ./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にエクスポートされました。データをインポートします。インポートするファイル名は絶対パスまたは相対パスで指定できます。ファイルが
<EMQX data directory>/backupディレクトリにある場合は、パスなしのベース名でも指定可能です。例：bash# 絶対パスでファイルをインポート $ ./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を付加してください。bash./emqx ctl data import emqx-export-2026-09-01-08-30-00.000.tar.gz --allow-security-profile-mismatch