設定ファイル

ユーザーは設定ファイルまたは環境変数を使ってEMQXを設定できます。本節では主にEMQXの設定ファイルについて紹介し、EMQXで最もよく使われる機能の基本的な設定方法を説明します。詳細な設定項目や解説については、EMQX Enterprise Configuration Manualをご参照ください。

設定ディレクトリ

EMQXをインストールすると、設定やランタイムデータを管理するための一連のディレクトリが作成されます。これらのディレクトリは大きく2つのカテゴリに分かれています。

静的設定ディレクトリ (etc)：読み取り専用で、変更されない静的な設定ファイルを格納します。
動的設定ディレクトリ (data/configs)：書き込み可能で、ランタイムで生成または動的に更新される設定ファイルを格納します。

静的設定ディレクトリ (`etc`)

etcディレクトリにはEMQXの初期設定を定義する設定ファイルが格納されます。これらのファイルは通常、デプロイ時やアップグレード時に変更され、ランタイム中は安定性を保つため読み取り専用となっています。etcディレクトリの場所はインストール方法によって異なります。

インストール方法	パス
RPMまたはDEBパッケージでインストール	`/etc/emqx`
Dockerコンテナで実行	`/opt/emqx/etc`
ポータブル圧縮パッケージから展開	`./etc`

EMQX 6.3.0以降、RPMおよびDEBインストールでは/opt/emqx/etcが/etc/emqxへのシンボリックリンクとして作成されます。

動的設定ディレクトリ (`data/configs`)

ランタイム中、EMQXはダッシュボード、REST API、CLIを通じて動的な再設定を可能にしています。これらのツールで行われた変更はdata/configsディレクトリに保存され、セッションをまたいで永続化されます。このディレクトリの場所もインストール方法によって異なります。

インストール方法	パス
RPMまたはDEBパッケージでインストール	`/var/lib/emqx/configs`
Dockerコンテナで実行	`/opt/emqx/data/configs`
ポータブル圧縮パッケージから展開	`./data/configs`

EMQX 6.3.0以降、RPMおよびDEBインストールでは/opt/emqx/dataが/var/lib/emqxへのシンボリックリンクとして作成されるため、/opt/emqx/data/configsは/var/lib/emqx/configsに解決されます。カスタムのデータディレクトリを設定してもこのシンボリックリンクは更新されません。

TIP

node.data_dir設定や環境変数EMQX_NODE__DATA_DIRを変更することでデータディレクトリを変更可能です。ただし、クラスター運用時はすべてのノードで同じディレクトリパスを使用する必要があります。

設定ファイルの内容が重複することは推奨されませんが、重複した場合は事前に定義された上書きルールで解決されます。詳細はConfig Override Rulesをご覧ください。

設定例

Schemaセクションでは詳細なリファレンスを提供していますが、設定例はEMQXの設定を理解し適用する際に役立ちます。

RPMまたはDEBパッケージでEMQXをインストールした場合、etc/emqx/examplesディレクトリに設定例があります。
DockerコンテナでEMQXを実行している場合、opt/emqx/etc/examplesディレクトリに設定例があります。

ベース設定ファイル

EMQX 5.8.4以降、etcディレクトリにbase.hoconというベース設定ファイルが存在します。このファイルはデフォルト設定を含み、ランタイム中により上位の設定ファイルで上書き可能です。

例えば、基本的な認証設定でデプロイを開始し、ダッシュボードUIからより複雑な設定で上書きすることが可能です。

nodeやclusterのような不変の設定については、デプロイ固有の値でランタイム中に変更すべきでない場合、環境変数を使うこともできます。詳細はEnvironment VariablesおよびConfig Override Rulesをご参照ください。

TIP

base.hoconファイルはクラスター間で同期されず、そのノードにのみ適用されます。

設定書き換えファイル

data/configsディレクトリのcluster.hoconファイルはクラスター全体の設定項目を含みます。ダッシュボード、REST API、CLIからの設定変更はこのファイルに永続化されます。

クラスター内のノードが再起動されたり新しいノードが追加された場合、そのノードは自動的に他のノードからcluster.hoconファイルをコピーして適用します。このため、手動でのファイル編集は推奨されません。

