# ファイルからシークレットを読み込む

多くのEMQX設定フィールドには機密性の高い値が含まれます。例えば、SSLリスナーのキーのパスフレーズ、ブリッジやコネクターのパスワード、OIDCクライアントシークレット、S3のシークレットアクセスキー、APIキーなどです。これらの値を`emqx.conf`やAPIリクエストに直接埋め込むことを避けるために、EMQXはシークレット型フィールドに対して`file://` URLプレフィックスをサポートしています。EMQXは起動時および設定のリロード時に参照されたファイルからシークレットを読み込みます。

## 構文

シークレットとしてドキュメント化されているフィールド（またはダッシュボードのツールチップに`file://`オプションが記載されているフィールド）には、以下の形式を使用します。

```text
file://<path-to-file>
```

パスは絶対パスでもEMQXの作業ディレクトリからの相対パスでもかまいません。ファイルの内容全体がシークレット値として使用されますが、以下の変換が行われます。

- 末尾の空白文字は削除されます。改行、キャリッジリターン、スペース、タブのいずれかの末尾文字が除去されます。先頭および内部の内容はそのまま使用されます。

例：

```hocon
# ファイルから読み込むSSLリスナーのキーのパスフレーズ
listeners.ssl.default.ssl_options.password = "file://etc/certs/key-passphrase"

# ファイルから読み込むMQTTブリッジのパスワード
bridges.mqtt.upstream.password = "file:///run/secrets/upstream-mqtt-password"
```

## クラスターでの考慮事項

EMQXをクラスターで運用する場合、設定を読み込むすべてのノードがファイルパスを解決できる必要があります。

- 設定を読み込むすべてのEMQXノードにファイルが存在している必要があります。同じパスはノードごとに異なるファイルを指し示します。EMQXはノード間でファイルをコピーしません。
- ファイルの内容はノード間で一致している必要があります。そうでないと、同じ設定フィールドに対して異なるノードが異なるシークレット値を使用することになります。
- ダッシュボードやREST API経由で設定を変更した場合、その変更は`file://...`文字列としてすべてのノードに伝播され、各ノードが自身のファイルを開きます。

一般的なパターンとしては、デプロイメントツール（Kubernetes Secrets、Ansible、構成管理ツールなど）を使ってEMQX起動前にシークレットファイルを各ノードに同じパスでプロビジョニングします。

## 適用箇所

`file://`の方式は設定スキーマでシークレット型が使われている箇所で有効です。主な例：

- **SSL/TLSリスナー**：`listeners.<type>.<name>.ssl_options.password`（キーのパスフレーズ）。詳細は[Enable SSL/TLS](../network/emqx-mqtt-tls.md)を参照。
- **ブリッジとコネクター**：パスワード、APIキー、シークレットアクセスキー、JWTトークン、サービスアカウントのJSON認証情報（例：`service_account_json`）。
- **クラスターリンク**：`cluster.links[].password`。
- **ダッシュボードSSO（OIDC）**：`dashboard.sso.oidc.secret`。
- **ライセンス**：`license.key`（ライセンス文字列自体）。詳細は[License Configuration](./license.md)を参照。
- **AI補完**：`ai.completion_profile.api_key`。

これらのフィールドのダッシュボードのツールチップには`file://`形式がサポートされている旨が表示されます。

## ノードクッキーをファイルから読み込む

EMQX 6.3.0以降、`node.cookie`およびその環境変数オーバーライドである`EMQX_NODE__COOKIE`は`file://`を受け入れます。これは`string`型フィールドのデフォルト動作に対する明示的な例外です。

`emqx.conf`にノードクッキーをプレーンテキストで保存したくない場合は、`node.cookie`をファイルURLに設定してください。

```hocon
node.cookie = "file:///run/secrets/emqx-cookie"
```

または、環境変数`EMQX_NODE__COOKIE`を設定します。

```bash
export EMQX_NODE__COOKIE='file:///run/secrets/emqx-cookie'
```

パスは通常のファイルでもFIFO（名前付きパイプ）でもかまいません。EMQXは起動時に一度だけノードクッキーを解決します。設定のリロード時にはファイルやFIFOは再読込されません。

FIFOを使用する場合、オーケストレーターは起動時に`emqx ctl`などの他の`emqx`コマンドを呼び出す前に、毎回FIFOにクッキーを書き込む必要があります。ノード起動後に呼び出されるコマンドは、FIFOを再度読み込まずに稼働中のノードからクッキーを取得します。

起動スクリプトはファイル内容の末尾の改行文字を削除します。参照されたパスが存在しない場合、ファイルが空の場合、または解決されたクッキーにバックスラッシュ、シングルクォート、ダブルクォート、スペースが含まれる場合はノードは起動に失敗します。

EMQXは解決済みのクッキーを生成された`data/configs/vm.*.args`ファイルに書き込まずに直接Erlang VMに渡します。クラスター展開では、すべてのノードにファイルやFIFOをプロビジョニングし、各ノードが同じクッキーを読み込むようにしてください。詳細は[Set Node Cookie](../cluster/security.md#set-node-cookie)を参照してください。

## ロギングとマスキング

EMQXはシークレット型フィールドの値をログやHTTP APIレスポンスでマスキングします。`file://`値の場合はファイルパスのみログに記録し、内容は記録しません。解決されたシークレット値は決してログに出力されません。

## `file://`を使わない方がよい場合

`node.cookie`のように明示的にドキュメント化されているフィールドを除き、プレーンな`string`型フィールドは`file://`値をファイル参照として扱わず、文字列としてそのまま扱います。`file://`がサポートされているかどうかはスキーマの型とフィールドのドキュメントを必ず確認してください。