インストールとマイグレーション
本章では、EMQXの基本的なインストール手順、最低限のハードウェア仕様、および将来の設定や保守作業を容易にするためのファイルおよびディレクトリの場所について説明します。また、EMQX Enterpriseのライセンス設定方法や、EMQX 4.4からEMQX 5.1へのマイグレーション方法についても解説します。
サポートされているオペレーティングシステム
以下の表は、EMQXがサポートするオペレーティングシステムとそのバージョンを示しています。
| オペレーティングシステム | サポートされているバージョン | x86_64/amd64 | arm64 |
|---|---|---|---|
| Ubuntu | Ubuntu 22.04 Ubuntu 24.04 | Yes | Yes |
| Debian | Debian 11 Debian 12 Debian 13 | Yes | Yes |
| CentOS/RHEL | Rocky Linux 8 Rocky Linux 9 Rocky Linux 10 | Yes | Yes |
| Amazon Linux | Amazon Linux 2023 | Yes | Yes |
| macOS 14+ | macOS 14 macOS 15 macOS 26 | No | Yes |
インストール環境
EMQXを動作させるErlang VMは、ファイル名や対話型Erlangシェルの端末IOなど、さまざまな機能でUnicodeサポートを有効にするためにシステムのロケール設定に依存しています。
Linux OSを使用する場合は、EMQXを起動する前にシステム環境でUTF-8ロケールが有効になっていることを確認することを推奨します。以下のタブから、各プラットフォームでUTF-8ロケールを有効にする方法をご覧ください。
ポート使用状況
EMQXはデフォルトで以下のポートを使用します。これらのポートが他のアプリケーションで占有されていないことを確認し、必要に応じてファイアウォールを開放してEMQXが正常に動作するようにしてください。
| ポート | プロトコル | 説明 |
|---|---|---|
| 1883 | TCP | TCPによるMQTTリスナーポート。主に暗号化されていないMQTT接続に使用されます。 |
| 8883 | TCP | SSL/TLSによるMQTTリスナーポート。暗号化されたMQTT接続に使用されます。 |
| 8083 | TCP | WebSocketによるMQTTリスナーポート。WebSocket経由のMQTT通信に使用されます。 |
| 8084 | TCP | WSS（SSL上のWebSocket）によるMQTTリスナーポート。暗号化されたWebSocket接続に使用されます。 |
| 18083 | HTTP | EMQXダッシュボードおよびREST APIのポート。管理コンソールおよびAPIインターフェース用。 |
| 4370 | TCP | Erlang分散ポート。実際のポートはノード名に応じてBasePort (4370) + Offsetとなります。 |
| 5370 | TCP | クラスターRPCポート（Docker環境では5369）。実際のポートはノード名に応じてBasePort (5370) + Offsetとなります。 |
注意
クラスターを形成していなくても、EMQXはポート4370および5370をリッスンします。これら2つのポートは固定で変更できません。Offsetはノード名のName部分（Name@Host）の数値サフィックスによって決まります。数値サフィックスがない場合はデフォルトで0です。詳細はポートマッピングを参照してください。
ファイルとディレクトリ
インストール後、EMQXは実行ファイルや設定ファイル、データ、ログを格納するためのいくつかのディレクトリを作成します。以下の表は、異なるインストール方法ごとに作成されるディレクトリとそのパスを示しています。
| ディレクトリ | 説明 | tar.gzでインストール時のパス | RPM/DEBでインストール時のパス |
|---|---|---|---|
etc | 静的設定ファイル | ./etc | /etc/emqx |
data | データベースおよび設定 | ./data | /var/lib/emqx |
log | ログファイル | ./log | /var/log/emqx |
releases | ブート指示ファイル | ./releases | /usr/lib/emqx/releases |
bin | 実行ファイル | ./bin | /usr/lib/emqx/bin |
lib | Erlangコード | ./lib | /usr/lib/emqx/lib |
erts-* | Erlangランタイム | ./erts-* | /usr/lib/emqx/erts-* |
plugins | プラグイン | ./plugins | /usr/lib/emqx/plugins |
EMQX 6.3.0以降、RPMおよびDEBパッケージは/opt/emqxを作成し、上記のFilesystem Hierarchy Standardパスへのシンボリックリンクを配置します。これにより、オペレーターやスクリプトはDockerイメージと同じ/opt/emqx/...パスを使用できます。
| シンボリックリンク | 実体パス |
|---|---|
/opt/emqx/bin | /usr/lib/emqx/bin |
/opt/emqx/data | /var/lib/emqx |
/opt/emqx/etc | /etc/emqx |
/opt/emqx/lib | /usr/lib/emqx/lib |
/opt/emqx/log | /var/log/emqx |
/opt/emqx/plugins | /usr/lib/emqx/plugins |
/opt/emqx/releases | /usr/lib/emqx/releases |
/opt/emqx/erts-* | /usr/lib/emqx/erts-* |
パッケージのインストールやアップグレード時にこれらのシンボリックリンクが作成または更新されます。アンインストール時にはこれらが削除され、/opt/emqxが空の場合のみディレクトリも削除されます。/opt/emqx直下に直接追加された他のコンテンツは保持されます。
シンボリックリンクは常に上記の実体パスを指します。カスタムのデータ、ログ、プラグインディレクトリを設定しても対応するシンボリックリンクは更新されません。
TIP
- 圧縮パッケージでインストールした場合、ディレクトリはソフトウェアをインストールしたディレクトリに対する相対パスです。
- Dockerコンテナでインストールした場合、EMQXは
/opt/emqxディレクトリにインストールされます。 data、log、pluginsディレクトリは設定ファイルで変更可能です。パフォーマンス向上のため、dataディレクトリを高速ディスクにマウントすることを推奨します。同じクラスターに属するノードでは、dataディレクトリの設定を統一してください。クラスターの詳細はクラスターを参照してください。
以下の表は、一部ディレクトリのファイルやサブフォルダの説明です。
| ディレクトリ | 説明 | パーミッション | ファイル |
|---|---|---|---|
| bin | 実行ファイル | 読み取り | emqx と emqx.cmd: EMQXの実行ファイル。詳細はコマンドラインインターフェースを参照してください。 |
| etc | 設定ファイル | 読み取り | base.hocon: ランタイム設定変更で上書き可能なベース設定。emqx.conf: 上書き不可の静的設定。emqx-example-en.conf: EMQXのデモ設定ファイル。全設定項目を含む。acl.conf: デフォルトのACLルール。vm.args: Erlang仮想マシンの動作パラメータ。certs/: EMQXのSSLリスナー用X.509鍵および証明書ファイル。外部システム連携時のSSL/TLS接続にも使用可能。 |
| data | 動作データ | 書き込み | authz: REST APIやダッシュボードからアップロードされたファイル認可ルールを保存。詳細は認可 - ファイルを参照。certs: REST APIやダッシュボードからアップロードされた証明書ファイルを保存。configs: 起動時に生成された設定ファイルやAPI・CLIからの設定上書きを保存。mnesia: EMQXの動作データを格納する組み込みデータベース。アラーム記録、クライアントの認証・認可情報、ダッシュボードユーザー情報などを含む。このディレクトリを削除すると、これらの動作データはすべて失われます。— ノードごとに名前が付けられたサブディレクトリを含む場合があります（例： emqx@127.0.0.1）。ノード名変更時は対応するサブディレクトリも削除または移動してください。— 組み込みデータベースの照会には emqx ctl mnesiaコマンドを使用します。詳細は管理コマンドCLIを参照。patches: EMQXがホットパッチとしてロードする.beamファイルを保存。迅速な修正に利用可能。trace: オンライントレースログファイル。本番環境では、データ安全のため dataディレクトリ（traceフォルダを除く）を定期的にバックアップすることを推奨します。 |
| log | 動作ログ | 読み取り | emqx.log.*: EMQXの動作ログ。詳細はログを参照してください。 |
TIP
EMQXは設定情報をdata/configsとetcディレクトリに保存します。etcディレクトリは読み取り専用の設定ファイルを格納し、ダッシュボードやREST APIからの設定更新はdata/configsに保存され、ランタイムでのホットリロードをサポートします。
etc/base.hocon: ランタイム設定変更で上書き可能なベース設定。etc/emqx.conf: 上書き不可の静的設定。data/configs/cluster.hocon: ランタイム設定の上書き。
EMQXはこれらのファイルから設定項目を読み込み、Erlangネイティブの設定ファイル形式に変換してランタイムに適用します。