このファイルの設定はbase.hoconの設定の上に適用されます。設定の上書き階層の詳細はConfig Override Rulesをご覧ください。

EMQX 5.1以降、クラスター設定の変更時にcluster.hoconファイルのバックアップが作成されます。バックアップはノードのローカル時間でタイムスタンプが付けられ、最大10個まで保持されます。

不変設定ファイル

後方互換性のため、emqx.confファイルはnodeやclusterの重要なシステム設定に対して引き続き利用可能です。このファイルはbase.hoconやcluster.hoconよりも優先度が高いですが、環境変数よりは低い優先度です。意図的にこの優先度を利用し、パッケージのアップグレードでこのファイルのデフォルトが更新されることを理解している場合を除き、変更は避けてください。

設定の上書きに関する詳細はConfig Override Rulesを参照してください。

設定パス

EMQXでは設定値をドット区切りのパスで参照できます。これはツリー構造に似ており、ルート（常にStruct）から始まり、各セグメントはフィールド名またはMapのキーを指します。配列要素の場合は1始まりのインデックスを使用します。

設定パスの例：

bash

node.name = "emqx.127.0.0.1"
zone.zone1.max_packet_size = "10M"
authentication.1.enable = true

HOCON設定フォーマット

EMQX v5.0以降、設定ファイルフォーマットとしてHuman-Optimized Config Object Notation (HOCON)を採用しています。

HOCONは人間が読みやすいデータフォーマットでJSONのスーパーセットです。継承や結合、引用符などの機能により設定作業をさらに簡素化します。

HOCON構文例：

JSON風のオブジェクトとして表現可能です。

bash

node {
  name = "emqx@127.0.0.1"
  cookie = "mysecret"
  cluster_call {
    retry_interval  =  1m
  }
}

またはフラット形式でも記述できます。

bash

node.name = "127.0.0.1"
node.cookie = "mysecret"
node.cluster_call.retry_interval = "1m"

このフラット形式は過去のEMQXバージョンとの互換性を保ちつつ使い分けられています。

HOCONでは文字列の両端に引用符を付けることを推奨します。特殊文字を含まない文字列は引用符なしでも構いません（例：foo、foo_bar）。一方、フラット形式は=の右側のすべてを値として扱います。

HOCON構文の詳細はHOCON Documentationをご参照ください。

環境変数

設定ファイルのほかに、環境変数を使ってEMQXを設定することも可能です。

例えば、環境変数EMQX_NODE__NAME=emqx2@127.0.0.1は以下の設定を上書きします。

bash

# emqx.conf
node {
  name = "emqx@127.0.0.1"
}

設定項目と環境変数は以下のルールで変換されます。

設定ファイルの.区切りは環境変数では使えないため、EMQXは__（ダブルアンダースコア）を区切り文字として使用します。
他の環境変数と区別するため、EMQXは環境変数にEMQX_というプレフィックスを付けます。
環境変数の値はHOCON値として解析されるため、複雑なデータ型も渡せます。:、=、#などのHOCON特殊文字を含む値は必ずダブルクォート"で囲み、リテラル文字列として扱われるようにしてください。特に#はHOCONの行コメントを開始するため、引用符なしでは#以降がコメントとして無視されます。

変換例：

bash

# 環境変数

## localhost:1883は構造体{"localhost": 1883}として解析されるため、ダブルクォートで囲む必要があります
export EMQX_LISTENERS__SSL__DEFAULT__BIND='"127.0.0.1:8883"'

## HOCON配列を文字列として直接渡す
export EMQX_LISTENERS__SSL__DEFAULT__SSL_OPTIONS__CIPHERS='["TLS_AES_256_GCM_SHA384"]'


# 設定ファイル
listeners.ssl.default {
    ...
    bind = "127.0.0.1:8883"
    ssl_options {
      ciphers = ["TLS_AES_256_GCM_SHA384"]
    }
  }
}

#、:、=を含む値について

パスワードなどの文字列に#を含む場合、#はHOCONの行コメント開始文字なので以下のようにすると

