設定リファレンス
Yagra の設定は、すべて環境変数で行います。設定ファイルはありません。
バイナリは、プロセスを起動したときに一度だけ環境を読みます。ですから値を変えたら、該当する コンテナの再起動が必要です。
同梱の compose ファイルを使う場合は、compose ファイルの隣にある .env に変数を書きます。最初の
セットアップは、インストールガイドを見てください。
このページに出てくる変数は、2 種類あります。
- バイナリが読む変数（
yagra-core、yagra-poller、またはその両方）。同梱の compose ファイルを 使うかどうかに関わらず、どのデプロイでも効きます。 - compose 専用の変数。compose ファイルを展開するときに、Docker Compose か同梱の NATS サーバー 設定が使います。バイナリは一切読みません。末尾の専用セクションにまとめてあります。
シークレットは、値ではなくファイルで渡します。 シークレットを扱う変数は 3 つです。
YAGRA_KEK_FILE、YAGRA_SESSION_KEY_FILE、YAGRA_NATS_CALLOUT_SEED_FILE です。
これらが運ぶのは、マウントしたファイルへのパスです。シークレットそのものが環境変数の値に現れる
ことは決してありません。ですから docker inspect やプロセスの環境から漏れることもありません。
真偽を表す変数（YAGRA_ENABLE_HA）は、1・
true・yes・on で真になります（大文字小文字は区別しません）。それ以外の値では偽で、未設定も
偽です。
既定でオンで、読み方が逆のものが 2 つあります。0・false・no・off でオフになり、それ以外
（未設定を含む）ではオンのままです。YAGRA_ENABLE_MCP（MCP の節を見てください）と
YAGRA_STORE_FORWARD（store-and-forward の行を見てください）です。
以下の表で、既定の列にあるダッシュ（—）は、その変数に既定値が無いという意味です。未設定のときに 何が起きるかは、用途の欄に書いてあります。
Yagra-core
Section titled “Yagra-core”yagra-core バイナリが読む変数 — オーケストレーション、スケジューリング、ノースバウンド REST API。
バックエンドストア
Section titled “バックエンドストア”データは種類ごとに、それ専用のストアへ入ります（アーキテクチャ概要 を見てください）。
コアが実データを扱うモードで動くには、PostgreSQL・バス・VictoriaMetrics の 3 つが必要です。 それ以外のストアは任意です。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_DATABASE_URL |
— (required) | メタデータストア用の PostgreSQL 接続 URL。起動時、接続は 2 秒間隔で 30 回リトライされます。 |
YAGRA_TSDB_URL |
— (required) | VictoriaMetrics のベース URL — 時系列メトリクスストア。 |
YAGRA_REDIS_URL |
unset | 揮発性のポーラー死活・割当ミラー用の Redis URL。未設定・空・到達不能 ⇒ コアは一度だけログを出して no-op ミラーに縮退します — 致命的にはなりません。ミラーは再構築可能なので、Redis を失っても安全です。 |
YAGRA_LOGS_URL |
unset | VictoriaLogs のベース URL — 検索可能なパッシブイベントストア。未設定 ⇒ パッシブイベントはすべて PostgreSQL に留まります。 |
YAGRA_CLICKHOUSE_URL |
unset | ClickHouse の HTTP URL — トラフィックフローストア。未設定 ⇒ フロー受信は無効になり、フロー API は 503 を返します。 |
YAGRA_PG_MAX_CONNECTIONS |
20 |
コアプロセス全体の接続プール上限。高可用性を有効にすると、リーダーの advisory lock 用接続がこのプールに加えて 1 本増えます — PostgreSQL の max_connections はそれを見込んでサイジングしてください。 |
YAGRA_VM_WRITERS |
コアあたり 1 本、最大 4 |
VictoriaMetrics へメトリクスを書くタスクの本数です。サンプルはノード単位に振り分けられるので、1 ノードの系列の順序は崩れません。下の待ち行列はこの層の合計で、本数分に分割されます — タスクごとに増えるわけではありません。以前の版と同じ 1 本構成にするなら 1 を指定してください。4 を超える指定は 4 に丸められ、丸めたことがログに出ます。 |
YAGRA_RESULT_QUEUE_CAP |
16384 |
VictoriaMetrics の書き込みが遅いあいだ、コアがポーリング結果を何件まで抱えられるかです。これを超えた分は捨てられます。これは設計どおりの動作です — メトリクスは best-effort の層で、次のポーリングが同じ値を埋め直します。ただしグラフには穴が空きます。大きさは自分のデプロイの yagra_vm_backlog_needed_high_water から決めてください。この指標は、上限の無い待ち行列ならどこまで伸びたかを示します。メモリは件数に比例し、24 ポートのノードで 1 件あたりおよそ 21 KB です。131072 を超える指定は 131072 に丸められ、丸めたことがログに出ます。 |
API と認証
Section titled “API と認証”| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_API_ADDR |
0.0.0.0:8080 |
REST API のバインドアドレス。コンテナのヘルスチェックも、プローブ先ポートを導くためにこれを読みます。 |
YAGRA_ADMIN_PASSWORD |
unset | admin アカウントの初回起動パスワード。アカウントが最初にシードされるときにだけ参照されます。未設定または空 ⇒ コアが一度限りのランダムなブートストラップパスワードを生成してログに一度だけ出力します — 周知の既定パスワードは存在しません。 |
YAGRA_SESSION_KEY_FILE |
unset | マウントした HMAC セッション署名鍵へのパス（16 進 64 文字または生の 32 バイト）。コアの再起動を越えて有効で、HA ペアをまたいで機能する、ステートレスな署名付きセッショントークンを有効化します。未設定 ⇒ プロセスごとの不透明トークン。 |
YAGRA_PAT_OIDC_IDLE_DAYS |
30 |
SSO でプロビジョニングされたアカウントが所有する API トークンが、所有者がサインインしないまま生き延びる日数。IdP 側でのアカウント無効化は Yagra に通知されないため、所有者の沈黙が唯一の手がかりです。ローカル/サービスアカウントが所有するトークンは対象外。1〜365 にクランプされ、無効化はできません。 |
YAGRA_KEK_FILE |
unset | 監視用認証情報を保存時にエンベロープ暗号化する、マウントしたマスタ鍵（KEK）へのパス。 |
WebUI の TLS
Section titled “WebUI の TLS”WebUI は、既定で HTTPS で提供されます。
証明書の正本は PostgreSQL にあり、他のすべての秘密と同じ KEK で二重に暗号化されています。コアが それを、web コンテナの読むボリュームへ書き出します。全体像は セキュリティを見てください。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_TLS_DIR |
unset | コアが証明書バンドルを実体化するディレクトリ（web コンテナの nginx が読みます）。未設定 ⇒ 何も書きません — TLS を別の場所で終端するデプロイの形です。同梱の compose ファイルは /var/lib/yagra/tls を設定します。 |
YAGRA_TLS_SELF_SIGNED_SANS |
unset | ブートストラップの自己署名証明書が対象とする名前（カンマ区切り）。未設定 ⇒ ループバックとコンテナのホスト名。実際に入力されるアドレスをコンテナ内から知る術はないので、ここで指定するか設定 ▸ TLS 証明書で正しい名前を指定して再生成してください。 |
YAGRA_API_BIND |
unset（⇒ 0.0.0.0） |
コアの平文 API ポートを公開するホスト側インターフェース。コア自身も読みますが、それは設定 ▸ TLS 証明書が「このポートがまだ LAN から届くか」を報告するためだけで、コンテナ内でコアが bind する先は変わりません。Prometheus の scrape・webhook 送信元・API スクリプトを TLS エッジへ移した後に 127.0.0.1 を設定してください。 |
次の 4 つは web コンテナのエントリポイントが読みます（どちらの Rust バイナリも読みません）:
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_WEB_TLS |
on |
off / false / 0 にすると、コンテナの 8080 で平文 HTTP を配ります — 手前のリバースプロキシやロードバランサが既に HTTPS を終端している構成のための選択肢です。 |
YAGRA_WEB_TLS_CERT |
/etc/nginx/certs/server.pem |
web コンテナ内での、証明書チェーンと秘密鍵をまとめたバンドルのパス。1 ファイルに両方を収めているため、鍵と一致しない証明書が読まれる瞬間が生じません。 |
YAGRA_WEB_TLS_WAIT_SECS |
90 |
エントリポイントがそのファイルを待つ秒数。タイムアウトはハードエラーです — TLS が要求された以上、黙って平文へ格下げするのではなく起動を拒否します。 |
YAGRA_WEB_TLS_RELOAD_SECS |
15 |
取り込み・再生成された証明書を検知するためにバンドルをハッシュする周期。変更は nginx -s reload で適用され、しかも nginx -t が通った場合だけです — 不正な証明書は UI を落とさず、直前の設定が動き続けます。 |
スケジューリングとポーリングの既定値
Section titled “スケジューリングとポーリングの既定値”| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_POLL_INTERVAL_SECS |
300 |
初期の既定ポーリング間隔（秒）。10–3600 にクランプされます。初回起動のみ: この値は保存される設定を一度だけシードします。以後は WebUI の設定値が権威であり、この変数は無視されます。 |
YAGRA_SNMP_COMMUNITY |
unset | 認証情報が紐付いていないノードに使うフォールバックの SNMP v2c コミュニティ。未設定または空 ⇒ フォールバックなし — 該当ノードには認証情報の割り当てが必要です。 |
YAGRA_MERAKI_POOL |
default |
Meraki クラウドポーリングのジョブを振り分けるポーラープール。 |
環境変数で設定する Webhook とメールのチャネルは、常に有効な既定のチャネルです。WebUI で設定した どの通知チャネルとも並行して発火します。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_WEBHOOK_URL |
unset | 既定のアラート通知 Webhook — すべてのアラートで発火します。未設定または空 ⇒ 環境変数による Webhook チャネルなし。 |
YAGRA_SMTP_HOST |
unset | 既定メールチャネル用の SMTP リレーホスト。チャネルは YAGRA_SMTP_HOST・YAGRA_SMTP_FROM・YAGRA_SMTP_TO がすべて設定されているときにだけ有効になります。 |
YAGRA_SMTP_PORT |
465 |
SMTP ポート。既定は implicit TLS（SMTPS）です。 |
YAGRA_SMTP_FROM |
unset | メールの From アドレス。有効なメールボックスとしてパースできなければチャネルは破棄されます。 |
YAGRA_SMTP_TO |
unset | メールの To アドレス。有効なメールボックスとしてパースできる必要があります。 |
YAGRA_SMTP_USER |
unset | SMTP 認証のユーザー名。認証情報が適用されるのは YAGRA_SMTP_USER と YAGRA_SMTP_PASS の両方が設定されているときだけです。 |
YAGRA_SMTP_PASS |
unset | SMTP 認証のパスワード。 |
YAGRA_POOL_COVERAGE_ALERT_AFTER_SECS |
300 |
ノードを抱えたままのポーラープールに生存ポーラーが 1 台も居ない状態が何秒続いたら、監視カバレッジそのものについて critical アラートを上げるか。ポーラーは終了時に自ら離脱を通知するため、通常のローリング再起動でも条件は即座に成立します — このデバウンスはそれで誰も呼び出さないためのものです。0 でアラートは無効。yagra_pools_without_live_poller と yagra_pool_nodes_without_live_poller のゲージはどちらの設定でも出力されます。 |
アクティブ/パッシブ構成の完全な手順は高可用性ガイドを 参照してください。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_ENABLE_HA |
false |
PostgreSQL の advisory lock によるリーダー選出を使う、オプトインのアクティブ/パッシブコアペア。オフ ⇒ 単一のアクティブコアで、非 HA と同一の挙動です。 |
YAGRA_CORE_ID |
unset | このコアインスタンスの人間可読な id。HA のログと診断に表示されます。未設定 ⇒ 汎用ラベル。 |
AI のクライアント向けに、既定で公開される MCP のツール群です。詳しくは MCP サーバーのページを見てください。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_ENABLE_MCP |
true |
/mcp に MCP のツール群をマウントします。false にすると外れ、/mcp へのリクエストは 404 を返します。/mcp の認証は、公開ダッシュボードが有効なときでも常に必須です。ですから有効であっても、API トークンを発行するまでは何も見えません。 |
YAGRA_MCP_ALLOWED_HOSTS |
unset | /mcp の Host ヘッダーを固定する、カンマ区切りの host[:port] 許可リスト（任意。DNS リバインディング対策）。未設定または空 ⇒ 任意の Host を受理します。必須の Bearer 認証は引き続きゲートとして機能します。 |
分析と AI RCA
Section titled “分析と AI RCA”トラブルシュートの分析ジョブと、AI 根本原因分析（RCA）の生成に対する上限です。RCA の生成は外部の LLM を呼び出します。ですから RCA の上限は、支出の上限も兼ねます。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_ANALYSIS_MAX_CONCURRENT |
4 |
同時に実行できるトラブルシュート分析ジョブの上限。 |
YAGRA_ANALYSIS_RATE_PER_MIN |
30 |
毎分受け付ける新規分析ジョブの上限（スライディング 60 秒ウィンドウ）。 |
YAGRA_RCA_MAX_CONCURRENT |
2 |
同時に実行できる AI RCA 生成の上限。 |
YAGRA_RCA_RATE_PER_MIN |
10 |
毎分受け付ける新規 RCA 生成の上限（スライディング 60 秒ウィンドウ）。 |
YAGRA_RCA_CACHE_SECS |
900 |
RCA レポートのキャッシュ寿命（秒）。強制再生成はキャッシュを迂回しますが、レート上限は迂回しません。 |
YAGRA_RCA_MAX_TURNS |
6 |
LLM 根本原因分析が回答に至るまでに使えるツール呼び出しのターン数上限。v0.1.23 以降、分析は読み取り専用の MCP ツールを自分で呼んで調べられます。1 にすると以前の単発動作に完全に戻ります — ツールは一切提示されず、プロバイダへ送られるリクエストは以前とバイト単位で同一です。 |
YAGRA_RCA_TASK_BUDGET_SECS |
240 |
1 回の根本原因分析（ツール呼び出しを含む）の実時間上限（秒）。上限に達した場合はリクエストを失敗させず、モデルの最後の回答を返します。 |
トラフィックフローと IP→ASN 補完
Section titled “トラフィックフローと IP→ASN 補完”フローストアへの接続そのものは、YAGRA_CLICKHOUSE_URL で設定します（上の「バックエンドストア」を
見てください）。
ここに挙げる変数は、保持期間と IP→ASN 補完の調整に使います。詳しくは トラフィックフロー機能のページにあります。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_FLOW_RETENTION_DAYS |
30 |
フローレコードの保持期間（日数。ClickHouse の TTL として適用）。1–3650 にクランプされます。 |
YAGRA_CLICKHOUSE_SYSTEM_LOG_RETENTION_DAYS |
7 |
ClickHouse 自身の system.*_log テーブルの保持期間（日数）。0–3650 にクランプされます。素の ClickHouse はこれらに TTL を与えないため、無制限に増え続けます。0 にすると system.* に手を触れません。YAGRA_CLICKHOUSE_URL がこのデプロイの持ち物でない ClickHouse を指している場合に使ってください。 |
YAGRA_IPASN_DB |
unset | フローの IP→ASN 補完に使う、オフラインの iptoasn.com TSV データセットへのパス。未設定 ⇒ 補完は無効になり、エクスポーターが提供する AS 番号だけが使われます。ファイルが存在しない・読めない場合は警告をログに出して補完を無効化します — 致命的にはなりません。 |
YAGRA_IPASN_RELOAD_SECS |
0 |
IP→ASN データセットを再起動なしでホットリロードする周期（秒）。0 ⇒ 起動時に一度だけ読み込み、リロードタスクなし。 |
バス認証情報のスコープ化
Section titled “バス認証情報のスコープ化”バスをリモートポーラーへ公開する場合、コアを NATS の Auth Callout サービスとして動かせます。すると ポーラーごとに、そのポーラーが必要とするサブジェクトだけに絞ったバスの認証情報を発行できます。
v0.3.2 以降、設定する物はありません。「Accept remote pollers」を有効にすると、これも一緒に 有効になります。署名鍵は初回起動時に生成されてデータベースに封じられ、公開鍵のほうは、バスの 残りの設定を書くのと同じ 1 回の実行でバス自身の設定に書き込まれます。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_NATS_POLLER_PASSWORD |
unset | 自分のトークンを持たないポーラーが名乗る共有のブートストラップシークレットであり、callout を動かすかどうかを決める変数でもあります。未設定 ⇒ レスポンダは起動せず、NATS は静的なアカウントに戻ります。リモートポーラーのスイッチがこれを書き込みます。同梱の NATS サーバー設定も同じ値を消費します（compose 専用の変数を参照）。 |
YAGRA_NATS_CALLOUT_ACCOUNT |
$G |
発行したポーラーユーザーを配置する NATS アカウント。バスの生成された callout.conf が名乗るアカウントと一致している必要がありますが、そのファイルはこの同じ値から書かれます。ブローカーのアカウントを独自に変えていない限り、触らないでください。 |
YAGRA_NATS_CALLOUT_SEED_FILE |
unset | 旧経路。 マウントした NATS アカウント nkey シードファイルへのパス。設定すると、core が自分で生成した鍵より優先されます。未設定（通常の状態）なら保存された鍵を使います。v0.3.2 より前に手で設定していた環境のためだけに残っています。 |
バスの証明書は、上の認証情報とは別のものです。Yagra が生成し、PostgreSQL が正本になります。WebUI
自身の証明書と同じ扱いです。bus-cert-init という一発サービスが、バスの起動前にそれをボリュームへ
書き出します。NATS サーバーはそこから読みます。
通常この 2 つを手で設定することはありません。設定 ▸ ポーラー ▸ リモートポーラーを受け入れるが、 TLS と認証を 1 回の変更で有効にするのと合わせて設定します。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_BUS_TLS_SANS |
unset | バス証明書に載せる追加の subject alternative name。カンマ区切りで、リモート拠点が接続する宛先を書きます。nats / localhost / 127.0.0.1 は、この変数を設定した場合でも常に含まれます。nats が抜けると、TLS を有効にした瞬間に同居するコアとポーラーが自分のバスに届かなくなるからです。 |
YAGRA_BUS_TLS_DIR |
unset | bus-cert の一発サービスが証明書と NATS サーバー設定を書き出す先。運用者ではなく compose が設定します。未設定の場合、この一発サービスは非ゼロで終了します。 |
WebUI からのアップグレード
Section titled “WebUI からのアップグレード”Settings ▸ Upgrade（v0.2.2 以降）の画面を出すのはコアです。しかし実際の作業を行うのは、Docker
ソケットを持つ yagra-updater サイドカーです。コアはソケットを持ちません。
ここに挙げる 2 つが、コア側の設定です。サイドカー自身の設定は、後述の compose 専用の変数にあります。
| 変数 | 既定値 | 用途 |
|---|---|---|
YAGRA_UPGRADE_DIR |
未設定 | コアとサイドカーが要求を受け渡すディレクトリ — 共有ボリュームで、deploy 構成では /data/upgrade。未設定＝サイドカー未配備で、画面は「今動いているもの」と「移行できる先」は答え、実行側は利用不可と表示します。このディレクトリの中身が実行されることは一切ありません — 要求ファイル・ハートビート・アップロードされたアーカイブだけを置きます。 |
YAGRA_UPGRADE_BUNDLE_MAX_BYTES |
4294967296（4 GiB） |
アップロードされるイメージアーカイブの上限。到着したバイト単位で判定します。リリース 3 イメージをまとめて save してもおよそ 1 GB なので、これは運用上の制限ではなく、別のファイルをブラウザにドラッグしてしまったときに PostgreSQL と同じファイルシステムを埋める前に止めるための値です。 |
Yagra-poller
Section titled “Yagra-poller”yagra-poller のバイナリが読む変数です。ポーラーは状態を持たないポーリングのワーカーで、パッシブ
イベントとトラフィックフローの受信リスナーも抱えています。
バスと識別子
Section titled “バスと識別子”| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_POLLER_ID |
配布 compose では local、それ以外はホスト名 |
ハートビート・作業セット割当・設定 ▸ ポーラーページで使われる、安定したポーラー識別子。v0.3.2 から docker-compose.deploy.yml は中央デプロイ内のポーラーに local を渡します。コンテナのホスト名は Compose がコンテナを作り直すたびに変わり、アップグレードのたびに死んだ行を残していたためです。core にも同じ値が渡るので、両者が別のポーラーを指すことはありません。単体で何も設定せずに動かした場合は従来どおりマシンのホスト名で、それも解決できなければランダムな poller- id です。A–Z a–z 0–9 _ - にサニタイズされます。 |
YAGRA_POLLER_POOL |
default |
このポーラーが最初に所属するプール —— core が初めてこのポーラーを見たときに名乗る値です（分散ポーリングを参照）。v0.3.4 以降、その後の所属は core が持ちます。Settings ▸ Pollers で移動すると次のワーキングセットでポーラーに伝わり、稼働中のポーラーが購読先をその場で張り替えるため、この値を書き換えてコンテナを作り直しても移動は戻りません。未設定の場合、このポーラーが受信したパッシブイベントとフローには default ではなくプールなしのタグが付きます。 |
YAGRA_POLLER_QUEUE |
pollers |
レガシーのジョブ単位ファンアウト経路用の NATS キューグループ名。 |
YAGRA_BUS_CA_FILE |
unset | tls:// のバス URL（リモートポーラー）で NATS サーバー証明書をピン留めするための CA／サーバー証明書ファイル。未設定または空 ⇒ ピン留めなし — 平文の単一ノード経路です。 |
YAGRA_BUS_AUTH_CALLOUT |
未設定 ⇒ 無効 | ポーラーのみ。1 または true にすると、ポーラーは バスのユーザー名として自分の YAGRA_POLLER_ID を名乗ります。Auth Callout はこの名前で権限を絞ります。無効のまま（既定であり、リモートポーラーのスイッチが設定する状態）なら、YAGRA_BUS_URL に書かれた ユーザー名 —— 共有の静的アカウント —— を名乗ります。callout を有効にした環境でのみ ON にしてください。callout が無効な状態で自分の id を名乗ると、どの静的アカウントにも一致せずバスに拒否されます。 |
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_MAX_CONCURRENT_POLLS |
256 |
同時実行プローブ総数の上限。各デバイスはさらに、同時に 1 つのインフライトプローブに制限されます。これは速さの上限ではなく「同時に何本走らせるか」で、同じ枠で SNMP のテーブル取得も走るため、小さな拠点では下げてください。 |
YAGRA_ADOPT_RATE_PER_SEC |
200 |
このポーラーが他のポーラーから作業を引き継ぐとき（再起動・障害・ローリングアップグレード・スケールイン）に、ジッタ窓の幅を決めるレート（チェック数／秒）。窓は 引き継いだ数 ÷ レート で、そのチェック自身の間隔で頭打ちになります。50 件の引き継ぎなら 1 秒未満で開始し、完全なコールドスタートは従来どおり間隔全体に広がります。0 にすると以前の挙動（常に間隔全体でジッタ）に戻ります。 |
パッシブイベントリスナー
Section titled “パッシブイベントリスナー”syslog と SNMP トラップの受信です（パッシブイベントを見て ください）。各リスナーは、バインドアドレスを設定するまで無効のままです。
2 つの YAGRA_LISTENER_* 変数は、すべての受信リスナーに効きます。次の節のトラフィックフローの
リスナーも含みます。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_SYSLOG_BIND |
unset | syslog リスナーの UDP バインドアドレス（例 0.0.0.0:1514）。未設定または空 ⇒ リスナー無効。バインド失敗はログに出してそのリスナーをスキップします — 致命的にはなりません。 |
YAGRA_TRAP_BIND |
unset | SNMP トラップリスナーの UDP バインドアドレス（例 0.0.0.0:1162）— v1/v2c のトラップと inform。未設定または空 ⇒ リスナー無効。 |
YAGRA_TRAP_COMMUNITY |
unset | コミュニティ文字列が一致しないトラップを破棄します。未設定または空 ⇒ コミュニティフィルタなし — すべてのトラップを受理します。値は決してログに出しません。 |
YAGRA_EVENT_RATE_PER_SOURCE |
200 |
syslog + トラップ受信の、送信元 IP ごとの毎秒イベント数上限（送信元ごとに 1 つの共有トークンバケット。実効レートの下限は 0.1）。 |
YAGRA_EVENT_RATE_GLOBAL |
5000 |
syslog + トラップ受信の、全送信元合計の毎秒イベント数上限。 |
YAGRA_LISTENER_WORKERS |
auto (1–4) | エッジリスナーごとの並列読み取りソケット数。既定はホストの利用可能な並列度を 1–4 にクランプした値。SO_REUSEPORT のないプラットフォームでは常に 1 ソケットです。 |
YAGRA_LISTENER_RCVBUF_BYTES |
4194304 |
リスナーソケットごとの受信バッファ（SO_RCVBUF）サイズ — 既定は 4 MiB。 |
トラフィックフローリスナー
Section titled “トラフィックフローリスナー”NetFlow・IPFIX・sFlow の受信です。フローのデータグラムには、syslog やトラップとは別の枠があります。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_FLOW_BIND |
unset | NetFlow v5/v9 と IPFIX の UDP バインドアドレス（例 0.0.0.0:2055）。未設定または空 ⇒ リスナー無効。 |
YAGRA_SFLOW_BIND |
unset | sFlow v5 の UDP バインドアドレス（例 0.0.0.0:6343）。レートリミッタ・アグリゲータ・フラッシャは NetFlow リスナーと共有します。 |
YAGRA_FLOW_RATE_PER_SOURCE |
1000 |
送信元ごとの毎秒データグラム数上限（フローレコード数ではありません）。 |
YAGRA_FLOW_RATE_GLOBAL |
20000 |
全エクスポーター合計のフローデータグラム上限。 |
YAGRA_FLOW_TOP_N |
500 |
バケット×エクスポーターごとに保持する上位フロー数（バイト数順）— フローストアの主たるカーディナリティ制御です。 |
YAGRA_FLOW_BUCKET_SECS |
60 |
フロー集約バケットの幅（秒）。 |
store-and-forward
Section titled “store-and-forward”リモートポーラーは、ネットワークが切れている間も結果をためます。まずメモリに、あふれたらディスクへ 書き出します。そしてリンクが戻ったときに送り直します。詳しくは 分散ポーリングを見てください。
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_STORE_FORWARD |
on | 結果バッファのマスタースイッチ。off・false・0・no（大文字小文字を区別しない）で無効化します。それ以外の値 — 未設定を含む — はオンを意味します。オフ ⇒ 純粋なパススルー: 結果はライブで発行され、失敗時は破棄されます。 |
YAGRA_STORE_FORWARD_DIR |
/var/lib/yagra/buffer |
ディスク退避先のディレクトリ。同梱の compose ファイルはここに名前付きボリュームをマウントします。ディレクトリを作成・走査できない場合、ポーラーはメモリのみのバッファリングに縮退します — クラッシュすることはありません。 |
YAGRA_STORE_FORWARD_MEM_MAX |
20000 |
最も古い結果がディスクへ退避され始めるまでの、メモリ内リングのサイズ（結果件数）。 |
YAGRA_STORE_FORWARD_DISK_MAX_MB |
512 |
ディスク退避の合計上限（MB）。最も古いセグメントを丸ごと破棄することで強制されます。 |
YAGRA_STORE_FORWARD_MAX_AGE_SECS |
86400 |
これより古い（既定 24 時間）バッファ済み結果は再送時に破棄されます。 |
YAGRA_STORE_FORWARD_DISK_FREE_FLOOR_MB |
1024 |
ファイルシステムの空き容量がこの MB 数を下回ったら退避を停止します — ホストディスクの安全床です。 |
YAGRA_STORE_FORWARD_SEGMENT_MB |
16 |
退避セグメントのロールサイズ（MB）— ディスク上限の粒度です。0 やパースできない値は組み込みの 16 MiB にフォールバックします。 |
両バイナリが読む変数
Section titled “両バイナリが読む変数”| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_BUS_URL |
— | NATS バスの URL — nats://host:4222、リモート拠点なら tls://user:pass@host:4222。コアはライブモードに必須です（上のスケルトンモードを参照）。これがないポーラーは警告をログに出してアイドルします。どちらのバイナリも接続を 2 秒間隔で 30 回リトライします。 |
| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_DISK_WATCH_PATHS |
/=root |
path または path=alias エントリのカンマ区切りリスト — ホスト自己メトリクスが容量を報告するファイルシステムです。alias はメトリクスの mount ラベルになります（省略時はパスの最終セグメントから導出）。読めないパスはサンプルから黙って除外されます。 |
トレーシングとログ
Section titled “トレーシングとログ”| 変数 | 既定 | 用途 |
|---|---|---|
YAGRA_OTEL_ENDPOINT |
unset | OpenTelemetry の span 送出先となる OTLP/HTTP エンドポイント（例 http://jaeger:4318）。未設定または空 ⇒ span は送出されません — 構造化ログのみ。不正なエンドポイントは警告を出してログのみへフォールバックし、起動を中断することは決してありません。 |
OTEL_EXPORTER_OTLP_ENDPOINT |
unset | OpenTelemetry 標準のフォールバックエンドポイント。YAGRA_OTEL_ENDPOINT が未設定のときにだけ参照されます。 |
OTEL_TRACES_SAMPLER |
parentbased_always_on |
トレースサンプラ。認識される値: always_on・always_off・traceidratio・parentbased_always_off・parentbased_traceidratio。それ以外は既定（すべてサンプリング）にフォールバックします。大規模環境では parentbased_traceidratio を推奨します。 |
OTEL_TRACES_SAMPLER_ARG |
1.0 |
比率ベースのサンプラに使うサンプリング比率。0.0–1.0 にクランプされます。 |
YAGRA_LOG_DIR |
unset | 1 時間ごとにローテートする JSON Lines ログの出力先ディレクトリ。stdout の代わりではなく追加で書きます。docker logs に手が届かない環境のための機能で、そうした環境ではパニックや OOM の痕跡が一切残りません。サポートバンドルはこのファイルを HTTP 経由で読み戻すため、復旧後に取得したバンドルにも落ちた実行のログが含まれます。未設定 ⇒ stdout のみ。書き込みはノンブロッキングで、ポーリングループを止めるくらいならログを落とします。ディレクトリが書けない場合も起動失敗ではなく、警告のうえ stdout のみに縮退します。ポーラーではこの変数が「そのポーラーがサポートバンドルに載るかどうか」を決めるスイッチでもあります。 同梱の compose は意図的に 2 通りに設定しています。コアと同じホストにいるポーラーには /var/log/yagra/pollers — コアのログボリュームのサブディレクトリで、コアがディスクから読み戻すため、既に停止したポーラーのログにも届きます。リモート拠点のポーラーには自分専用ボリューム上の /var/log/yagra で、コアから要求されたときに一定期間分をバス経由で送ります。未設定のままだとポーラーは log-ship 能力を宣言しないので、バンドルはその拠点を待たずに「未収録」と記録します。 |
YAGRA_LOG_RETAIN_HOURS |
48 |
YAGRA_LOG_DIR に保持する時間別ログファイルの本数。自動的に刈られるので、無人環境が自分のログでボリュームを埋め尽くすことはありません。 |
RUST_LOG |
info |
標準の tracing EnvFilter 構文による構造化ログのフィルタ — 素のレベル（debug）またはモジュール別ディレクティブ。 |
compose 専用の変数
Section titled “compose 専用の変数”次の変数は、compose ファイルを展開するときに Docker Compose（または同梱の NATS サーバー設定）が
使います。バイナリは一切読みません。設定する場所は、実行する compose ファイルの隣の .env です。
使用箇所の列は、次の略記を使います。
- deploy =
docker-compose.deploy.yml（取得のみで動くサーバー構成） - poller =
docker-compose.poller.yml（単体で動くリモート拠点のポーラー） - single-node =
docker-compose.yml - nats =
docker/nats/nats-server.conf
| 変数 | 既定 | 使用箇所 | 用途 |
|---|---|---|---|
YAGRA_IMAGE_TAG |
latest |
deploy, poller | 取得する、公開されている 3 つの ghcr.io/horryworks/yagra-* イメージのタグ。latest は最新の安定リリースです。本番では固定の v<version> タグを使ってください。 |
YAGRA_IMAGE_REPO |
ghcr.io/horryworks |
deploy, poller | 3 つのイメージを取得するレジストリの名前空間。自前のミラーから配る場合にのみ変更してください。 |
YAGRA_UPGRADE_REPO |
ghcr.io/horryworks |
deploy | yagra-updater サイドカーがリリースを探しに行く先。YAGRA_IMAGE_REPO とは意図的に別の変数です — リリースの所在は、この環境が現在のイメージを取得した場所とは限らず、private ミラーから取得している環境では、リリースを 1 つも持たないレジストリを選択画面が見に行ってしまうためです。いずれにせよホスト側で固定されるので、API 要求がレジストリを指定することはできません。 |
YAGRA_UPGRADE_CHECK_SECS |
86400 |
deploy | サイドカーがリリース一覧を更新する間隔 — 1 日 1 回。一覧は選択画面を埋めるだけなので、頻繁に見に行っても得るものはありません。WebUI で機構を停止すると、この通信自体が止まります。 |
YAGRA_UPGRADE_ALLOW_BUNDLE |
0 |
deploy | 到達できるレジストリが無い環境向けに、アップロードされた docker save アーカイブからの導入を許可します。Yagra の Admin ロールからホスト root への経路が広がります — docker load は構成が名指しする 3 イメージだけでなく、アーカイブに入っているものを何でも導入するためです。だからこそホスト側の設定で、WebUI からは有効にできません。load 以降は通常経路と同一です — 同じバックアップ、同じ構成の差し替え、同じ provenance 検証を行い、アーカイブが操作者の名乗ったタグを含むことも照合します。 |
YAGRA_UPGRADE_MIN_FREE_BYTES |
3221225472（3 GiB） |
deploy | アップグレードが何かを書き込む前に要求する空き容量。事前バックアップ（PostgreSQL のフルダンプと VictoriaMetrics のスナップショット）はリリースイメージの取得より前に走ります。この確認が無いと、既に満杯のホストにまず数百 MB を書き足してから pull に失敗することになります。Docker のストレージとデプロイディレクトリのうち少ないほうを見ます。どちらも測れないホストは、何も確認しなかった旨を記録した上で続行します。0 で確認を無効化します。バイト数として読めない値は既定値に戻すので、確認は有効なままです。 |
YAGRA_UPGRADE_KEEP_RELEASES |
1 |
deploy | 導入するリリースの1 つ前まで、いくつ残すか。対象はこのプロジェクトの 3 イメージと、デプロイディレクトリ内の yagra-backup-* ディレクトリだけで、ホスト上の他のものには触れません。後片付けは新しい版が健全だと確認できた後にのみ走り、後片付けの失敗が成功したアップグレードを失敗に変えることはありません。既定が 1 なのは、WebUI が用意する「戻る」が直前のリリースへの 1 ホップだけで、そのホップに再ダウンロードを必要とさせてはならないからです。再取得ができない閉じたネットワークでは増やしてください。0 は導入したリリースだけを残しますが、バックアップは必ず 1 つ残ります —— 最新のものは、このアップグレード自身が取ったものだからです。 |
YAGRA_DOCKER_GID |
0 |
deploy | yagra-updater サイドカーの実行グループ。uid を 0 以外にする場合にのみ意味を持ちます（root は gid に関わらず Docker ソケットに届きます）。 |
POSTGRES_PASSWORD |
yagra |
deploy | PostgreSQL のパスワード — postgres コンテナとコアの YAGRA_DATABASE_URL の両方に展開されます。本番では変更してください。🚨 URL に使える文字だけにしてください。 接続 URL に埋め込まれ、そこで percent-encode はできないため、/ @ : ? # を含むパスワードは URL をそこで終わらせ、コアは起動を拒否します。openssl rand -hex 16 はこれらを生成しませんが、openssl rand -base64 は高い確率で / を生成します。 |
YAGRA_API_PORT |
8080 |
deploy | コアの API ポートにマップするホストポート。 |
YAGRA_WEB_PORT |
443 |
deploy | WebUI コンテナにマップするホストポート — HTTPS。ソースからビルドする単一ノード構成では既定が 8443 で、評価用スタックが特権ポートを必要としないようにしています。 |
YAGRA_SYSLOG_PORT |
514 |
deploy | ポーラーの syslog リスナーにマップするホスト UDP ポート（コンテナポート 1514）。 |
YAGRA_TRAP_PORT |
162 |
deploy | SNMP トラップリスナーにマップするホスト UDP ポート（コンテナポート 1162）。 |
YAGRA_FLOW_PORT |
2055 |
deploy | NetFlow/IPFIX リスナーにマップするホスト UDP ポート。 |
YAGRA_SFLOW_PORT |
6343 |
deploy | sFlow リスナーにマップするホスト UDP ポート。 |
YAGRA_NATS_PORT |
4222 |
deploy | NATS バスを公開するホストポート。バスを公開するのは TLS + 認証を有効にした場合だけにしてください。それを決めるのが次の YAGRA_NATS_BIND です。 |
YAGRA_PULL_POLICY |
always |
deploy | スタック起動のたびに Compose が 3 つのイメージを再取得するかどうか。既定は従来どおりなので、既存のデプロイは何も変わりません。イメージがレジストリ由来でないホストでは missing にします — サーバ移転は 3 つのイメージを新ホストへ直接読み込むので、その後は元のマシンでしか応答しないレジストリに手を伸ばさずに自力で起動できなければなりません。 |
YAGRA_BACKUP_SKIP_METRICS |
0 |
deploy | 1 にすると VictoriaMetrics のスナップショットをバックアップから外し、到達できないストアと同じ扱いで「省いた」ことをマニフェストに記録します。メトリクスのチェックを外して移転したときに設定されます。アップグレード経路がこれを設定することはありません。 |
YAGRA_NATS_BIND |
127.0.0.1 |
deploy | バスのポートを公開するアドレス。既定ではホストのループバックに閉じるので、同居するコアとポーラー以外からは届きません。設定 ▸ ポーラー ▸ リモートポーラーを受け入れるがこれを 0.0.0.0 にしますが、その際 TLS と認証も同時に有効化します。バスにはデバイスの認証情報が平文で流れるため、この 2 つは 1 つの変更にまとめる必要があります。 |
YAGRA_NATS_ARGS |
-js |
deploy | NATS サーバの起動引数。バスを TLS にすると -c /etc/nats/nats-server.conf が付きます。この設定ファイルは bus-cert-init の一発サービスが書き出します。 |
YAGRA_CORE_BUS_URL |
nats://nats:4222 |
deploy | コアが接続するバスの URL。バスを TLS に切り替えると tls://core:<パスワード>@nats:4222 になります。サーバ全体を TLS にすると平文のポートが残らないため、同居するコアも同じ変更で移る必要があります。 |
YAGRA_POLLER_BUS_URL |
nats://nats:4222 |
deploy | 同居するポーラーが接続するバスの URL。理由は YAGRA_CORE_BUS_URL と同じで、poller アカウントのパスワードを使います。リモートポーラーの URL は、設定 ▸ ポーラーが発行するアーカイブに入っているので、このファイルからは取りません。 |
YAGRA_CERT_DIR |
./certs |
deploy, poller | NATS サーバー証明書（サーバー側）とポーラーの CA 証明書（リモート側。YAGRA_BUS_CA_FILE と対）のためにバインドマウントされるホストディレクトリ。 |
YAGRA_NATS_CORE_PASSWORD |
— (required) | deploy, nats | NATS 静的認証設定の core ユーザーのパスワード。参照されているのに未設定だと NATS サーバーは起動時に終了します — fail-closed で、黙って既定値になることはありません。 |
YAGRA_CALLOUT_SEED_DIR |
./callout |
deploy | 旧経路。 account.seed を置くホストディレクトリ。コアに読み取り専用でマウントされます。YAGRA_NATS_CALLOUT_SEED_FILE と対になりますが、v0.3.2 以降これを必要とするものはありません。 |
YAGRA_SESSION_KEY_DIR |
./session |
deploy | session.key を置くホストディレクトリ。コアコンテナ（複数可）に読み取り専用でマウントされます。YAGRA_SESSION_KEY_FILE と対になります。 |
YAGRA_POLLER_LOG_DIR |
/var/log/yagra/pollers |
deploy | 同居しているポーラーに YAGRA_LOG_DIR として渡す値です。コアが読み戻すログボリュームのサブディレクトリであり、これがそのポーラーのログをサポートバンドルに載せる経路になります。空にすると、そのポーラーは stdout のみに出力します。 |
YAGRA_IPASN_URL |
https://iptoasn.com/data/ip2asn-combined.tsv.gz |
deploy, single-node | ipasn-updater サイドカーが取得するデータセットの URL — AS 補完のために外向き通信を必要とする唯一のコンテナです。 |
YAGRA_IPASN_REFRESH_SECS |
604800 |
deploy, single-node | ipasn-updater サイドカーの取得周期 — 既定は 7 日です。 |
COMPOSE_PROFILES |
未設定（発行されたキットでは self-upgrade） |
poller | Docker 自身の変数で、監視拠点では「その拠点がリリースを導入できるか」を決めるスイッチです。self-upgrade が入っていると Compose が yagra-poller-updater サイドカーを起動し、ポーラーが self-upgrade を名乗り、Settings ▸ Upgrade から入れ替えられるようになります。値を空にすれば、その拠点で Docker ソケットを持つコンテナは 1 つも動きません。キット（Settings ▸ Pollers ▸「Issue token & download」）が既定で書き込みます。切り替えは compose ではなくここで行ってください。アップグレードは compose を入れ替えますが .env には触れないからです。 |
WebUI ビルド時
Section titled “WebUI ビルド時”| 変数 | 既定 | 用途 |
|---|---|---|
VITE_API_BASE |
empty | WebUI の API クライアントと SSE クライアントが呼ぶ API のオリジン — スキーム + ホスト + ポートで、パスは決して含みません。Vite によってビルド時に焼き込まれるため、ビルド済みイメージでは変更できません。空 ⇒ 同一オリジン: 本番イメージは同梱の nginx の背後で WebUI を配信し、nginx が /api をコアへプロキシします。別ホストのコアに対して WebUI を自分でビルドする場合にだけ設定してください。 |