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

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

構文

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

file://<path-to-file>

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

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

例：

# ファイルから読み込む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を参照。
• ブリッジとコネクター：パスワード、APIキー、シークレットアクセスキー、JWTトークン、サービスアカウントのJSON認証情報（例：service_account_json）。
• クラスターリンク：cluster.links[].password。
• ダッシュボードSSO（OIDC）：dashboard.sso.oidc.secret。
• ライセンス：license.key（ライセンス文字列自体）。詳細はLicense Configurationを参照。
• AI補完：ai.completion_profile.api_key。

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

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

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

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

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

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

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を参照してください。

ロギングとマスキング

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

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

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