bash

export EMQX_DASHBOARD__DEFAULT_PASSWORD="MQtt#123"

パスワードはMQttとして解析され、#123はコメントとして無視されます。リテラルとして渡すにはHOCONレベルのダブルクォート（シェルの引用符ではなく）で囲み、パーサーに"MQtt#123"として認識させます。

bash

# 正しい例 — HOCONパーサーが見る値は "MQtt#123"
export EMQX_DASHBOARD__DEFAULT_PASSWORD='"MQtt#123"'

# 同じ効果、シェル用に内側の引用符をエスケープ
export EMQX_DASHBOARD__DEFAULT_PASSWORD="\"MQtt#123\""

:や=を含む値も同様です。URLエンコード（例：%23）は機能しません。EMQXは環境変数の値をURLデコードしません。

なぜ一部の引用なし値は通り、一部は通らないのか

EMQXは環境変数の値をfake_key=<値>としてHOCONパーサーに渡します。パース成功すれば解析結果を使い、失敗すれば生文字列を使います。例えばEMQX_..._PASSWORD="abc#def"はabc（#defはコメント）となりますが、EMQX_..._PASSWORD=".abc#def"は無効なHOCONなので生文字列のまま.abc#defとなります。HOCON引用符で囲むと動作が決定的になります。

TIP

EMQXは未定義のルートパス（例：EMQX_UNKNOWN_ROOT__FOOBAR）を無視します。UNKNOWN_ROOTは事前定義されたルートパスではないためです。

既知のルートパスに未知のフィールド名を設定すると、起動時にwarningログを出力します。例えばenableを誤ってenabledと設定した場合、以下のように出力されます。

bash

[warning] unknown_env_vars: ["EMQX_AUTHENTICATION__ENABLED"]

TIP

EMQX 6.3.0以降、EMQX_FEATURESはfeature gates用の特別な起動環境変数です。HOCON設定パスにはマッピングされず、cluster.hoconにも保存されず、EMQX起動時のみ解決されます。

起動時環境変数

多くのEMQX_プレフィックス付き環境変数はemqx.confの設定を上書きしますが、以下の変数は設定ファイルの対応がなく、設定ファイル解析前にEMQX自体の動作を制御します。

EMQX_FEATURES：ノードが起動するアプリケーションセットを選択（例：FULLやESSENTIAL）。
EMQX_SECURITY_PROFILE：ノード全体のセキュリティプロファイルを選択（legacyまたはhardened）。

EMQX 6.3.0以降、emqxコマンドはetc/emqx.envから環境変数を読み込みます。サービス起動、フォアグラウンド起動、emqx ctl実行時すべてに適用されます。RPM/DEBインストールでは/etc/emqx/emqx.envにあります。システムdユニットを編集する代わりにこのファイルで起動時環境変数を設定してください。

ファイル内の設定は環境から継承した変数を上書きします。
パッケージアップグレード時も編集内容は保持されます。
ファイルには起動時変数がコメント行で記載されており、例：#KEY="${KEY:-default}"。コメント解除して式を変えなければ、非空値を保持するか未設定時にデフォルトを使います。値を上書きする場合は式をKEY=valueに置き換えます。
起動時環境変数を変更したらEMQXノードを再起動してください。
通常のEMQX_プレフィックス付き上書き（例：EMQX_NODE__COOKIE）もこのファイルで設定可能です。

設定上書きルール

EMQXでは設定値は階層的に適用され、以下の上書きルールがあります。

同一ファイル内では後に定義された値が先の値を上書きします。
上位の設定が下位の設定を置き換えます。

設定の優先順位は以下の通りです。

base.hocon < cluster.hocon < emqx.conf < 環境変数

つまり、base.hoconの設定は最も低い優先度で、より上位の設定で上書き可能です。EMQX_で始まる環境変数が最も高い優先度を持ちます。

TIP

バージョン5.8.4以前はbase.hoconファイルが存在しませんでした。優先順位は同じですがbase.hoconはありません。

