# Usage FAQs

## ライセンスが期限切れになるとどうなりますか？

EMQX Enterpriseユーザーの場合、ライセンスの有効期限が切れると、ノード起動時に期限切れを通知する警告が表示されます。ライセンスタイプによっては、追加の制限が適用されることがあります。

- **「小規模」顧客向けまたはトライアルライセンスの場合：** ライセンスで指定された接続数の上限に達していなくても、新しいMQTT接続は許可されません。既存の接続は切断されませんが、切断された場合は再接続できません。
- **「小規模」顧客向けまたはトライアル以外のライセンスの場合：** 総接続数が最大制限を超えない限り、新しいMQTT接続は許可されます。

ご自身のライセンスタイプが不明な場合は、担当のアカウントマネージャーにご確認ください。

## ライセンスはどのように更新しますか？

以下のコマンドでEMQX Enterpriseライセンスを更新できます。

```bash
./bin/emqx ctl 

    license info             # ライセンス情報を表示
    license update <License> # 文字列として与えられたライセンスを更新
```

また、ダッシュボードからもライセンスを更新可能です。ライセンスの申請方法やダッシュボードを使った更新手順については、[EMQX Enterpriseライセンスの操作](deploy/license.md)をご参照ください。

## 共有サブスクリプションを使用しているときにリテインドメッセージを受信できないのはなぜですか？

MQTTプロトコルにより、クライアントが共有サブスクリプションを使用している場合、サーバーはそのクライアントにリテインドメッセージを送信してはなりません。

## 共有サブスクリプションを使用しているときにメッセージが時々失われるのはなぜですか？

共有サブスクライバーの接続が切断されてもセッションがアクティブな場合、サーバーは引き続きそのサブスクライバーにメッセージを配信し、メッセージはセッション内に一時的に保存されます。そのため、他のアクティブな共有サブスクライバーはすべてのメッセージを消費していないように見えることがあります。さらに、共有サブスクライバーが再接続時に新しいセッションを作成することを選択した場合、古いセッションにキャッシュされたメッセージは永久に失われます。

上記の状況が存在しないことを確認してもメッセージロスが続く場合は、[ログトレース](../guides/observability/tracer.md)を使用して詳細調査を行ってください。

## SSL/TLS接続失敗の原因をどのようにトラブルシュートしますか？

通常、SSL/TLS接続のハンドシェイクが失敗すると、EMQXは[ログ](../guides/observability/log.md)に失敗理由を出力します。以下はログに現れる一般的なキーワードとその意味です。

- certificate_expired

   `certificate_expired` キーワードがログに現れた場合、証明書が期限切れであることを示します。速やかに更新してください。

- no_suitable_cipher

   `no_suitable_cipher` キーワードがログに現れた場合、ハンドシェイク中に適切な暗号スイートが見つからなかったことを示します。考えられる原因は、証明書の種類が暗号スイートと一致しない、サーバーとクライアントの両方でサポートされる暗号スイートが見つからないなどです。

- handshake_failure

   `handshake_failure` キーワードがログに現れた場合、原因は多岐にわたります。クライアントが報告するエラーと合わせて分析してください。例えば、クライアントが接続先サーバーのアドレスがサーバー証明書のドメイン名と一致しないと判断する場合などがあります。

- unknown_ca

   `unknown_ca` キーワードがログに現れた場合、証明書の検証に失敗したことを意味します。一般的な原因は、中間CA証明書の省略、ルートCA証明書の指定漏れ、または誤ったルートCA証明書の指定です。双方向認証の場合、ログの他の情報からサーバーまたはクライアントの証明書設定の誤りを判断できます。

   サーバー証明書に問題がある場合、エラーログは通常以下のようになります。

   ```
   {ssl_error,{tls_alert,{unknown_ca,"TLS server: In state certify received CLIENT ALERT: Fatal - Unknown CA\n"}}}
   ```

   `CLIENT ALERT` はクライアントからの警告メッセージであり、サーバー証明書がクライアントの検証に失敗したことを示します。

   クライアント証明書に問題がある場合、エラーログは通常以下のようになります。

   ```
   {ssl_error,{tls_alert,{unknown_ca,"TLS server: In state certify at ssl_handshake.erl:1887 generated SERVER ALERT: Fatal - Unknown CA\n"}}}
   ```

   `SERVER ALERT` はサーバーがクライアント証明書の認証に失敗したことを示し、クライアントはサーバーからこの警告メッセージを受け取ります。

- protocol_version

   `protocol_version` キーワードがログに現れた場合、クライアントとサーバーがサポートするTLSプロトコルのバージョンが一致していないことを示します。

## MQTTクライアントの異常切断の原因をどのようにトラブルシュートしますか？

Shellで `emqx ctl listeners` を実行すると、各リスナーの切断統計情報が返されます。切断理由や切断回数が含まれます。例：

