デプロイメントFAQ
EMQXのデプロイに推奨されるオペレーティングシステムは何ですか？
EMQXはさまざまなオペレーティングシステムおよびハードウェアプラットフォームで動作します。エンタープライズレベルの安定性と信頼性を考慮すると、一般的にCentOS、Ubuntu、DebianなどのLinuxディストリビューションでのデプロイを推奨しています。
EMQXの推奨デプロイメントプランは何ですか？
EMQXはクラスターでのデプロイを推奨しており、クラスターのフロントエンドにロードバランサー（Nginx、HAProxyなど）を配置して、クライアント接続を各ノードに均等に分散させることを推奨します。
通信のセキュリティ要件が高いユーザーには、クライアント側でTLS接続を有効にし、ロードバランサー側でTLS接続を終了させることを推奨します。つまり、クライアントとロードバランサー間はTLS暗号化通信を使用し、ロードバランサーとEMQXノード間はTCP通信を使用します。
EMQXノードはポートをパブリックネットワークに公開しないため、全体のセキュリティが低下することはありませんが、TLSのオフロードによりEMQXのリソース消費を効果的に節約できます。
デバイス数やメッセージスループットが少ない場合でもクラスターをデプロイする必要がありますか？
デバイス数が少なくメッセージスループットが低い場合でも、本番環境ではクラスターのデプロイが有効です。
クラスターはシステムの可用性を向上させ、単一障害点の発生を減らします。ノードがダウンしても、クラスター内の他の正常なノードがサービスを継続提供できるため、業務に影響を与えません。
EMQXが起動しない場合のトラブルシューティング方法は？
EMQXが起動しない場合は、ログディレクトリ内のemqx.log.Nまたはerlang.log.Nを確認して詳細なエラーを取得してください。
または、emqx consoleコマンドでコンソールからEMQXを起動すると、エラーログが直接コンソールに出力されます。ログ内容に基づき本ページの対応策を参照するか、GitHubでサポートを依頼してください。
EMQX起動時に「logger: command not found」というログが出る場合の対処法は？
以下の依存関係をインストールしてください。
CentOS/Redhat
$ yum install rsyslogUbuntu/Debian
$ apt-get install bsdutilsEMQX起動時にログに「...{on_load_function_failed,crypto}...」と表示される場合の対処法は？
セキュリティ向上のため、EMQXはバージョン4.3以降でopenssl-1.1を使用しています。これにより、一部の古いLinuxディストリビューションで問題が発生する場合があります。
EMQXバージョン4.3.10未満およびEMQX Enterpriseバージョンe4.3.5未満では、以下のようなエラーメッセージが表示されることがあります。
{application_start_failure,kernel,{{shutdown,{failed_to_start_child,kernel_safe_sup,{on_load_function_failed,crypto}}}, ..}それ以降のバージョンでは、以下のようなエラーメッセージが表示されることがあります。
FATAL: Unable to start Erlang.
Please make sure openssl-1.1.1 (libcrypto) and libncurses are installed.これは、EMQXが依存するErlang/OTPの「crypto」アプリケーションが、必要なopensslの動的ライブラリ（.soファイル）を見つけられず起動に失敗したことを示しています。以下の方法で対応してください。
重要なお知らせ
以下の解決策はあくまで例示です。
記載されているソースバージョンは現時点の知見に基づいて選択していますが、古くなっている場合や脆弱性が含まれている可能性があります。
最新のセキュリティアップデートを得るためには、OSのパッケージマネージャーからlibcryptoを直接インストールすることを推奨します。
DockerでEMQXを起動した際に「Permission denied」というログが出て起動に失敗する場合の対処法
EMQXのデータを永続化するためにディレクトリをマウントして起動する際、
sudo docker run -d --name emqx -p 18083:18083 -p 1883:1883 -v /emqx/data:/opt/emqx/data -v /emqx/log:/opt/emqx/log emqx:latest以下のようなエラーでコンテナの起動に失敗することがあります。
mkdir: cannot create directory '/opt/emqx/data/configs': Permission deniedこれは、コンテナ内のEMQXがLinuxユーザーemqxとして動作しているのに対し、ホスト側のマウント先ディレクトリがrootユーザーで作成されているため、EMQXがディレクトリやファイルを作成できないためです。
解決方法としては、ホスト側にemqxユーザーを作成し、そのユーザーでマウント対象ディレクトリを作成するか、作成済みのデータ・ログディレクトリの権限を777に変更してください。
ただし、最も推奨されるデータ永続化方法は名前付きデータボリュームを使用することで、権限問題を気にせずに済みます。
sudo docker volume create --name emqx-data
sudo docker volume create --name emqx-log
sudo docker run -d --name emqx -p 18083:18083 -p 1883:1883 -v emqx-data:/opt/emqx/data -v emqx-log:/opt/emqx/log emqx:latestEMQX起動時に「ポートが使用中（eaddrinuse）」と表示された場合はどうすればよいですか？
EMQXは起動時にデフォルトで7つのポートを使用します。これらは以下の通りです。
- ポート1883：MQTTのTCPリスナー用。設定で変更可能。
- ポート8883：MQTTのSSL/TLSリスナー用。設定で変更可能。
- ポート8083：MQTTのWebSocketリスナー用。設定で変更可能。
- ポート8084：MQTTのWSS（WebSocket over SSL）リスナー用。設定で変更可能。
- ポート18083：HTTP APIサービスのデフォルトリスニングポート。ダッシュボードもこのポートを使用。設定で変更可能。
- ポート4370：EMQX分散クラスターのリモート関数呼び出しおよびMnesiaデータ同期用。クラスターを形成していなくてもデフォルトで占有。リスニングポートは
BasePort (4370) + Offsetで決まり、4370は固定で変更不可。Offsetはノード名（Name@Host）の数字サフィックスで決まり、数字がなければ0。例：emqx@127.0.0.1のOffsetは0、emqx1@127.0.0.1のOffsetは1。 - ポート5370：クラスターRPCポートで負荷分散用。主にノード間のMQTTメッセージ転送に使用。ポート4370と同様に、クラスター未形成でもデフォルトで占有。実際のリスニングポートは
BasePort (5370) + Offsetで決まり、5370は固定で変更不可。Offsetはノード名のName部分の数字サフィックスで決まり、数字がなければ0。
EMQX起動時に「WARNING: Default (insecure) Erlang cookie is in use.」というログが出る理由は？
警告ログ全文は以下の通りです。
WARNING: Default (insecure) Erlang cookie is in use.
WARNING: Configure node.cookie in /usr/lib/emqx/etc/emqx.conf or override from environment variable EMQX_NODE__COOKIE
WARNING: NOTE: Use the same cookie for all nodes in the cluster.同じcookieを使用するEMQXノードのみがクラスターを形成できます。cookieはクラスター通信を保護するものではありませんが、意図しないクラスターへの接続を防止します。デフォルトではEMQXノードはemqxsecretcookieというcookie値を使用していますが、クラスター構築時にはセキュリティ強化のためcookie値の変更を推奨します。
2つ目の警告はcookieの変更方法を示しており、emqx.confのnode.cookie設定を編集するか、環境変数EMQX_NODE__COOKIEを設定する方法があります。
EMQX Dockerコンテナを再起動すると、設定したルールやリソースなどのデータが消えるのはなぜですか？
EMQXのランタイムデータは/opt/emqx/dataディレクトリに保存されており、設定ルール、リソース、保持メッセージなどが含まれます。コンテナ再起動時にデータ永続化を確保するには、/opt/emqx/dataディレクトリをホストのローカルディレクトリやデータボリュームにマウントする必要があります。
しかし、/opt/emqx/dataディレクトリを正しくマウントしていても、コンテナ再起動後にデータが消失する場合があります。これはEMQXのランタイムデータが/opt/emqx/data/mnesia/${Node Name}ディレクトリに保存されており、コンテナ再起動時にEMQXのノード名が変わるため新しいストレージディレクトリが作成されるためです。
EMQXのノード名はNameとHostで構成され、HostはデフォルトでコンテナのIPアドレスから取得されます。デフォルトネットワーク設定では、コンテナのIPが再起動時に変わる可能性があるため、コンテナに固定IPを割り当てる必要があります。
この問題に対処するため、EMQXは環境変数EMQX_HOSTを提供しており、ノード名のHost部分を設定できます。ただし、このHost値は他のノードから到達可能である必要があるため、ネットワークエイリアスと併用してください。以下はEMQX_HOST環境変数とネットワークエイリアスを指定してEMQX Dockerコンテナを起動する例です。
docker run -d --name emqx -p 18083:18083 -p 1883:1883 -e EMQX_HOST=alias-for-emqx --network example --network-alias alias-for-emqx --mount type=bind,source=/tmp/emqx,target=/opt/emqx/data emqx:5.8.3docker-composeで起動したコンテナが正常に起動しダッシュボードにアクセスできるにも関わらず、コンテナのステータスがunhealthyになる理由は？
docker-compose ps
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
emqx1 emqx/emqx:latest "/usr/bin/docker-ent…" emqx 120 seconds ago Up 110 seconds (unhealthy) 0.0.0.0:1883->1883/tcp, :::1883->1883/tcp, 0.0.0.0:18083->18083/tcp, :::18083->18083/tcpEMQXのヘルスチェックは./bin/emqx_ctl statusコマンドに依存しています。このコマンドが失敗すると、コンテナはunhealthy状態になります。
healthcheck:
test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
interval: 60s
timeout: 15s
retries: 3手動で./bin/emqx_ctl statusコマンドを実行した場合、
emqx@docker:/opt/emqx$ emqx_ctl status
Node emqx@docker not responding to pings.と表示される場合、コマンドがノードに接続できていません。これは通常、コンテナ起動時にネットワークがエイリアスを使用せず、FQDN形式でないためにノードが正しく特定できないことが原因です。
対策は以下の通りです。
- Dockerのホスト名をEMQXノード名に合わせる。
docker-compose.ymlにホスト名設定を追加する。
# xxx.yyy.zzz(docker.emqx.com)はFQDN形式である必要があります
hostname: docker.emqx.com
environment:
- EMQX_HOST=docker.emqx.comEMQXはdata/mnesia/<node name>ディレクトリにデータを保存するため、ノード名にIPアドレスではなくホスト名やFQDNのような固定識別子を使うことが重要です。ノード名が変わるとデータ損失の原因となります。
これを簡単にするために、EMQX Docker Compose Generatorを利用して本番環境向けのdocker-compose.ymlファイルを作成することを検討してください。