ダッシュボードUI、HTTP API、CLIからの変更はランタイムでcluster.hoconに永続化され即時反映されます。ただし、同じ設定項目がemqx.confや環境変数で異なる値に設定されている場合、ノード再起動後に変更が元に戻ることがあります。

混乱を避けるため、emqx.confとcluster.hoconで設定が重複しないようにしてください。

TIP

古いEMQXバージョン（例：5.0.2/v5.0.22以前）ではcluster-override.confファイルが存在し、設定優先順位はemqx.conf < ENV < HTTP API (cluster-override.conf)でした。
5.0.2/v5.0.22以前から最新バージョンにアップグレードする場合、優先順位は変わらず、互換性維持のためcluster.hoconは作成されません。
cluster-override.conf機構はバージョン5.1で廃止されました。

上書き例

以下の設定では、最後の行で定義されたlevelのdebugが先のerrorを上書きしますが、enableフィールドは変更されません。

bash

log {
  console {
    enable = true
    level = error
  }
}

## コンソールログの出力レベルをdebugに設定し、他の設定は維持
log.console.level = debug

パケットサイズ制限は最初に1MBに設定され、その後10MBに上書きされています。

bash

zones {
  zone1 {
    mqtt.max_packet_size = 1M
  }
}
zones.zone1.mqtt.max_packet_size = 10M

リスト要素の上書き

EMQXの配列は以下の2つの表現方法があります。

リスト形式：例 [1, 2, 3]
マップ形式（サブスクライブ用）：例 {"1"=1, "2"=2, "3"=3}

以下の3つの形式は同等です。

bash

authentication.1 = {...}
authentication = {"1": {...}}
authentication = [{...}]

この機能により、配列の要素の値を簡単に上書きできます。例えば：

bash

authentication  = [
  {
    enable = true,
    backend = "built_in_database",
    mechanism = "password_based"
  }
]

# 1番目の要素のenableフィールドを以下のように上書き可能
authentication.1.enable = false

TIP

リスト形式の配列は完全に上書きされ、元の値は保持できません。例えば：

bash

authentication = [
  {
    enable = true
    backend = "built_in_database"
    mechanism="password_based"
  }
]

## 以下の設定では1番目の要素のenable以外の全フィールドが失われます。
authentication = [{ enable = true }]

ゾーンの上書き

EMQXのゾーンは設定をグループ化する概念です。リスナーにzoneフィールドでゾーン名を設定すると、そのゾーンに紐づいたリスナーに接続したMQTTクライアントはゾーンの設定を継承し、グローバル設定を上書きすることがあります。

TIP

デフォルトではリスナーはdefaultという名前のゾーンに紐づいています。defaultゾーンは論理的なグループであり、設定ファイルには存在しません。

ゾーンレベルで上書き可能な設定項目は以下の通りです。

mqtt：MQTT接続やセッション設定。特定ゾーンでMQTTメッセージの最大パケットサイズを大きくするなど。
force_shutdown：強制シャットダウンのポリシー。
force_gc：Erlangプロセスのガベージコレクションの微調整。
flapping_detect：クライアントのフラッピング検出。
durable_sessions：MQTTセッションの永続化設定。特定ゾーンで永続ストレージを有効化など。

EMQXバージョン5のデフォルト設定ファイルにはゾーンは含まれていません。バージョン4ではinternalとexternalの2つのデフォルトゾーンが存在していました。

ゾーンを作成するには設定ファイルに定義します。例：

bash

zones {
  # 複数のゾーンを定義可能
  my_zone1 {
    # ゾーンはグローバル設定と同じスキーマを共有
    mqtt {
      # このゾーンの接続に対して大きなパケットサイズを許可
      max_packet_size = 10M
    }
    force_shutdown {
      # このゾーン固有の設定
      ...
    }
    durable_sessions {
      # このゾーンでセッションの永続化を有効化
      enable = true
      ...
    }
  }
  my_zone2 {
    ...
  }
}

リスナーでzoneフィールドを設定し、作成済みのゾーンに紐づけます。

bash

listeners.tcp.default {
    bind = 1883
    zone = my_zone1
    ...
}

設定コード管理のベストプラクティス

