Template schema

A template is a YAML file (.wpg.yaml; JSON with .wpg.json is equivalent) that describes one stream: a layer stack, optional generators that vary fields, and a transmit profile. The machine-readable definition is docs/schema/template.schema.json; print it with wpg template schema. Unknown keys are errors, so typos are caught. Check a file with wpg template lint FILE.

schema: 1                  # required
meta: { ... }              # required
variables: [ ... ]         # optional
layers: [ ... ]            # required, outermost first
packet: { ... }            # optional
stream: { ... }            # optional
tx: { ... }                # optional

meta

variables

Template arguments. Each entry has name, optional default (string, number or bool) and description. Use ${name} anywhere inside a field value or generator. Override at run time with --var name=value (wpg send, wpg render), or in the GUI. A variable with no default and no override is an error, and so is a ${…} that is not declared. Declared but unused variables give a warning.

Optional keys constrain the value. Without them any text is accepted:

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 checks the default and the choices. A run-time value that does not fit (--var, or vars in the job and render API) is a template error that names the variable and what was expected: the CLI exits with status 3 and the server answers 422 invalid_template. A bool accepts true, false, 1 and 0 and is substituted as 1 or 0. The job form in the GUI shows a matching input for each variable.

layers

Each entry is protocol (an id from the catalog, see the Protocol reference), fields and generators.

fields

Fields you write are Manual; fields you omit (or set to auto) keep their default or are computed (lengths, checksums, next-protocol numbers). Values use human notation:

Deliberately wrong values are accepted: a Manual length or checksum is used as written, and wpg template lint reports the mismatch as a warning (diag-*). That is how the samples in templates/malformed/ are made.

generators

A map from field name to a generator, either the full form or the shorthand used by the GUI:

A generator and a fixed value on the same field produce a lint warning.

Expressions (expr)

An expr generator computes an integer for every packet. The result is written into the field like any other value, so it can fill numbers, IPv4 / IPv6 addresses and MAC addresses.

A reference can only name a field that has a generator in the same template; fixed field values are not visible (put them in a variable and write ${name} instead, which is substituted before the expression is parsed). An expr can read another expr only if that one comes earlier in the template. Examples from the bundled library:

generators:
  chaddr: { kind: expr, expr: "$0.src" }                          # copy the Ethernet source MAC (dhcp-discover-flood)
  xid: { kind: expr, expr: "rand(0, 0xffffffff)" }               # a reproducible random transaction ID
  label: { kind: expr, expr: "${srgb_base} + ${first_index} + idx" } # SR-MPLS prefix SIDs (sr-mpls-prefix-sid-sweep)

packet

stream

How generators combine and how long the stream is.

Unbounded generators (a counter without wrap) need a count and cannot be in the inner position of product or nested.

tx

Command-line options of wpg send override these.

Overriding values from the command line

wpg send, wpg render, wpg template show and wpg bench --template change a template for one run without editing the file:

LAYER is a protocol id (its first layer: ipv4), the n-th layer of a protocol counting from 0 (ipv4[1] is the inner header of IP-in-IP) or a 0-based layer index (2). FIELD is a field name from the protocol reference. An unknown layer or field stops with exit status 3 and lists the template’s layers or the closest field names. Every variable in --vars-file must be declared in the template, as with --var.

GEN is one of:

$ 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 layers

payload is not a wire protocol; its fields control generation: mode (fixed, pattern, random, counter), data, length, seed, and for counter the counter_offset, counter_width (u32 or u64) and counter_value (usually fed by a counter generator). raw places bytes as given.

Lint checks

The bundled library

templates/ is loaded as a library by default and is checked by crates/wpg-template/tests/samples.rs:

List them with wpg template list templates.

Key reference (generated)

Generated from the JSON Schema of the template format (wpg template schema); the descriptions are the doc comments of the code (English). Template is the document root.

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.