```
$ . /bin/emqx ctl listeners
tcp:default
  listen_on : 0.0.0.0:1883
  acceptors : 16
  proxy_protocol : false
  running : true
  current_conn : 9
  max_conns : infinity
  shutdown_count : [{keepalive_timeout,1},{idle_timeout,2}]
```

一般的な切断理由は以下の通りです。

- `keepalive_timeout`：クライアントのハートビートがタイムアウトし、EMQXが接続を閉じた。
- `tcp_closed`：クライアントがDISCONNECTパケットを送信せずにTCP接続を直接閉じた。
- `frame_too_large`：クライアントが送信したパケットサイズが最大制限を超え、EMQXが接続を閉じた。
- `protocol_error`：クライアントの非準拠動作によりEMQXが接続を閉じた（例：同一接続内で複数のCONNECTパケットを送信）。
- `idle_timeout`：TCP接続確立後15秒以内にクライアントからCONNECTパケットを受信しなかったため、EMQXが接続を閉じた。

また、[ログトレース](../guides/observability/tracer.md)を利用して、指定したクライアントID、IP、トピックに関連するすべてのログを追跡し、切断原因を分析できます。

## ストレステスト実行時に接続数やスループットが期待より低い場合、システムをどのようにチューニングすればよいですか？

ストレステストを実行する際は、必要なハードウェアリソースの確保に加え、OSやErlang VMのチューニングも必要です。代表的なチューニング項目は、ファイルハンドルのグローバル制限およびユーザー制限、TCPのバックログやバッファ、Erlang VMのプロセス数制限などです。クライアント側のマシンも、すべてのサブスクライブおよびパブリッシュを処理できる能力とリソースを持っている必要があります。

ユースケースによって最適なチューニングは異なります。一般的なチューニング方法については、[パフォーマンスチューニング](../guides/performance/tune.md)をご参照ください。

## クライアント接続、パブリッシュ、サブスクライブに関する問題（接続失敗や異常切断など）が発生した場合、どのようにトラブルシュートすればよいですか？

EMQXのデバッグログにはすべての動作や現象が記録されています。デバッグログを確認することで、クライアントがいつ接続を開始し、接続時に指定したパラメーター、接続の成功・拒否の有無および拒否理由などを特定できます。ただし、デバッグモードでは大量の情報が記録されるため、個別のクライアントやトピックの分析は困難になることがあります。

これに対応するため、EMQXは[ログトレース](../guides/observability/tracer.md)機能を提供しています。トレースしたいクライアントやトピックを指定すると、それらに関連するすべてのデバッグログを指定のログファイルに出力します。これにより、自己分析やコミュニティへの問い合わせが容易になります。

なお、ネットワーク障害などでクライアントがEMQXに接続できない場合、EMQXはメッセージを受信しないため、ログトレース機能は役に立ちません。このような場合は、ファイアウォールやセキュリティグループなどのネットワーク設定によりサーバーポートが閉じられていることが多く、特にクラウド環境でEMQXをデプロイしている際に発生しやすいです。したがって、ログトレースに加えて、ポートの占有状況、リスニング状態、ネットワーク設定の確認も重要です。

## 「CENSYS」などのクライアントIDを持つ見慣れないクライアントがいるのはなぜですか？

CENSYSはIPv4アドレス空間を定期的にスキャンし、HTTP、SSH、MQTTなどの各種プロトコルのデフォルトポートを特定するインターネットスキャンおよび偵察ツールです。そのため、クライアントIDが「CENSYS」やその他の見慣れないクライアントがMQTTブローカーにアクセスしている場合、セキュリティ保護レベルが比較的低いことを示しています。この問題に効果的に対処するため、以下の対策を検討してください。

1. EMQXのHTTP APIアクセス権限検証に使用されるAppIDやAppSecretなど、デフォルト設定の使用を避ける。
2. パスワード認証やJWT認証などの認証機構を有効にし、IPアドレスの知識だけでログインできる状態を防止する。
3. TLS相互認証を有効にし、有効な証明書を持つクライアントのみアクセスを許可する。
4. 適切な認可機構を有効にし、認可されていないデバイスによる機密データへのアクセスを制限する。
5. ファイアウォールを設定し、不要なポートは可能な限り閉じる。

## ダッシュボードのログインパスワードを忘れた場合、どのようにリセットしますか？

ダッシュボードの初期ユーザー名とパスワードはそれぞれ `admin` と `public` です。セキュリティ上の理由から、初回ログイン時にパスワードの変更が強制されます。以前設定したパスワードを忘れた場合は、以下のコマンドで旧パスワードを入力せずに新しいパスワードを設定できます。

```bash
./bin/emqx ctl admins passwd <Username> <Password>
```