EMQXの設定をソース管理や自動化システムで管理する場合、以下のルールを推奨します。

設定コードはbase.hoconに記述する。
cluster.hoconを手動編集したり、自分でマウントしたりしない。
emqx.confは優先度が高いこととアップグレードの影響を理解した上でのみ変更する。
ダッシュボード、API、CLIで変更しない単純な上書きは環境変数で行う。

設定コードの真のソースはbase.hoconです。ノード起動時に静的設定ディレクトリから読み込まれ、パッケージング、イメージビルド、構成管理、GitOpsで管理可能です。ダッシュボード、REST API、CLIからのランタイム変更はcluster.hoconに永続化され、base.hoconの上に重ねられます。

例として、リスナー、ログ、認証、認可、データ統合のベースラインをbase.hoconに保持できます。

bash

# base.hocon
listeners.tcp.default {
  bind = "0.0.0.0:1883"
  max_connections = 1024000
}

log.console {
  enable = true
  level = warning
}

authentication = [
  {
    mechanism = password_based
    backend = built_in_database
    user_id_type = username
  }
]

cluster.hoconは設定コードの真のソースとして使わないでください。EMQXがランタイムで管理し、ダッシュボード、REST API、CLIが書き換え、上書き前にバックアップを作成し、クラスター内のノード間でコピーされます。手動編集やマウントはランタイム更新と競合したり上書きされたりする恐れがあります。

emqx.confは配布パッケージにベースライン設定ファイルとして同梱されています。変更しなければアップグレード時に新しいEMQXバージョンの保守的なデフォルト変更を取り込めます。emqx.confで設定項目を指定するとbase.hoconやcluster.hoconより優先度が高くなり、ランタイム変更が反映されてもノード再起動後に元に戻ることがあります。意図的にその挙動が必要な場合のみ使用してください。

環境変数は最も優先度が高く、単純なデプロイ固有値やランタイムで変更すべきでない値に便利です。

bash

export EMQX_NODE__NAME='emqx@node1.example.net'
export EMQX_NODE__COOKIE='mysecret'
export EMQX_CLUSTER__DISCOVERY_STRATEGY='static'
export EMQX_CLUSTER__STATIC__SEEDS='["emqx@node1.example.net", "emqx@node2.example.net"]'

環境変数はすべての設定ファイルを上書きするため、運用者が後からダッシュボード、API、CLIで調整する設定には使わないでください。

スキーマ

HOCONオブジェクトの型安全性を高めるため、EMQXはスキーマを導入しています。このスキーマはデータ型、フィールド名、メタデータを定義し、設定値の検証などに利用されます。

EMQX Enterprise Configuration Manualはこのスキーマから生成されています。

TIP

ゾーンの設定スキーマは各グループで同一のため、設定マニュアルには含まれていません。例えばzones.my_zone1.mqtt {...}はmqtt {...}と同じスキーマです。

プリミティブデータ型

設定マニュアルのプリミティブ型は自明なものが多く、簡単な説明で十分です。以下は全プリミティブ型の一覧です。

Integer

整数値を表します。例：42、-3、0。

Integer(Min..Max)

指定された範囲内の整数。例：1..+infは1から正の無限大までの整数を意味し、正の整数のみ許容されます。

Enum(symbol1, symbol2, ...)

列挙型で、定義されたシンボルのいずれかのみを取れます。例：Enum(debug,info,warning,error)はログレベルの許容値です。

String

文字列型で、複数の形式をサポートします。

