テンプレートスキーマ

テンプレートは 1 つのストリームを記述する YAML ファイル (.wpg.yaml。.wpg.json の JSON も同等) です。レイヤスタック、フィールドを変化させるジェネレータ、送出プロファイルから成ります。機械可読な定義は docs/schema/template.schema.json で、wpg template schema でも出力できます。未知のキーはエラーになるのでタイプミスを検出できます。ファイルの検査は wpg template lint FILE です。

schema: 1                  # 必須
meta: { ... }              # 必須
variables: [ ... ]         # 任意
layers: [ ... ]            # 必須。外側から内側の順
packet: { ... }            # 任意
stream: { ... }            # 任意
tx: { ... }                # 任意

meta

variables

テンプレート引数です。各項目は name、任意の default (文字列・数値・真偽値)、description を持ちます。フィールド値やジェネレータの中で ${name} と書き、実行時に --var name=value (wpg send、wpg render) や GUI で上書きします。既定値も上書きも無い変数はエラーで、宣言の無い ${…} もエラーです。宣言だけで使われていない変数は警告になります。

次の任意のキーで値を制約できます。書かなければどんな文字列も受け付けます。

variables:
  - { name: vlan_id, type: uint, min: 1, max: 4094, default: 100 }
  - { name: target, type: ipv4, required: true }
  - { name: proto, type: uint, choices: [6, 17], default: 17 }

wpg template lint は既定値と選択肢を検査します。実行時の値 (--var、ジョブ API と render API の vars) が合わなければテンプレートエラーになり、変数名と期待する値を示します。CLI は終了コード 3、サーバは 422 invalid_template を返します。bool は true、false、1、0 を受け付け、1 か 0 として代入されます。GUI のジョブ作成フォームは変数ごとに合った入力欄を表示します。

layers

各項目は protocol (カタログの ID。プロトコルリファレンス を参照)、fields、generators から成ります。

fields

書いたフィールドは Manual、書かない (または auto にした) フィールドは既定値になるか、計算されます (長さ、チェックサム、次プロトコル番号)。値は人間向け表記です。

わざと誤った値も受け付けます。Manual の長さやチェックサムは書いたとおりに使われ、wpg template lint は不一致を警告 (diag-*) として報告します。templates/malformed/ のサンプルはこの仕組みで作っています。

generators

フィールド名からジェネレータへの対応です。完全形か、GUI と同じ短縮表記で書きます。

同じフィールドに固定値とジェネレータを書くと lint が警告します。

式 (expr)

expr ジェネレータはパケットごとに整数を計算します。結果は他の値と同じようにフィールドに書き込まれるので、数値のほか IPv4 / IPv6 アドレスや MAC アドレスも埋められます。

参照できるのは、同じテンプレートでジェネレータを持つフィールドだけです。固定値のフィールドは見えません (変数にして ${name} と書けば、式の解析より前に置き換わります)。expr が別の expr を参照できるのは、参照先がテンプレート内で先にある場合だけです。同梱ライブラリの例:

generators:
  chaddr: { kind: expr, expr: "$0.src" }                          # Ethernet の送信元 MAC を写す (dhcp-discover-flood)
  xid: { kind: expr, expr: "rand(0, 0xffffffff)" }               # 再現可能なランダムのトランザクション ID
  label: { kind: expr, expr: "${srgb_base} + ${first_index} + idx" } # SR-MPLS の Prefix SID (sr-mpls-prefix-sid-sweep)

packet

stream

ジェネレータの組み合わせ方とストリームの長さです。

無限のジェネレータ (wrap 無しの counter) には count が必要で、product や nested の内側には置けません。

tx

wpg send のコマンドラインオプションが優先されます。

コマンドラインからの上書き

wpg send、wpg render、wpg template show、wpg bench --template では、ファイルを編集せずにその実行だけテンプレートを変えられます。

LAYER はプロトコル ID (最初のレイヤ: ipv4)、0 から数えた n 番目のレイヤ (ipv4[1] は IP-in-IP の内側のヘッダ)、または 0 始まりのレイヤ添字 (2) です。FIELD は プロトコルリファレンス にあるフィールド名です。存在しないレイヤやフィールドを指定すると終了コード 3 で止まり、テンプレートのレイヤ一覧か近いフィールド名を表示します。--vars-file の変数も --var と同じく、テンプレートで宣言されている必要があります。

GEN は次のいずれかです。

$ wpg render templates/examples/eth-ipv4-udp-range.wpg.yaml -o out.pcapng --count 100 \
    --vars-file lab.yaml --set ipv4.ttl=1 --gen udp.src_port=range:1024..1123

payload レイヤ

payload は実際のプロトコルではなく、フィールドが生成を制御します。mode (fixed、pattern、random、counter)、data、length、seed、counter モードでは counter_offset、counter_width (u32 または u64)、counter_value (通常は counter ジェネレータで与える) です。raw は指定したバイト列をそのまま置きます。

lint の検査項目

同梱ライブラリ

templates/ は既定でライブラリとして読み込まれ、crates/wpg-template/tests/samples.rs で検証されています。

一覧は wpg template list templates で表示できます。

キーリファレンス (自動生成)

テンプレート形式の JSON Schema (wpg template schema) から自動生成しています。説明文はコードの doc コメント (英語) です。Template が文書のルートです。

Template

A .wpg.yaml template: one packet (+ generators) = one stream.

FcsChoice

Frame check sequence choice.

FieldInput

A field value as written in YAML / JSON: a scalar in human notation or a structured value for TLV (options) and list fields.

• scalars: 64, "192.168.1.1", 0x0800, syn|ack (flag names), ipv4 (enum variant names), auto. Hex byte strings must be quoted ("00 01 02");
• TLV: a list of items, each a bare variant name (nop), a one-key map ({ mss: 1460 }, { timestamps: { tsval: 1, tsecr: 0 } }) or the explicit form { type: 99, data: "01 02" } / { name: mss, length: 4, fields: { value: 1 } };
• list: a list of scalars, or of maps for lists of field groups.

Generator

Field value generator, tagged by kind.

kind: "range"

kind: "list"

kind: "random"

kind: "random_mac"

kind: "counter"

kind: "file"

kind: "expr"

GeneratorSpec

A generator of a layer field: either a full [Generator] or the human shorthand of the GUI (192.168.1.1-192.168.5.254, 10.0.0.0/24, 1,5,9, 00:11:22:*).

Meta

Template metadata.

PacketOptions

Frame-level packet options.

Scalar

A YAML scalar; variable defaults may be written as numbers.

StreamMode

How generators of several fields are combined (see wpg_core::stream::Mode).

StreamOptions

Stream expansion options.

TemplateLayer

One layer of the template’s packet.

TxProfile

How the stream is transmitted.

VarType

Value type of a template variable (the field-type names of the protocol catalog).

Variable

A template argument (${name} placeholder) overridable at run time.