引用符なし：特殊文字を含まない単純な識別子や名前に適します（後述の禁止文字に注意）。
引用符付き文字列：特殊文字や空白を含む場合はダブルクォート"で囲み、必要に応じてバックスラッシュ\でエスケープします。例："line1\nline2"。
三重引用符文字列："""で囲み、\以外のエスケープ不要で複雑な内容を含められます。三重引用符に隣接するクォートはエスケープが必要です。
インデント付き三重引用符文字列："""~と~"""で囲み、EMQX 5.6以降で導入。設定ファイル内でのインデントを許容し、複数行や整形テキストに適します。

引用符なし文字列の注意点：

禁止文字：$、"、{、}、[、]、:、=、,、+、#、`、^、?、!、*、&、\、空白。
//で始めない（コメント開始と誤認されるため）。
true、false、nullで始まる場合はブール値やnullと誤解されないようにする。

三重引用符文字列のガイドライン：

三重引用符に隣接するクォートはエスケープまたは~区切りを使う。
複数行文字列はスペース（タブ不可）によるインデントをサポート。インデントレベルは最小の先頭スペース数で決定。

例：

rule_xlu4 {
  sql = """~
    SELECT
      *
    FROM
      "t/#"
  ~"""
}

HOCONの文字列引用規則の詳細はHOCON仕様を参照してください。

EMQX独自のインデント付き三重引用符文字列の詳細はemqx/hocon.git READMEを参照してください。

String("constant")

定数文字列で、単一値の列挙型（Enum）のように振る舞います。特定の設定やモードの静的値定義に使います。

Boolean

trueまたはfalseのいずれか（大文字小文字を区別）。

Float

小数点を含む浮動小数点数。例：3.14、-0.001。

Duration

人間に読みやすい形式の時間の長さを表します。例やフォーマットの説明があります。

Duration(s)

秒単位の精度を持つDuration型。詳細と例があります。

Secret

パスワードやトークンなどの機密情報用型。使用方法と重要性の説明があります。

複合データ型

EMQXのHOCON設定における複合データ型は、他の複合型やプリミティブ値を含むデータ構造を表現します。柔軟で階層的なデータ表現を可能にします。

Struct `Struct(name)`

中括弧{}で囲まれたフィールドを持つ構造体。nameはスキーマ名で、構造体のフィールド名と型を指定します。

Map `Map($name->Type)`

Structに似ていますが、フィールド名が事前定義されていないキー・バリューの集合です。

$nameはドット.を含まない任意の文字列キーを意味し、エンティティや属性名を表します。Typeはすべての値が同じ型であることを示し、均一なデータコレクションを可能にします。

OneOf `OneOf(Type1, Type2, ...)`

複数の型のいずれかを取るユニオン型。構造体のフィールドが複数の候補型のいずれかを持つことを示します。例：String(infinity)またはDurationのいずれか。

Array `Array(Type)`

指定した型の要素からなる配列。

TIP

Mapのフィールド名が正の整数の場合、Arrayの代替表現として解釈されます。例：

bash

myarray.1 = 74
myarray.2 = 75

はmyarray = [74, 75]と解釈され、配列要素の上書きに便利です。

Variform式

Variformは文字列操作やランタイム評価のための軽量かつ表現力豊かな言語です。完全なプログラミング言語ではなく、EMQXの設定内に埋め込んで動的に文字列操作を行うための専門ツールです。

TIP

Variform式は特定の設定項目にのみ適用されます。明示されていない限り使用しないでください。

NULL値について

Variform式では値のバインディング参照や部分式の評価が未定義値となる場合、空文字列''として表現されます。

JSONデコードしたフィールドがnullの場合は未定義値（空文字列）として扱われ、文字列"null"とは異なります。

構文

例：

function_call(clientid, another_function_call(username))

この式はclientidとusernameを組み合わせて新しい文字列値を生成します。

Variformは以下のリテラルをサポートします。

ブール値：trueまたはfalse
整数：例42
浮動小数点数：例3.14
文字列：シングルクォート'またはダブルクォート"で囲まれたASCII文字列
配列：[と]で囲まれ、カンマ,区切りの要素
変数：事前定義された値の参照（例：clientid）
関数：事前定義関数（例：concat([...])）

Variformは以下をサポートしません。

算術演算
ループ
ユーザー定義変数
ユーザー定義関数
例外処理やエラー回復
文字列リテラル内のエスケープシーケンス（特殊文字のアンエスケープはunescape関数を使用）

Variform式を含む設定例：

mqtt {
    client_attrs_init = [
        {
            # client IDの最初の'-'までのプレフィックスを抽出
            expression = "nth(1, tokens(clientid, '-'))"
            # client_attrs.groupとして設定
            set_as_attr = group
        }
    ]
}

TIP

アンエスケープ関数が必要な場合、HOCON設定内で三重引用符"""文字列を使うと二重エスケープ不要で便利です。

例：

#### 複数行のclient IDの最初の行を取得
expression = """nth(1, tokens(clientid, unescape('\n')))"""

事前定義関数

EMQXはルールエンジンの文字列関数に似た豊富な文字列、配列、乱数、ハッシュ関数を備えています。これらは抽出データの操作やフォーマットに使えます。

文字列関数：
- 文字列操作関数
- 新関数any_to_string/1は任意の中間非文字列値を文字列に変換します。
配列関数：nth/2
トピック関数：
- topic_join(Words)：配列のトピックレベルを/で結合しMQTTトピックやフィルターを生成。例：topic_join(['devices', clientid, '#'])はdevices/<clientid>/#を生成。
- topic_join(Parent, Word)：ParentトピックにWordを追加。Parentが/で終わる場合は区切り文字を追加しない。
- topic_match(Topic, Filter)：MQTTトピックがフィルターにマッチするか判定し、trueまたはfalseを返す。例：topic_match(topic, topic_join(['devices', clientid, '#']))はクライアント固有トピックフィルターとのマッチ判定。
- topic_split(Topic)：MQTTトピックを/で分割しトピックレベルの配列を返す。
乱数関数：rand_str、rand_int
スキーマレスエンコード/デコード関数：
- bin2hexstr(Data)
- hexstr2bin(Data)
- base64_decode(Data)
- base64_decode(Data, 'no_padding') (6.0.2以降)
- base64_decode(Data, 'no_padding', 'urlsafe') (6.0.2以降)
- base64_encode(Data)
- base64_encode(Data, 'no_padding') (6.0.2以降)
- base64_encode(Data, 'no_padding', 'urlsafe') (6.0.2以降)
- int2hexstr(Integer)：整数を16進文字列にエンコード。例：15はF（大文字）。
ハッシュ関数：
- hash(Algorithm, Data)：Algorithmはmd4、md5、sha（sha1）、sha224、sha256、sha384、sha512、sha3_224、sha3_256、sha3_384、sha3_512、shake128、shake256、blake2b、blake2sのいずれか。
- hash_to_range(Input, Min, Max)：sha256でハッシュし、MinからMaxまでの整数にマッピング（Min <= X <= Max）。
- map_to_range(Input, Min, Max)：入力をMinからMaxまでの整数にマッピング（Min <= X <= Max）。
比較関数：
- num_eq(A, B)：2つの数値が同じならtrue、そうでなければfalse。
- num_neq(A, B)：2つの数値が異なればtrue、そうでなければfalse。
- num_gt(A, B)：A > Bならtrue、そうでなければfalse。
- num_gte(A, B)：A >= Bならtrue、そうでなければfalse。
- num_lt(A, B)：A < Bならtrue、そうでなければfalse。
- num_lte(A, B)：A <= Bならtrue、そうでなければfalse。
- str_eq(A, B)：2つの文字列が同じならtrue、そうでなければfalse。
- str_neq(A, B)：2つの文字列が異なればtrue、そうでなければfalse。
- str_gt(A, B)：辞書順でAがBより後ならtrue、そうでなければfalse。
- str_gte(A, B)：辞書順でAがBより前でないならtrue、そうでなければfalse。
- str_lt(A, B)：辞書順でAがBより前ならtrue、そうでなければfalse。
- str_lte(A, B)：辞書順でAがBより後でないならtrue、そうでなければfalse。
- is_empty_var(V)：変数が空か判定。Variformの空は未定義値（undefined）、JSONのnull（文字列"null"は含まない）、空文字列""。
- not(Bool)：Boolがfalseならtrue、trueならfalse。文字列も受け付け、入力が文字列なら出力も文字列。
システム関数：
- getenv(Name)：環境変数Nameの値を返す。ただしOS環境変数はEMQXVAR_プレフィックス付きで読み込む。読み込み後は不変。
データ抽出関数：
- json_value(Data, Path)：JSON文字列からドット区切りパスで値を抽出。例：usernameがJSONオブジェクトならjson_value(username, 'shop.floor')でフィールド取得。
- jwt_value(Data, Path)：JWTトークンのペイロードからドット区切りパスでクレーム値を抽出。例：passwordがカスタムクレームを持つJWTならjwt_value(password, 'client_attrs.unitid')で値取得。
- is_jwt(Data)（6.2.3以降）：DataがJWSコンパクト形式のJWT構造か判定。3つのドット区切りBase64URLデコード可能なセグメントを持ち、ヘッダーJSONにalgフィールドがあればtrue。署名検証やペイロード検査は行わず、未定義、null、空文字列、5セグメントのJWE、破損値はfalse。

条件式

Variform式は包括的な制御フローを持ちませんが、以下の関数で基本的な条件制御が可能です。

iif(Condition, ThenExpression, ElseExpression)：Conditionがtrueまたは非空文字列ならThenExpressionを返し、それ以外はElseExpressionを返す。
coalesce(Arg1, Arg2, ...)：最初の非空引数を返す。
coalesce([Element1, Element2, ...])：配列の最初の非空要素を返す。

エラー処理

Bashなどのスクリプト環境と同様に、Variform式は未バインド変数や実行時例外発生時に空文字列""を返す設計です。

未バインド変数：未定義またはスコープ外の変数参照は空文字列として評価。
実行時例外：関数の誤用や型不一致などの例外は空文字列を返す。例：配列インデックス範囲外。

式の例

nth(1, tokens(clientid, '.'))：ドット区切りのclient IDのプレフィックスを抽出。
strlen(username, 0, 5)：usernameの部分文字列を抽出。
coalesce(regex_extract(clientid,'[0-9]+'),'vin-1000')：正規表現でclient IDから数字を抽出。空なら'000'を返す。
iif(true, "Value if true", "Value if false")：Value if trueを返す。
iif("", "Value if true", "Value if false")：Value if falseを返す。
iif("hello", "Value if true", "Value if false")：Value if trueを返す。
iif(regex_match(clientid,'^foo\.+*'),'foo','bar')：clientidがfoo.で始まればfoo、そうでなければbarを返す。

パスワード認証

エンドツーエンドトレース

設定ファイル ​

設定ディレクトリ ​

静的設定ディレクトリ (etc) ​

動的設定ディレクトリ (data/configs) ​

設定例 ​

ベース設定ファイル ​

設定書き換えファイル ​

不変設定ファイル ​

設定パス ​

HOCON設定フォーマット ​

環境変数 ​

起動時環境変数 ​

設定上書きルール ​

上書き例 ​

リスト要素の上書き ​

ゾーンの上書き ​

設定コード管理のベストプラクティス ​

スキーマ ​

プリミティブデータ型 ​

Integer ​

Integer(Min..Max) ​

Enum(symbol1, symbol2, ...) ​

String ​

String("constant") ​

Boolean ​

Float ​

Duration ​

Duration(s) ​

Secret ​

複合データ型 ​

Struct Struct(name) ​

Map Map($name->Type) ​

OneOf OneOf(Type1, Type2, ...) ​

Array Array(Type) ​

Variform式 ​

構文 ​

事前定義関数 ​

条件式 ​

エラー処理 ​

式の例 ​

設定ファイル

設定ディレクトリ

静的設定ディレクトリ (`etc`)

動的設定ディレクトリ (`data/configs`)

設定例

ベース設定ファイル

設定書き換えファイル

不変設定ファイル

設定パス

HOCON設定フォーマット

環境変数

起動時環境変数

設定上書きルール

上書き例

リスト要素の上書き

ゾーンの上書き

設定コード管理のベストプラクティス

スキーマ

プリミティブデータ型

Integer

Integer(Min..Max)

Enum(symbol1, symbol2, ...)

String

String("constant")

Boolean

Float

Duration

Duration(s)

Secret

複合データ型

Struct `Struct(name)`

Map `Map($name->Type)`

OneOf `OneOf(Type1, Type2, ...)`

Array `Array(Type)`

Variform式

構文

事前定義関数

条件式

エラー処理

式の例