Introduction

wpg (web-packet-generator) is a Rust packet generator for network verification, driven from a web GUI. It lets you assemble arbitrary packets, including deep OSI-family protocols such as IS-IS and CLNP, and transmit them at high speed. Transmission backends range from pcap/Npcap up to AF_PACKET, AF_XDP and DPDK. It ships as a single binary for Windows, macOS and Linux. Use is limited to lab and verification environments.

Where to start

1. Choose how to install: build from source on your OS, deploy to a Linux lab host over SSH, or run the Docker image.
2. Follow the install page for your choice, then Permissions if wpg doctor reports that sending is not allowed.
3. First login: set the password and walk through the screens.
4. Work through the tutorials, starting with the ARP sweep.

You can try everything except sending without any privileges: rendering a template to a pcapng file needs no raw socket.

Concepts

The same binary is both the server (wpg serve, the web UI and REST API) and a command-line tool (wpg send, wpg render, wpg template lint, …); see the CLI reference.

How this manual is organised

• Getting Started: installation, permissions and the first login.
• Tutorials: end-to-end tasks such as an ARP sweep, rate control, pcap replay and an IS-IS adjacency.
• Reference: generated pages for every protocol, the template schema, the API, the CLI and wpg.toml.
• Operations: deployment, services, Docker, upgrades, fast backends, TLS, receive and verification.
• Developer Guide: the crate layout and how to add protocols and translations.

Only send on networks you own or are authorised to test; see the legal notice.

Choose how to install

wpg is a single wpg executable with the web UI embedded. Release binaries are not published yet, so every way below builds it from source; they differ in where it is built and how it runs.

What you need

• A machine to run wpg on: Linux (Ubuntu 20.04 or later and comparable), macOS 12 or later, or Windows 10 21H2 or later.
• A network interface connected to the lab network you want to test. Sending on a network you do not own or are not authorised to test is not allowed.
• A browser on the same machine, or on another one if you set a password and bind to a non-local address.

Pick a way

Notes for the choice:

• Rates. Windows sends through Npcap only and is meant for the GUI at low to medium rates. macOS sends through BPF. For high rates (AF_PACKET, AF_XDP, DPDK) use Linux.
• Docker Desktop on macOS and Windows runs containers in a VM, so frames never reach your physical NIC. Use Docker on Linux hosts only.
• No privileges yet? Every path can render templates to pcapng files and run the web UI without raw-socket rights; only sending needs Permissions.

After installing

Whichever way you chose, the next steps are the same:

1. Run wpg doctor and fix what it reports for sending (Permissions).
2. Start the server with wpg serve (the deploy script and Docker start it for you) and open http://127.0.0.1:8080.
3. Set the password and look around: First login.
4. Try a dry run (the pcapfile backend writes a pcapng file instead of sending), then send for real in the ARP sweep tutorial.

If something does not work, see FAQ and troubleshooting.

Install on Linux

Supported: Ubuntu 20.04 or later (glibc 2.31) and comparable distributions. Release binaries are not published yet, so you build from source; the result is a single wpg executable with the web UI embedded.

1. Install the prerequisites

# Rust toolchain installer (rustup.rs) and a C toolchain for linking
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sudo apt install build-essential pkg-config git

git clone https://github.com/SeiyaFunaokaJP/web-packet-generator.git
cd web-packet-generator
./scripts/setup.sh          # add --just to also install the just task runner

scripts/setup.sh installs the Rust toolchain pinned in rust-toolchain.toml with the WASM target used by the web UI, and a prebuilt trunk (the web UI bundler) at the version pinned in scripts/versions.env. It ends by printing the next command.

Linux sends through AF_PACKET, which needs no extra library. Only the optional libpcap backend (--features pcap) needs sudo apt install libpcap-dev. tshark (package tshark) is optional; the tutorials use it to inspect generated captures.

2. Build

./scripts/build.sh --release        # or: just release

The script builds the web UI with trunk, then the wpg binary with cargo, and prints ==> done: target/release/wpg. Add --features pcap, --features afxdp or --dpdk for optional backends. Without trunk the script still builds the binary but skips the web UI.

3. Try it without any privileges

Rendering to a file needs no special rights, so you can check the installation first:

./target/release/wpg doctor
./target/release/wpg template lint templates/examples/*.wpg.yaml
./target/release/wpg render templates/examples/arp-sweep.wpg.yaml -o /tmp/arp.pcapng

wpg doctor reports what is missing for sending (see Permissions); a failing caps.raw_socket check is expected until the next step.

4. Allow raw sending

Either run as root or grant capabilities to the binary once (it is lost when the file is replaced):

sudo setcap cap_net_raw,cap_net_admin+ep ./target/release/wpg
./target/release/wpg doctor

5. Start the server

./target/release/wpg serve            # or: just run for development with hot reload

By default wpg listens on 127.0.0.1:8080 and loads the templates under ./templates. Open http://127.0.0.1:8080 in a browser; the next page, First login, covers the password and the first screens. To reach it from another machine, set a password and use --bind 0.0.0.0:8080 (or bind in wpg.toml, written by wpg config init); see Configuration. For a permanent installation on a lab host, scripts/deploy.sh copies the binary, applies setcap and installs a systemd unit; see CML2 notes.

Send your first frames

./target/release/wpg ifaces
./target/release/wpg send templates/examples/arp-sweep.wpg.yaml -i eth1 --rate 1000pps

Only send on networks you own or are authorised to test. Continue with the ARP sweep tutorial.

Install on macOS

Supported: macOS 12 or later. Release binaries are not published yet, so you build from source; the result is a single wpg executable with the web UI embedded. macOS ships libpcap, so no extra library is needed: scripts/build.sh (and just release) build the libpcap backend (pcap feature) automatically on macOS, because it is the only way wpg can send there (--no-pcap leaves it out). Release archives include it too.

1. Install the prerequisites

xcode-select --install                     # compiler and linker
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
brew install wireshark                     # optional: tshark, and ChmodBPF (see below)

git clone https://github.com/SeiyaFunaokaJP/web-packet-generator.git
cd web-packet-generator
./scripts/setup.sh                         # add --just to also install the just task runner

scripts/setup.sh installs the Rust toolchain pinned in rust-toolchain.toml with the WASM target, and a prebuilt trunk at the version pinned in scripts/versions.env.

2. Build

./scripts/build.sh --release        # or: just release

The last line printed is ==> done: target/release/wpg.

3. Try it without any privileges

./target/release/wpg doctor
./target/release/wpg template lint templates/examples/*.wpg.yaml
./target/release/wpg render templates/examples/arp-sweep.wpg.yaml -o /tmp/arp.pcapng

4. Allow sending

Sending goes through /dev/bpf*. Either run wpg with sudo, or make the devices accessible: installing Wireshark with its ChmodBPF helper does this for members of the access_bpf group. wpg doctor prints the exact hint for your machine; see Permissions.

5. Start the server

./target/release/wpg serve

wpg listens on 127.0.0.1:8080 by default and loads the templates under ./templates. Open http://127.0.0.1:8080 in a browser and continue with First login.

Send your first frames

./target/release/wpg ifaces
sudo ./target/release/wpg send templates/examples/arp-sweep.wpg.yaml -i en0 --rate 1000pps

Only send on networks you own or are authorised to test. Continue with the ARP sweep tutorial.

Release binaries: Gatekeeper and quarantine

Release archives (wpg-<version>-aarch64-apple-darwin.tar.gz for Apple silicon, ...-x86_64-apple-darwin.tar.gz for Intel) are not signed or notarised. A file downloaded with a browser gets the com.apple.quarantine attribute, and Gatekeeper then refuses to run it (““wpg” cannot be opened because Apple cannot check it for malicious software” or “… is damaged”). Building from source as above avoids this completely.

Check the download first, then remove the attribute from the extracted files:

shasum -a 256 -c wpg-0.2.0-aarch64-apple-darwin.tar.gz.sha256   # or compare with SHA256SUMS
tar -xzf wpg-0.2.0-aarch64-apple-darwin.tar.gz
xattr -dr com.apple.quarantine wpg-0.2.0-aarch64-apple-darwin
./wpg-0.2.0-aarch64-apple-darwin/wpg --version

Alternatives:

• Download with curl -LO instead of a browser: curl does not set the quarantine attribute.
• Try to run it once, then allow it in System Settings → Privacy & Security (“Open Anyway”); macOS asks again on the next start and then remembers it.
• The Finder shortcut (Control-click → Open) was removed in macOS 15 and never applied to command-line tools; use xattr or System Settings.

Do not disable Gatekeeper globally (spctl --master-disable). Remove the attribute again after every upgrade, since each new download is quarantined. For running wpg at boot, see Running as a service.

Install on Windows

Supported: Windows 10 21H2 or later. Release binaries are not published yet, so you build from source. Transmission uses Npcap only and is intended for GUI use at low to medium rates; use Linux for high rates. Commands below are for PowerShell.

Installing wpg on a Linux lab host from Windows? You do not need to build anything on Windows. Get the repository (git clone, or “Download ZIP” on GitHub and unpack it), then double-click scripts\deploy.bat. A wizard asks for the host, the SSH user and password, the sudo password, the admin password of the web UI and the interfaces to send on, builds wpg on the host and installs it as a service. Only the OpenSSH client that ships with Windows 10 / 11 is needed. See Deploying.

1. Install the prerequisites

1. Install rustup (choose the default MSVC toolchain; it asks for the Visual Studio Build Tools “Desktop development with C++” workload if it is missing).

2. Install Npcap (the default options are fine; the WinPcap API-compatible mode is not needed). Sending needs it.

3. Get the repository and run the setup script:

   git clone https://github.com/SeiyaFunaokaJP/web-packet-generator.git
   cd web-packet-generator
   .\scripts\setup.ps1              # add -Just to also install the just task runner
   

   It installs the Rust toolchain pinned in rust-toolchain.toml with the WASM target, a prebuilt trunk and the Npcap SDK (unpacked to C:\Npcap-SDK) at the versions pinned in scripts\versions.env, and lists anything still missing (the C++ build tools, Npcap). If PowerShell refuses to run scripts, start it with powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1.

   The SDK is needed to link the Npcap backend (pcap feature), the only way wpg can send on Windows. scripts\build.ps1 also finds an SDK you unpacked yourself in C:\npcap-sdk-<version> (the name of the zip; the newest version wins), in the directory named by the environment variable NPCAP_SDK, or through LIBPCAP_LIBDIR set to its Lib\x64 directory. Without the SDK the build still succeeds, but the resulting wpg.exe cannot send and build.ps1 warns about it.

4. Optional: Wireshark (for tshark).

2. Build

.\scripts\build.ps1 -Release       # or: just release

It prints ==> Npcap SDK: LIBPCAP_LIBDIR=... when it found the SDK and ends with ==> done: target\release\wpg.exe. The variants:

Without trunk the frontend is skipped with a warning (the web UI then serves a stale or missing crates\wpg-web\dist).

3. Try it without any privileges

.\target\release\wpg.exe doctor
.\target\release\wpg.exe render templates\examples\arp-sweep.wpg.yaml -o $env:TEMP\arp.pcapng

4. Allow sending

Check that wpg doctor reports Npcap as installed (npcap) and the Npcap backend as built in (backend.pcap). If backend.pcap fails, build.ps1 did not find the Npcap SDK: run .\scripts\setup.ps1 (step 1) and build again. With Npcap’s default install an ordinary PowerShell can send (caps.raw_socket is ok); if Npcap was installed with “Restrict Npcap driver’s access to Administrators only”, caps.raw_socket fails and you must open PowerShell as Administrator for sending. See Permissions.

5. Start the server

.\scripts\run.ps1                  # or: .\target\release\wpg.exe serve

wpg listens on 127.0.0.1:8080 by default and loads the templates under .\templates. Open http://127.0.0.1:8080 in a browser and continue with First login. Windows Firewall may ask whether to allow wpg.exe; allow private networks only if you bind to a non-local address.

Send your first frames

.\target\release\wpg.exe ifaces
.\target\release\wpg.exe send templates\examples\arp-sweep.wpg.yaml -i <interface> --rate 1000pps

Use the interface name printed by wpg ifaces (the bare {GUID}; \Device\NPF_{GUID} as printed by tshark -D works too). The Npcap loopback adapter (\Device\NPF_Loopback) does not accept Ethernet frames (PacketSendPacket failed ... (50)); to try sending without touching a real network, use a host-only virtual adapter such as Hyper-V’s vEthernet (Default Switch) or a VMware host-only adapter, and watch it with wpg capture -i <interface> --backend pcap --include-outgoing or tshark. Only send on networks you own or are authorised to test. Continue with the ARP sweep tutorial.

Release archive and Npcap check

Release archives (wpg-<version>-x86_64-pc-windows-msvc.zip) contain wpg.exe with the web UI and the Npcap backend, the sample templates and packaging\windows\wpg-service.ps1. They are not code-signed:

# Verify, then clear the "downloaded from the Internet" mark before extracting
(Get-FileHash .\wpg-0.2.0-x86_64-pc-windows-msvc.zip -Algorithm SHA256).Hash   # compare with SHA256SUMS
Unblock-File .\wpg-0.2.0-x86_64-pc-windows-msvc.zip
Expand-Archive .\wpg-0.2.0-x86_64-pc-windows-msvc.zip -DestinationPath "C:\Program Files\wpg"

If SmartScreen still shows “Windows protected your PC”, choose More info → Run anyway once.

Npcap is not bundled (its licence does not allow redistribution with the free edition). wpg.exe loads wpcap.dll only when the pcap backend is first used (it is linked with /DELAYLOAD) and adds System32\Npcap to the DLL search path itself, so it starts without Npcap and works with either Npcap install mode. Both wpg doctor and scripts\build.ps1 check for it:

• wpg doctor fails the npcap check when Npcap is missing and warns when Npcap looks installed but wpcap.dll is in neither System32\Npcap nor System32. The fix line links to https://npcap.com/#download.
• Sending without Npcap stops with Npcap is not installed; install it from https://npcap.com/#download and run wpg doctor instead of crashing.
• wpg doctor also fails backend.pcap when this wpg.exe was built without the Npcap backend, and tells you to unpack the SDK and run scripts\build.ps1 again.
• When Npcap was installed in administrator-only mode, caps.raw_socket fails in an unelevated terminal; the fix is an Administrator terminal or reinstalling Npcap without that option.
• scripts\build.ps1 prints a warning before building, since a build without Npcap succeeds but cannot send, and another one when it builds without the Npcap SDK.

To run wpg in the background at boot, see Running as a service.

Run with Docker

The image builds wpg and its web UI inside the container, so the host needs Docker and nothing else: no Rust toolchain, no trunk. Use a Linux host: Docker Desktop on macOS and Windows runs containers in a VM, and frames sent there never reach your physical NIC.

This page is the short path. Build options, proxies, every setting and the limits are in Docker.

1. Get the repository and start

git clone https://github.com/SeiyaFunaokaJP/web-packet-generator.git
cd web-packet-generator
WPG_PASSWORD='change me' WPG_ALLOWED_IFACES='["eth1"]' docker compose up -d --build

• WPG_PASSWORD is required: the server listens on every address of the host, so it refuses to start without a password. Pick your own; it is the administrator password of the web UI.
• WPG_ALLOWED_IFACES lists the interfaces jobs may send on. Use the name of your lab interface (ip -br link lists them); leave it out to allow all.
• The first build compiles everything and takes a while. Later starts reuse the image.

The container uses the host network and gets only CAP_NET_RAW and CAP_NET_ADMIN, so it can send on the host’s interfaces without running wpg as root on the host.

2. Check it

docker compose ps                         # STATUS shows "healthy" once the server answers
docker compose exec wpg wpg doctor        # raw sockets and interfaces, as the container sees them

Open http://127.0.0.1:8080 on the host (or http://<host>:8080 from another machine) and log in with the password. First login walks through the screens.

3. Try a template

The bundled templates are in /usr/share/wpg/templates inside the container and appear in the Templates screen. From the command line, render one to a file first (nothing is sent), then send it:

docker compose exec wpg wpg render /usr/share/wpg/templates/examples/arp-sweep.wpg.yaml -o /var/lib/wpg/arp.pcapng
docker compose exec wpg wpg send /usr/share/wpg/templates/examples/arp-sweep.wpg.yaml -i eth1 --rate 1000pps

/var/lib/wpg is the wpg-data volume: the database, your own templates and files such as the pcapng above survive restarts and image upgrades. Only send on networks you own or are authorised to test. Continue with the ARP sweep tutorial, using docker compose exec wpg wpg ... where the tutorial runs wpg ....

Stop, upgrade, remove

docker compose logs -f wpg                # follow the log
docker compose down                       # stop; the wpg-data volume is kept
git pull && WPG_PASSWORD='change me' docker compose up -d --build   # upgrade
docker compose down -v                    # stop and delete the wpg-data volume

To keep the settings out of your shell history, put them in a .env file next to docker-compose.yml (WPG_PASSWORD=..., WPG_ALLOWED_IFACES=..., WPG_BIND=...). The repository ignores .env in both git and the Docker build context, so the password is neither committed nor copied into the image.

Permissions

Sending raw frames is a privileged operation and the requirement differs per OS. At startup and on demand (wpg doctor) wpg runs a self-diagnosis and shows OS-specific guidance. Administrators can also restrict allowed interfaces and the maximum rate.

Linux

The afpacket backend needs CAP_NET_RAW (and CAP_NET_ADMIN is granted with it). Either run as root or grant the capabilities to the binary:

sudo setcap cap_net_raw,cap_net_admin+eip /path/to/wpg

This is the hint wpg doctor prints, with the real path of the running binary. If a backend is refused with EPERM/EACCES, the error says:

AF_PACKET needs CAP_NET_RAW: run as root or grant it with `sudo setcap cap_net_raw,cap_net_admin+ep $(command -v wpg)`

File capabilities are lost when the binary is replaced and are ignored on nosuid mounts; under systemd use AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN. See CML2 notes.

macOS

Needs read/write access to /dev/bpf*. Run with sudo, or make the devices accessible (for example with Wireshark’s ChmodBPF). The hint printed by wpg doctor is sudo /path/to/wpg … (or make /dev/bpf* accessible, e.g. via Wireshark's ChmodBPF).

Windows

Needs Npcap (either install mode; wpg finds wpcap.dll in System32\Npcap itself) and, only when Npcap was installed in administrator-only mode, an Administrator terminal. wpg doctor reads that setting (the AdminOnly value under HKLM\SYSTEM\CurrentControlSet\Services\npcap\Parameters): unelevated with the default install, caps.raw_socket is ok (npcap_admin_only=no); with administrator-only mode it fails with the hint Run from an elevated (Administrator) terminal, or reinstall Npcap ... without "Restrict Npcap driver's access to Administrators only"; when the setting cannot be read it is a warning. A missing Npcap points to https://npcap.com/#download.

Checking with wpg doctor

wpg doctor prints one line per check with a stable id in brackets; wpg doctor --json gives the same data for scripts. The exit status is non-zero when a check fails.

Each check reports ok, warn, fail or skip (not applicable on this OS).

First login

Start the server and open the address it prints:

wpg serve                       # listens on 127.0.0.1:8080

Setting the administrator password

The password can come from any of these (highest priority first; run wpg serve --help to see which ones your build supports):

1. wpg serve --password … or --password-file <file>
2. the WPG_PASSWORD environment variable
3. [auth] password_hash / password_file in wpg.toml (an argon2id hash, written by wpg config set-password)
4. the setup screen shown on the first visit, if none of the above is set

While no password exists wpg accepts connections from the local machine only and warns at startup; do not bind it to a non-local address until a password is set. Passwords are stored as argon2id hashes, sessions use HttpOnly, SameSite=Strict cookies, and repeated failed logins are rate limited. For access over a network, put TLS in front (--tls, a certificate in wpg.toml, or a reverse proxy).

The first screens

After logging in you land on the dashboard: interface state, running jobs and recent statistics. Then:

1. Templates: the bundled library (examples, protocols, scenarios, malformed) is listed here, searchable by tag (protocol:ipv4, layer:l3, scenario, malformed). Open one, or duplicate it to make your own.
2. Builder: stack layers, edit fields (Auto/Manual, generators) and watch the hex dump and field tree update. An empty builder offers common stacks such as “Ethernet II / IPv4 / UDP”, and every field shows an input prefilled with its default (MAC address, IP address, …). Typing makes it a manual value; ↺ goes back to the default.
   • By default the builder only makes packets that follow the protocol definitions. Computed fields such as lengths and checksums stay locked, and out-of-spec values (a length or checksum that does not match, a value outside its constraints, …) are shown as errors under the field and in the toolbar, and block saving and creating a job.
   • For malformed test traffic, turn on Allow malformed packets in the toolbar: computed fields get an “Override” button and out-of-spec values are only warnings. The switch is remembered per browser and turns on by itself when you open a template that is already out of spec (such as the malformed ones).
3. Jobs: pick templates, an interface, a rate and a count, and start. Write to a file instead of sending makes a dry run (a pcapng file). Burst, workers and the verification signature are under Advanced. A finished job can be started again with Run again, or copied into the form with Edit as new job.
4. Settings: language (Japanese, English, Simplified Chinese, Traditional Chinese, Korean, German, French, Spanish), theme, template library paths.

The language menu and the theme toggle are in the header of every screen.

If sending is refused, run wpg doctor and read Permissions. Then work through the ARP sweep tutorial.

Tutorial: ARP sweep

Time: about 15 minutes. Privileges: none until Step 5 (everything before it is a dry run).

What you will build

A stream of ARP requests (“who has 10.0.0.x?”) that walks every host address of a /22, and then the same sweep repeated inside several VLANs. ARP sweeps are the classic way to populate an ARP cache, to check that a switch floods broadcasts correctly, and to exercise a router’s ARP glean rate limiting.

You will use three bundled templates:

Before you start

Build wpg once (see Install on Linux, macOS or Windows) and run the commands from the repository root. The examples call the binary wpg; use ./target/release/wpg (or target\release\wpg.exe) if it is not on your PATH. tshark is optional but makes the checks below more convincing.

Only send on networks you own or are authorised to test; see the legal notice.

Step 1. Read the smallest sweep

layers:
  - protocol: ethernet2
    fields:
      dst: ff:ff:ff:ff:ff:ff
      src: ${src_mac}

  - protocol: arp
    fields:
      oper: request
      sha: ${src_mac}
      spa: ${src_ip}
      tha: 00:00:00:00:00:00
    generators:
      tpa: ${first}-${last}   # shorthand for a range generator

Two things do the work. generators.tpa varies the ARP target protocol address across the stream, and ${...} placeholders are template variables (declared in the variables: list with defaults) that you can override at run time with --var name=value. ethertype in the Ethernet layer is not written: it is Auto and becomes 0x0806 because the next layer is ARP.

Print the first frame:

$ wpg template show templates/scenarios/vlan-arp-sweep.wpg.yaml
Hex dump (60 bytes)
0000  ff ff ff ff ff ff 02 00  00 00 00 01 81 00 00 64  ...............d
0010  08 06 00 01 08 00 06 04  00 01 02 00 00 00 00 01  ................
0020  0a 00 00 fa 00 00 00 00  00 00 0a 00 00 01 00 00  ................
0030  00 00 00 00 00 00 00 00  00 00 00 00              ................
...

The last 14 octets are zero padding: an ARP request is 42 octets long and Ethernet needs 60 (the FCS is added by the NIC).

Step 2. Sweep a whole /22

arp-sweep-slash22.wpg.yaml swaps the range for a CIDR block held in a variable:

variables:
  - name: net
    default: 10.0.0.0/22
layers:
  - protocol: arp
    generators:
      tpa: ${net}

A CIDR generator yields the host addresses only, so a /22 gives 1022 frames (10.0.0.1 to 10.0.3.254). Render it to a pcapng file without touching the network:

$ wpg render templates/scenarios/arp-sweep-slash22.wpg.yaml -o /tmp/sweep.pcapng
Wrote 1022 packets to /tmp/sweep.pcapng.

Point the same template at another subnet without editing it:

$ wpg render templates/scenarios/arp-sweep-slash22.wpg.yaml -o /tmp/sweep.pcapng --var net=10.1.0.0/22

Step 3. Repeat the sweep in several VLANs

vlan-arp-sweep.wpg.yaml inserts an 802.1Q tag and adds a second generator:

  - protocol: dot1q
    generators:
      vid: ${vids}          # default 100-103

  - protocol: arp
    generators:
      tpa: ${first}-${last} # default 10.0.0.1-10.0.0.254

stream:
  mode: nested
  order: [dot1q.vid, arp.tpa] # slowest first

With two generators you have to say how they combine. zip advances both in lockstep, product is the Cartesian product, and nested is a product with an explicit order: here the VLAN is the slow loop, so all 254 addresses are asked in VLAN 100, then in VLAN 101, and so on: 4 x 254 = 1016 frames. Restrict it to two VLANs with a list:

$ wpg render templates/scenarios/vlan-arp-sweep.wpg.yaml -o /tmp/vlan-sweep.pcapng --var vids=100,200
Wrote 508 packets to /tmp/vlan-sweep.pcapng.

Step 4. Check the frames

$ tshark -r /tmp/vlan-sweep.pcapng -T fields -e vlan.id -e arp.dst.proto_ipv4 | sed -n '1p;254p;255p;$p'
100	10.0.0.1
100	10.0.0.254
200	10.0.0.1
200	10.0.0.254

Also run wpg template lint on any template you edit: it catches unknown fields, out-of-range values and bad generator syntax before you send.

Step 5. Send it

First rehearse with a backend that writes a file (for pcapfile the -i argument is the output path) or discards the frames (null):

$ wpg send templates/scenarios/arp-sweep-slash22.wpg.yaml --backend null -i lo --rate 100kpps
Sending on lo via null: rate 100000pps, burst 1, 1022 packets, 1 worker(s), plan PreRender (...)
state      finished (stream exhausted)
packets    1022
bytes      61320

Then send for real on your lab interface. Raw sending needs privileges (see Permissions); run wpg ifaces to pick the interface and wpg doctor if the backend is refused:

$ wpg ifaces
$ wpg send templates/scenarios/vlan-arp-sweep.wpg.yaml -i eth1 --rate 2000pps

The command runs the stream once (1016 frames at 2000 frames per second is about half a second) and prints a summary. Add --count 10000 to loop the sweep, or --duration 30s to run for a fixed time.

Step 6. Read the result

• On the device under test, look at the ARP or neighbour table (ip neigh, show ip arp) and at the MAC table of the switch (the sender MAC 02:00:00:00:00:01 should appear on the port and in the VLANs you used).
• On a Linux host in the same segment, tcpdump -e -n -i eth1 arp shows the requests with their VLAN tags.
• The sweep uses a made-up sender address (10.0.0.250). Change src_mac and src_ip with --var so that replies come back to an address you can observe.

Next steps

• VLAN-tagged TCP SYN flood for random source addresses and TCP options.
• Load and rate control for --rate, --duration and multi-worker sending.
• Template schema for every generator kind.

Tutorial: VLAN-tagged TCP SYN flood

Time: about 20 minutes. Privileges: none until Step 5.

What you will build

A stream of 100,000 TCP SYN segments in an 802.1Q VLAN, each with a random source address, source port and initial sequence number, and the usual SYN options (MSS, SACK-permitted, window scale). It is the standard way to load a firewall, load balancer or connection-tracking table from many “clients” while you watch the device’s SYN handling. wpg is stateless: it never completes a handshake and does not answer SYN-ACKs.

Use it only against equipment in a lab that you own or are authorised to test.

Before you start

Build wpg and run from the repository root (see Install on Linux). The template is templates/scenarios/vlan-syn-flood.wpg.yaml; a smaller relative is templates/examples/vlan-tcp-syn.wpg.yaml.

Step 1. Read the template

layers:
  - protocol: ethernet2
    fields: { dst: ${dst_mac}, src: ${src_mac} }

  - protocol: dot1q                 # TPID 0x8100 goes into ethernet2 automatically
    fields:
      vid: ${vid}

  - protocol: ipv4
    fields:
      dst: ${dst_ip}
      ttl: 64
      flags: df
    generators:
      src: { kind: random, min: 10.0.0.1, max: 10.255.255.254 }

  - protocol: tcp
    fields:
      dst_port: ${dst_port}
      flags: syn
      window: 64240
      options:
        - mss: 1460
        - sack_permitted
        - ws: 7
    generators:
      src_port: { kind: random, min: 1024, max: 65535 }
      seq: { kind: random, min: 0, max: 4294967295 }

stream:
  seed: 7
  count: 100000

tx:
  rate: 50kpps
  burst: 32

Points worth knowing:

• Nothing else is written. IPv4 ihl, total_length, protocol and header_checksum, TCP data_offset and checksum (with the IPv4 pseudo header), and the dot1q/Ethernet EtherTypes are all Auto and are recomputed for every frame. The TCP options region is padded to a 32-bit boundary automatically.
• Options are typed. mss: 1460, sack_permitted, ws: 7, nop and timestamps: { tsval: 1000, tsecr: 0 } are the built-in names; anything else can be written as { type: 99, data: "01 02" }.
• stream.seed makes random reproducible. The same seed produces the same 100,000 frames on every run and on every machine.
• tx.rate and tx.burst are only defaults; wpg send --rate overrides them.

Step 2. Look at the first frames

$ wpg render templates/scenarios/vlan-syn-flood.wpg.yaml -o /tmp/syn.pcapng --count 3
Wrote 3 packets to /tmp/syn.pcapng.
$ tshark -r /tmp/syn.pcapng -o tcp.check_checksum:TRUE
    1   0.000000 10.114.228.243 → 198.51.100.7 TCP 70 2311 → 443 [SYN] Seq=0 Win=64240 Len=0 MSS=1460 SACK_PERM WS=128
    2   0.000001 10.99.228.10 → 198.51.100.7 TCP 70 51321 → 443 [SYN] Seq=0 Win=64240 Len=0 MSS=1460 SACK_PERM WS=128
    3   0.000002 10.251.163.120 → 198.51.100.7 TCP 70 10483 → 443 [SYN] Seq=0 Win=64240 Len=0 MSS=1460 SACK_PERM WS=128

Wireshark reports no bad checksum. (Seq=0 is the relative sequence number Wireshark displays; the raw values are random.) tshark -V -c 1 shows the 802.1Q header with ID: 100.

Step 3. Change the target without editing the file

All the ${...} placeholders are variables; their defaults are in the variables: list at the top of the file. Override any of them on the command line:

$ wpg render templates/scenarios/vlan-syn-flood.wpg.yaml -o /tmp/syn.pcapng \
      --var vid=200 --var dst_ip=203.0.113.9 --var dst_port=8443 --count 1000

Use --var src_mac=… and --var dst_mac=… to set the MAC addresses; the next hop’s MAC on the sending interface is what the device under test expects as the destination.

Step 4. Understand count, seed and the pre-render plan

The stream has a fixed length (stream.count: 100000). wpg send pre-renders small streams into memory (limit 256 MiB by default) and expands large ones on the fly; force either with --plan prerender or --plan onthefly.

Step 5. Send it

Rehearse first, then send on the lab interface (see Permissions):

$ wpg send templates/scenarios/vlan-syn-flood.wpg.yaml --backend null -i lo --rate 20kpps --count 5000
$ wpg send templates/scenarios/vlan-syn-flood.wpg.yaml -i eth1 --rate 50kpps \
      --var vid=200 --var dst_ip=203.0.113.9 --var dst_mac=00:11:22:33:44:55

Start gently and climb: --ramp-up 10s increases the rate linearly from zero, which is kind to devices that fall over at the first burst. See Load and rate control.

Step 6. Read the result

• Watch the connection or SYN counters on the firewall or load balancer (show conn count, conntrack -C, SYN-cookie counters).
• On a Linux target, nstat -az TcpExtTCPReqQFullDoCookies and ss -s show what the SYN queue did.
• On the sending side, the summary at the end of wpg send gives packets, bytes, dropped and the achieved rate compared to the target.

Next steps

• Replace flags: syn with syn|ack, rst, or fin|ack to test how a stateful device treats out-of-state segments.
• Use templates/scenarios/tcp-syn-port-scan.wpg.yaml to scan destination ports 1-1024 instead.
• pcap to template replay turns a real capture into a template you can edit.

Tutorial: IPv6 and Neighbor Discovery

Time: about 25 minutes. Privileges: none until Step 6.

This page uses the IPv6 stack to practise two ideas: several layers whose type, length and checksum fields are derived from each other, and a link-layer multicast address computed from a network-layer one. The OSI stack without IP (IS-IS over LLC) is covered in Bringing up an IS-IS adjacency with Hellos.

What you will build

The four kinds of Neighbor Discovery messages that make IPv6 work on a link, then a sweep of Neighbor Solicitations:

Before you start

Build wpg and run from the repository root. Only send on lab networks you own or are authorised to test: forged RAs can disrupt every host on a segment.

Step 1. Follow the layers of one Neighbor Solicitation

$ wpg template show templates/protocols/l3/ndp-ns.wpg.yaml
Hex dump (86 bytes)
0000  33 33 ff 00 00 02 02 00  00 00 00 01 86 dd 60 00  33............`.
0010  00 00 00 20 3a ff 20 01  0d b8 00 00 00 00 00 00  ... :. .........
...
Layout
[0] ethernet2  bytes 0..86
  dst: 33:33:ff:00:00:02
  src: 02:00:00:00:00:01
  ethertype: 0x86dd (ipv6)  (auto)
[1] ipv6  bytes 14..86
  payload_length: 32  (auto)
  next_header: 0x3a (icmpv6)  (auto)
  hop_limit: 255
  src: 2001:db8::1
  dst: ff02::1:ff00:2
[2] icmpv6  bytes 54..86
  type: 0x87 (neighbor_solicitation)  (auto)
  code: 0
  checksum: 7207  (auto)
[3] ndp_ns  bytes 58..86
  reserved: 0
  target: 2001:db8::2
  options: 01 01 02 00 00 00 00 01

Every (auto) value was derived, not typed:

• ethernet2.ethertype = 0x86dd because the next layer is ipv6.
• ipv6.next_header = 58 because the next layer is icmpv6, and payload_length counts everything after the 40-octet header.
• icmpv6.type = 135 because the next layer is ndp_ns. The ICMPv6 message is split in two layers on purpose: icmpv6 holds type, code and checksum, and the body layer (ndp_ns, ndp_na, ndp_rs, ndp_ra, ndp_redirect, icmpv6_echo) selects the type.
• icmpv6.checksum covers the IPv6 pseudo header, the ICMPv6 header and the whole body, so it changes whenever any field below it changes.

The YAML behind it is short:

layers:
  - protocol: ethernet2
    fields: { dst: "33:33:ff:00:00:02", src: "02:00:00:00:00:01" }
  - protocol: ipv6
    fields:
      src: 2001:db8::1
      dst: ff02::1:ff00:2
      hop_limit: 255          # NDP requires 255
  - protocol: icmpv6          # type: auto
  - protocol: ndp_ns
    fields:
      target: ${target}
      options: "01 01 02 00 00 00 00 01"   # source link-layer address

Step 2. Two addresses that must agree

A Neighbor Solicitation for 2001:db8::2 goes to the solicited-node multicast group ff02::1:ff00:2 (ff02::1:ff plus the low 24 bits of the target) and, on Ethernet, to the multicast MAC 33:33: plus the low 32 bits of the IPv6 destination: 33:33:ff:00:00:02. wpg does not derive one address from the other, so if you change target you must change ipv6.dst and ethernet2.dst too (or send to the all-nodes group ff02::1 / 33:33:00:00:00:01 as the sweep does).

Also note hop_limit: 255. Receivers drop NDP messages that arrive with any other value, so leaving the default of 64 produces packets that look right in Wireshark and do nothing.

Step 3. Options are raw bytes

NDP options (options) are written as hex. 01 01 02 00 00 00 00 01 is type 1 (source link-layer address), length 1 (in 8-octet units), then the six-octet MAC. The Router Advertisement template chains three options:

options: >-
  01 01 02 00 00 00 00 01
  05 01 00 00 00 00 05 dc
  03 04 40 c0 00 27 8d 00 00 09 3a 80 00 00 00 00
  20 01 0d b8 00 01 00 00 00 00 00 00 00 00 00 00

Because the options are raw octets you can also build deliberately odd ones: a zero-length option, an option that runs past the end of the packet, or an unknown type.

Step 4. Verify with Wireshark

$ wpg render templates/protocols/l3/ndp-ns.wpg.yaml -o /tmp/ns.pcapng
$ tshark -r /tmp/ns.pcapng -V | sed -n '/Internet Control/,$p'
Internet Control Message Protocol v6
    Type: Neighbor Solicitation (135)
    Code: 0
    Checksum: 0x1c27 [correct]
    [Checksum Status: Good]
    Reserved: 00000000
    Target Address: 2001:db8::2
    ICMPv6 Option (Source link-layer address : 02:00:00:00:00:01)

[correct] is the important part: wpg computed the pseudo-header checksum itself.

Step 5. Sweep it

ndp-ns-sweep.wpg.yaml puts an IPv6 range in the target generator:

  - protocol: ndp_ns
    generators:
      target: 2001:db8::1-2001:db8::100

$ wpg render templates/scenarios/ndp-ns-sweep.wpg.yaml -o /tmp/ns-sweep.pcapng
Wrote 256 packets to /tmp/ns-sweep.pcapng.

Since the destination is the all-nodes group, every host on the segment sees all 256 solicitations and answers only for the addresses it owns. A real host would send each one to that target’s own solicited-node group; the sweep trades that for a single, simple template.

ra-flood.wpg.yaml shows random generators for the source MAC (random_mac with a fixed OUI) and the source link-local address, both reproducible via stream.seed.

Step 6. Send it

$ wpg send templates/scenarios/ndp-ns-sweep.wpg.yaml --backend null -i lo --rate 1000pps
$ wpg send templates/scenarios/ndp-ns-sweep.wpg.yaml -i eth1 --rate 1000pps

(Privileges: see Permissions.) On the target, ip -6 neigh, ndisc6 output or show ipv6 neighbors show what was learned, and tcpdump -n -i eth1 icmp6 on another host shows the solicitations and any advertisements.

Where other ICMPv6 types go

For a type that has no body protocol yet (for example MLD), set icmpv6.type explicitly and follow it with a raw layer that contains the four octets after the checksum and then the message. The same trick lets you send IPv6 extension-header chains, which have their own samples: templates/protocols/l3/ipv6-hopopts, ipv6-dstopts, ipv6-routing, ipv6-frag and ipv6-ext-chain.

Next steps

• Load and rate control for sending the RA flood at a chosen rate.
• Protocol reference for every IPv6 and ICMPv6 field.

Tutorial: Load and rate control

Time: about 20 minutes. Privileges: none (the null and pcapfile backends are used throughout).

The skills below (mass generation, rate, duration, ramp-up, workers) work with any template. For an example that loads a real server and counts its answers, see Load-testing a DHCP server.

What you will build

Commands that push a template at a chosen rate for a chosen amount of time, read the summary that comes back, and stay inside the limits of a lab. The example templates are the MAC flood (templates/scenarios/mac-flood.wpg.yaml, 100,000 frames with random source MACs) and the SYN flood (templates/scenarios/vlan-syn-flood.wpg.yaml).

Before you start

Build wpg and run from the repository root. Real transmission needs privileges and a lab interface; this tutorial uses --backend null (frames are built and counted but not sent), so you can run every command anywhere. Replace --backend null -i lo with -i eth1 to send for real.

Only load devices you own or are authorised to test.

Step 1. Count, duration and rate

The stopping condition and the speed come from the template’s tx: block and can be overridden on the command line:

If both count and duration are set, whichever comes first ends the run. Rates in bps count Layer-1 bytes (preamble, FCS and inter-frame gap included, as on the wire); % needs a real interface with a known link speed (it fails on lo).

$ wpg send templates/scenarios/udp-qos-matrix.wpg.yaml --backend null -i lo --rate 250kpps --count 50000
Sending on lo via null: rate 250000pps, burst 1, 50000 packets, 1 worker(s), plan PreRender (...)
state      finished (count reached)
backend    null
packets    50000
bytes      10100000
dropped    0
elapsed    0.200 s
average    250.00 kpps  404.00 Mbps (L2)  452.00 Mbps (L1)
accuracy   target 250.00 kpps  achieved 100.00%  max jitter 454.12µs  mean jitter 202ns

(The numbers on your machine will differ.) Read the last two lines first: average is what was actually sent, and accuracy tells you how close the pacing got to the target. A large dropped means the backend could not keep up.

Step 2. Ramp up

Devices that fall over on the first burst are easier to characterise if the rate climbs. --ramp-up increases the rate linearly from zero to the target over the given time:

$ wpg send templates/scenarios/vlan-syn-flood.wpg.yaml --backend null -i lo --rate 20kpps --ramp-up 1s --duration 3s
[    3.0 s]        50023 pkts  16.67 kpps  9.34 Mbps  dropped 0  rate 100.0%
state      finished (duration elapsed)
packets    50023
elapsed    3.000 s
average    16.67 kpps  9.34 Mbps (L2)  12.54 Mbps (L1)
accuracy   target 20.00 kpps  achieved 100.04%  max jitter 3.196862ms  mean jitter 115.686µs

The average (16.67 kpps) is below the 20 kpps target because the first second was the ramp.

Step 3. Start at a chosen time

--start-at waits before the first frame: a delay (+10s) or an RFC 3339 time (2026-09-29T12:00:00Z). It is handy for starting two senders together or for giving yourself time to start a capture:

$ wpg send templates/scenarios/vlan-syn-flood.wpg.yaml --backend null -i lo --start-at +2s --count 10
Scheduled start at +2s (in 2.0 s); Ctrl-C cancels.

Step 4. Use several workers

A single worker is limited by one CPU core. --workers N starts N transmit threads, each with its own backend instance and its own share of the stream and of the rate; --pin-cores 2,3 pins them to cores (Linux):

$ wpg send templates/scenarios/vlan-syn-flood.wpg.yaml --backend null -i lo --rate unlimited --count 100000 --workers 2
average    10.35 Mpps  5.79 Gbps (L2)  7.78 Gbps (L1)
worker 0     50000 pkts  3500000 bytes
worker 1     50000 pkts  3500000 bytes

unlimited on the null backend measures how fast frames can be built; it is not a network figure. For the afpacket backend also see --batch, --ring-depth, --qdisc-bypass and --no-tx-ring in wpg send --help, and Performance tuning.

Step 5. Pre-render or generate on the fly

--plan auto (default) pre-renders the stream into memory when it is small (256 MiB threshold) so the transmit loop only copies bytes, and expands it on the fly when it is larger. Force one with --plan prerender or --plan onthefly. Random generators take their values from stream.seed, so set one when you need a reproducible stream.

Step 6. Machine-readable results

--json prints the final report as JSON on standard output (progress and banners go to standard error), for CI jobs and scripts:

$ wpg send templates/scenarios/mac-flood.wpg.yaml --backend null -i lo --count 100000 --json | jq '{state: .state.state, packets: .backend.packets, dropped: .backend.dropped}'

The exit status is non-zero when the run failed (for example a refused backend), so wpg send can be a step in a pipeline.

Step 7. Keep it inside limits

• Set an absolute upper bound for everyone with [tx] max_rate in wpg.toml (for example max_rate = "100kpps") and restrict interfaces with allowed_ifaces; see Configuration.
• Ctrl-C cancels a run.
• Use a rehearsal backend (null, or pcapfile with -i out.pcapng) before every new template.

Next steps

• pcap to template replay to load a device with traffic recorded from a real network.
• Performance tuning for the per-backend knobs.

Tutorial: pcap to template replay

Time: about 20 minutes. Privileges: none until the last step.

What you will build

A round trip: take a capture (here one produced by wpg so the commands are reproducible, but any Ethernet pcap or pcapng works), convert it into an editable template, and render it back to the same bytes. Along the way wpg recognises which fields vary between packets and turns them into generators.

wpg import reads pcap (both byte orders, microsecond and nanosecond) and pcapng, Ethernet link type only, and assumes frames carry no FCS. It can also read pasted hex.

Before you start

Build wpg and run from the repository root. tshark is only used for checking.

Step 1. Make a capture

$ wpg render templates/examples/arp-sweep.wpg.yaml -o /tmp/arp.pcapng
Wrote 254 packets to /tmp/arp.pcapng.

In real life this file would come from tcpdump -i eth0 -w capture.pcap or Wireshark.

Step 2. Import it

$ wpg import /tmp/arp.pcapng -o /tmp/arp.wpg.yaml
Imported 254 packet(s) into 1 template(s): /tmp/arp.wpg.yaml

The result:

schema: 1
meta:
  name: arp
  description: Imported from /tmp/arp.pcapng (254 packets)
  ...
  tags:
  - imported
layers:
- protocol: ethernet2
  fields:
    dst: ff:ff:ff:ff:ff:ff
    src: 02:00:00:00:00:01
    ethertype: auto
- protocol: arp
  fields:
    htype: ethernet
    ptype: ipv4
    hlen: 6
    plen: 4
    oper: request
    sha: 02:00:00:00:00:01
    spa: 192.168.1.10
    tha: 00:00:00:00:00:00
  generators:
    tpa:
      kind: range
      start: 192.168.1.1
      end: 192.168.1.254
      step: 1
- protocol: raw
  fields:
    data: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
stream:
  mode: zip
  count: 254

Three things happened:

1. Fields are in human notation (192.168.1.10, request, ethernet), and fields that wpg can recompute were put back to auto only where doing so reproduces the captured bytes. A capture with a wrong checksum or length keeps that field as a manual value, so deliberately malformed traffic survives the trip.
2. Generator inference. All 254 frames have the same layer stack, and arp.tpa changes by +1 each time, so it became a range generator (an exact one). Other patterns are recognised too: a repeating cycle becomes list, a small set of values becomes an approximate list, and anything else becomes a random generator over the observed minimum and maximum (wpg warns when the result is approximate). Use --no-detect-generators to keep only the first packet’s values.
3. The 18 zero octets after ARP are the Ethernet padding that was in the capture. The importer keeps bytes it cannot attribute to a protocol in a raw layer so the frame is reproduced exactly. You may delete that layer: with packet.pad_to_min (the default) wpg pads the frame itself.

Step 3. Lint and render again

$ wpg template lint /tmp/arp.wpg.yaml
/tmp/arp.wpg.yaml: no issues
0 error(s), 0 warning(s) in 1 file(s)
$ wpg render /tmp/arp.wpg.yaml -o /tmp/arp2.pcapng
Wrote 254 packets to /tmp/arp2.pcapng.
$ diff <(tshark -r /tmp/arp.pcapng -x) <(tshark -r /tmp/arp2.pcapng -x) && echo identical
identical

The frames are byte-for-byte the same (timestamps differ, since wpg writes its own).

Step 4. Edit and reuse

Because it is now a template, you can change anything:

• Turn constants into variables: replace 192.168.1.10 by ${src_ip} and add variables: [{ name: src_ip, default: 192.168.1.10 }], then run wpg render … --var src_ip=10.9.8.7.
• Widen the sweep: change the range to 192.168.0.1-192.168.7.254.
• Set oper: reply to turn the capture into replies.
• Add packet: { fcs: bad } to see how a device treats a bad FCS.

Step 5. One template per packet, or from pasted hex

For a capture of a conversation rather than a sweep, ask for one template per packet:

$ wpg import /tmp/capture.pcap --per-packet /tmp/templates/

A packet copied from Wireshark (“Copy → as a Hex Stream”), a xxd/hexdump -C listing or plain spaced bytes can be piped in:

$ echo "ff ff ff ff ff ff 02 00 00 00 00 01 08 06 00 01 08 00 06 04 00 01 02 00 00 00 00 01 c0 00 02 01 00 00 00 00 00 00 c0 00 02 02" \
    | wpg import --hex - -o -

For captures that start with something other than Ethernet II, use --first-protocol. Frames that use a protocol wpg does not know are kept as raw bytes after the last layer it could decode, so they still replay.

Step 6. Share and replay

Pack the template and the original capture into a bundle that a colleague can import:

$ wpg template export /tmp/arp.wpg.yaml -o /tmp/arp.wpgbundle --attach /tmp/arp.pcapng
$ wpg template import /tmp/arp.wpgbundle -o ./my-templates

Send the template like any other, with a rate of your choice:

$ wpg send /tmp/arp.wpg.yaml -i eth1 --rate 500pps

See Load and rate control for the options.

Next steps

• Template schema for everything you can put in the file.
• ARP sweep, VLAN-tagged TCP SYN flood and IPv6 and Neighbor Discovery.

Tutorial: Load-testing a DHCP server

Time: about 25 minutes. Privileges: none until Step 3; root from Step 4 (network namespace and afpacket).

What you will build

A stream of DHCPDISCOVERs from many simulated clients, and a count of the DHCPOFFERs the server sends back, to find the rate the server can keep up with. Every frame changes the source MAC and chaddr (the client hardware address) together and uses a random transaction ID (xid). The server is dnsmasq running in a network namespace on the same Linux host.

wpg is stateless. It does not answer an OFFER with a DHCPREQUEST, so DORA (Discover / Offer / Request / Ack) never completes and no lease is created. What you measure is how fast the server handles DISCOVERs, not pool exhaustion (Step 6).

Only use this against DHCP servers you own or are authorised to test. A burst of DISCOVERs on a production segment can stop real clients from getting an address.

Before you start

Build wpg and run from the repository root (Installing on Linux). The template is templates/scenarios/dhcp-discover-flood.wpg.yaml; a single-frame example is templates/protocols/app/dhcpv4-discover.wpg.yaml. From Step 4 you need Linux, iproute2, dnsmasq (sudo apt install dnsmasq-base) and root.

Step 1. Read the template

variables:
  - name: oui
    default: "02:00:5e"

layers:
  - protocol: ethernet2
    fields:
      dst: "ff:ff:ff:ff:ff:ff"
    generators:
      src: { kind: range, start: "${oui}:00:00:01", end: "${oui}:ff:ff:ff" } # one MAC per client
  - protocol: ipv4
    fields:
      src: 0.0.0.0
      dst: 255.255.255.255
  - protocol: udp
    fields:
      src_port: 68
      dst_port: 67
  - protocol: dhcpv4
    fields:
      op: boot_request
      flags: broadcast
      options:
        - { message_type: discover }
        - { parameter_request_list: [1, 3, 6, 15, 51] } # mask, router, DNS, domain, lease
        - end
    generators:
      chaddr: { kind: expr, expr: "$0.src" } # the same MAC as the Ethernet source (layer 0)
      xid: { kind: expr, expr: "rand(0, 0xffffffff)" }

stream:
  seed: 1
  count: 10000

tx:
  rate: 200pps

Things worth knowing:

• Source MACs are sequential. range works on MAC addresses too and counts up from 02:00:5e:00:00:01. The 02 first octet marks a locally administered address that cannot clash with real hardware. --var oui=… changes the upper three octets.
• chaddr copies the source MAC through an expression. In an expr generator, $0.src means “this frame’s value of the src generator in layer 0 (ethernet2)”. Servers usually identify a client by chaddr, so the two must not drift apart. The expression syntax is in Template schema.
• xid is random per frame. rand(min, max) is derived from the frame index, so the same stream.seed gives the same values on every run.
• Fields you do not write are Auto or defaults. IPv4 length and checksum and UDP length and checksum (with the pseudo-header) are Auto; DHCP htype / hlen, the zero-filled sname and file, and the magic cookie come from defaults.

Step 2. Look at the first frames

$ wpg render templates/scenarios/dhcp-discover-flood.wpg.yaml -o /tmp/dhcp.pcapng --count 3
Wrote 3 packets to /tmp/dhcp.pcapng.
$ tshark -r /tmp/dhcp.pcapng
    1   0.000000      0.0.0.0 → 255.255.255.255 DHCP 293 DHCP Discover - Transaction ID 0xc4c98940
    2   0.000001      0.0.0.0 → 255.255.255.255 DHCP 293 DHCP Discover - Transaction ID 0xef7b0650
    3   0.000002      0.0.0.0 → 255.255.255.255 DHCP 293 DHCP Discover - Transaction ID 0x330355d7
$ tshark -r /tmp/dhcp.pcapng -o udp.check_checksum:TRUE -T fields -e eth.src -e dhcp.hw.mac_addr -e udp.checksum.status
02:00:5e:00:00:01	02:00:5e:00:00:01	1
02:00:5e:00:00:02	02:00:5e:00:00:02	1
02:00:5e:00:00:03	02:00:5e:00:00:03	1

The source MAC matches Client MAC address, and the UDP checksum is reported good (1). The same holds for all 10,000 frames:

$ wpg render templates/scenarios/dhcp-discover-flood.wpg.yaml -o /tmp/dhcp-all.pcapng
Wrote 10000 packets to /tmp/dhcp-all.pcapng.
$ tshark -r /tmp/dhcp-all.pcapng -Y 'eth.src != dhcp.hw.mac_addr' | wc -l
0

Step 3. Change the scale

--count sets the number of clients. Past the 10,000 of stream.count the MAC sequence starts over, so for more clients add a second stream with a different --var oui=…:

$ wpg render templates/scenarios/dhcp-discover-flood.wpg.yaml -o /tmp/dhcp-b.pcapng --var oui=02:00:5f
Wrote 10000 packets to /tmp/dhcp-b.pcapng.

The source MACs in this file run from 02:00:5f:00:00:01 to 02:00:5f:00:27:10 (10000 = 0x2710).

Step 4. Set up a DHCP server to test

Start dnsmasq in a namespace wpgdhcp, connected to wpg by a veth pair (dh0 ⇔ dhs0), with a 50-address pool:

sudo ip netns add wpgdhcp
sudo ip link add dh0 type veth peer name dhs0
sudo ip link set dhs0 netns wpgdhcp
sudo ip link set dh0 up
sudo ip netns exec wpgdhcp ip link set lo up
sudo ip netns exec wpgdhcp ip link set dhs0 up
sudo ip netns exec wpgdhcp ip addr add 10.98.0.1/24 dev dhs0
sudo ip netns exec wpgdhcp dnsmasq --no-daemon --port=0 --interface=dhs0 --bind-interfaces \
    --dhcp-range=10.98.0.10,10.98.0.59,10m --dhcp-authoritative --dhcp-leasefile=/tmp/wpg-leases \
    --log-dhcp --log-facility=/tmp/wpg-dnsmasq.log &

--port=0 turns DNS off. To test a real DHCP server or router, use the lab interface that reaches it instead of dh0.

Step 5. Send and count the OFFERs

Count OFFERs (source port 67) with wpg capture while another terminal sends 100 DISCOVERs:

$ sudo wpg capture -i dh0 -f "udp src port 67" --duration 3s --show 2 -w /tmp/offers.pcapng
$ sudo wpg send templates/scenarios/dhcp-discover-flood.wpg.yaml -i dh0 --backend afpacket --count 100

Capturing on dh0 via afpacket, filter udp src port 67 (Ctrl-C stops)
#   0  16:14:33.696984775    342 B  ethernet2 / ipv4 / udp / dhcpv4
#   1  16:14:33.703225873    342 B  ethernet2 / ipv4 / udp / dhcpv4
state      finished (duration elapsed)
...
matched    100 pkts  34200 bytes
saved      100 pkts to /tmp/offers.pcapng
$ tshark -r /tmp/offers.pcapng -c 3
    1   0.000000    10.98.0.1 → 255.255.255.255 DHCP 342 DHCP Offer    - Transaction ID 0xc4c98940
    2   0.006241    10.98.0.1 → 255.255.255.255 DHCP 342 DHCP Offer    - Transaction ID 0xef7b0650
    3   0.009784    10.98.0.1 → 255.255.255.255 DHCP 342 DHCP Offer    - Transaction ID 0x330355d7

Each OFFER carries the xid of its DISCOVER (Step 2). The broadcast flag is set, so the OFFERs go to 255.255.255.255.

Your first run will probably look very slow. By default dnsmasq sends an ICMP Echo to an address before offering it, to make sure it is unused. That costs about 3 seconds per DISCOVER, so a 3-second capture counts a single OFFER (the log /tmp/wpg-dnsmasq.log shows one DHCPOFFER every 3 seconds). The result above is with dnsmasq restarted with --no-ping. Finding limits like this one, set by how the server is built, is one of the points of this kind of test.

Now raise the rate to find where the OFFERs stop keeping up:

for r in 1kpps 5kpps 20kpps; do
  sudo wpg capture -i dh0 -f "udp src port 67" --duration 4s --show 0 > /tmp/cap-$r.txt &
  sudo wpg send templates/scenarios/dhcp-discover-flood.wpg.yaml -i dh0 --backend afpacket --count 2000 --rate $r
  wait; grep '^matched' /tmp/cap-$r.txt
done

Results in the development container (--no-ping); yours depend on the host and the server:

The rate at which the answered share starts to fall is a rough measure of the server’s DISCOVER capacity. The unanswered DISCOVERs were dropped in the server’s socket receive buffer. On real equipment, DHCP snooping or CoPP (control-plane policing) may drop them first, so check the switch or router counters too.

Step 6. Read the results

• An OFFER does not reserve the address. The pool has 50 addresses, yet all 100 DISCOVERs were answered, with 50 distinct addresses offered (tshark -r /tmp/offers.pcapng -T fields -e dhcp.ip.your | sort -u | wc -l). dnsmasq, like most servers, creates the lease on REQUEST / ACK, so DISCOVERs alone do not exhaust a pool. The lease file (/tmp/wpg-leases) stays empty.
• Tests that create leases are out of scope for wpg. Answering an OFFER with a REQUEST is stateful, which is a non-goal. For pool exhaustion or lease-holding tests use a DHCP client emulator such as perfdhcp.
• Through a relay: start from templates/protocols/app/dhcpv4-relay.wpg.yaml (unicast, with giaddr and option 82). Set the destination to the server’s address to test a server behind a router.
• For DHCPv6 there are templates/protocols/app/dhcpv6-solicit.wpg.yaml and dhcpv6-relay-forward.wpg.yaml.

Clean up:

sudo pkill -f 'dnsmasq --no-daemon --port=0 --interface=dhs0'
sudo ip netns del wpgdhcp      # removes dh0 as well

Next steps

• Use --ramp-up 30s with the target --rate to raise the rate linearly and find where the answered share starts to fall. See Load and rate control.
• In the GUI, open this scenario from the Templates page, send it from a job, and count the OFFERs on the Receive page (/rx) with the filter udp src port 67 (Receive and verification).

Tutorial: Bringing up an IS-IS adjacency with Hellos

Time: about 30 minutes. Privileges: none until Step 2; root from Step 3 (network namespace and afpacket).

What you will build

An IS-IS Level 2 LAN Hello (IIH), sent to FRR’s isisd, and the peer’s view of the adjacency going from Initializing to Up. The template is the interop check templates/interop/isis-l2-lan-hello-up.wpg.yaml. It is an OSI stack without IP, with LLC (0xfe) and IS-IS directly on Ethernet, and it shows the PDU length, padding up to the MTU, and the two-way check through the IS Neighbors TLV.

wpg is stateless. Keep sending Hellos and the adjacency stays up, but wpg does not flood LSPs or act as the DIS.

Only use this against routers you own or are authorised to test. A fake adjacency in a production IS-IS domain can affect route computation.

Before you start

Build wpg and run from the repository root (Installing on Linux). From Step 3 you need Linux, iproute2, FRR (sudo apt install frr; the script starts the daemons itself, so the frr service can stay stopped) and root. The IS-IS PDUs and TLVs are listed in IS-IS (P2).

Step 1. Read the template

layers:
  - protocol: dot3
    fields:
      dst: "01:80:c2:00:00:15" # AllL2ISs
      src: ${src_mac}
      length: auto
  - protocol: llc
  - protocol: isis_l2_lan_hello
    fields:
      circuit_type: l2
      source_id: ${system_id}
      holding_time: 30
      priority: 0 # wpg does not flood LSPs, so let the peer be the DIS
      lan_id: "0000 0000 0001 01" # overwritten by the DIS's LAN ID once the peer elects itself
      # Manual PDU length: Padding TLVs fill the PDU up to it (MTU 1500 - LLC 3).
      pdu_length: 1497
      tlvs:
        - { protocols_supported: [ipv4] }
        - { area_addresses: [{ address: "${area}" }] }
        - { ip_interface_addresses: ["${ip}"] }
        - { is_neighbors: ["${peer_mac}"] }

tx:
  count: 40 # two minutes of Hellos
  rate: ifg=3s

Things worth knowing:

• IS-IS does not use IP. With llc on top of dot3 (802.3 with a length field), DSAP / SSAP become 0xfe (OSI) automatically, and the IS-IS NLPID 0x83 comes from the PDU layer. 01:80:c2:00:00:15 is the all-Level-2-ISs address (AllL2ISs).
• A Manual pdu_length adds padding. Left Auto, the PDU is as long as its TLVs. With a value, Padding TLVs (type 8) are added until the PDU is exactly that long. 1497 is the Ethernet MTU of 1500 minus the 3-octet LLC header. A Hello that arrives at that size tells the peer that the MTUs match.
• is_neighbors is the two-way check. A LAN adjacency only comes Up once a router sees its own MAC (SNPA) in the other side’s Hello. Set peer_mac to the MAC of the peer’s interface.
• priority: 0 makes wpg lose the DIS (designated IS) election, because it does not do the DIS’s work (CSNPs, pseudonode LSP).
• The System ID (source_id) is 6 octets; area addresses use NSAP notation (49.0001).

Step 2. Look at the frame

$ wpg render templates/interop/isis-l2-lan-hello-up.wpg.yaml -o /tmp/isis.pcapng --count 1
Wrote 1 packets to /tmp/isis.pcapng.
$ tshark -r /tmp/isis.pcapng
    1   0.000000 02:00:00:00:00:01 → ISIS-all-level-2-IS's ISIS HELLO 1514 L2 HELLO, System-ID: 0000.0000.0001
$ tshark -r /tmp/isis.pcapng -V
...
ISIS HELLO
    .... ..10 = Circuit type: Level 2 only (0x2)
    SystemID {Sender of PDU}: 0000.0000.0001
    Holding timer: 30
    PDU length: 1497
    .000 0000 = Priority: 0
    SystemID {Designated IS}: 0000.0000.0001.01
    Protocols Supported (t=129, l=1)
    Area address(es) (t=1, l=4)
        Area address (3): 49.0001
    IP Interface address(es) (t=132, l=4)
        IPv4 interface address: 10.99.0.1
    IS Neighbor(s) (t=6, l=6)
        IS Neighbor: 02:00:00:00:00:02 (02:00:00:00:00:02)
    Padding (t=8, l=255)
    Padding (t=8, l=255)
    Padding (t=8, l=255)
    Padding (t=8, l=255)
    Padding (t=8, l=255)
    Padding (t=8, l=160)

(The -V output is abridged.) The frame is 1514 octets (MTU 1500 plus the 14-octet Ethernet header). The 1497-octet PDU is the 27-octet header, 23 octets for the four TLVs above, and six Padding TLVs (five of 255 octets and one of 160, each plus 2 octets of type and length: 1447).

Step 3. Set up the FRR lab

scripts/interop/frr-netns.sh starts FRR in a namespace wpgfrr connected to wpg by a veth pair (wpg0 ⇔ frr0). FRR’s IS-IS is net 49.0001.0000.0000.0002.00, is-type level-2-only. With --keep the lab stays up after the interop checks.

$ cargo build --release -p wpg-cli
$ sudo scripts/interop/frr-netns.sh --keep target/release/wpg
...
PASS  IS-IS L2 adjacency Up
...
lab kept: ip netns exec wpgfrr vtysh -N wpg; tear down with scripts/interop/frr-netns.sh --down

The script’s own check has already brought the adjacency up once. Wait until it expires, one holding time (30 s) after the last Hello, before you go on:

$ sudo ip netns exec wpgfrr vtysh -N wpg -c "show isis neighbor"
Area 1:
  System Id           Interface   L  State        Holdtime SNPA

Note both MACs (veth MACs change every time the pair is created):

SRC=$(cat /sys/class/net/wpg0/address)
PEER=$(sudo ip netns exec wpgfrr cat /sys/class/net/frr0/address)

Step 4. Receive the peer’s Hello

FRR sends its own Hello every 3 seconds. Receive one with wpg capture to check that wpg’s parser reads it:

$ sudo wpg capture -i wpg0 -f "ether dst 01:80:c2:00:00:15" --count 1 --show 1
Capturing on wpg0 via afpacket, filter ether dst 01:80:c2:00:00:15 (Ctrl-C stops)
#   0  16:10:42.763122508   1514 B  dot3 / llc / isis_l2_lan_hello
state      finished (count reached)
...

FRR’s Hello is also padded to 1514 octets and parses as dot3 / llc / isis_l2_lan_hello. Save it with -w /tmp/frr.pcapng to turn it into a template (pcap to template replay).

Step 5. Bring the adjacency up

First send one Hello without the peer’s MAC. peer_mac keeps its default 02:00:00:00:00:02, so to FRR this is a neighbor that does not know it yet:

$ sudo wpg send templates/interop/isis-l2-lan-hello-up.wpg.yaml -i wpg0 --backend afpacket \
      --var src_mac=$SRC --count 1
$ sudo ip netns exec wpgfrr vtysh -N wpg -c "show isis neighbor"
Area 1:
  System Id           Interface   L  State        Holdtime SNPA
 0000.0000.0001      frr0        2  Initializing  29       a63f.1a8d.7239

FRR has found wpg, but without the two-way check the adjacency stays Initializing. Now send with FRR’s MAC in peer_mac:

$ sudo wpg send templates/interop/isis-l2-lan-hello-up.wpg.yaml -i wpg0 --backend afpacket \
      --var src_mac=$SRC --var peer_mac=$PEER --count 2 --rate 1pps
$ sudo ip netns exec wpgfrr vtysh -N wpg -c "show isis neighbor"
Area 1:
  System Id           Interface   L  State        Holdtime SNPA
 0000.0000.0001      frr0        2  Up            30       a63f.1a8d.7239
$ sudo ip netns exec wpgfrr vtysh -N wpg -c "show isis neighbor detail"
Area 1:
 0000.0000.0001
    Interface: frr0, Level: 2, State: Up, Expires in 30s
    Adjacency flaps: 1, Last: 1s ago
    Circuit type: L2, Speaks: IPv4
    SNPA: a63f.1a8d.7239, LAN id: 0000.0000.0001.01
    LAN Priority: 0, unknown DIS state, DIS flaps: 0, Last: 2s ago
    Area Address(es):
      49.0001
    IPv4 Address(es):
      10.99.0.1

FRR sees the template’s TLVs as written: the area, the IPv4 address, priority 0 and the 30-second holding time. To keep the adjacency, send Hellos more often than the holding time. The template’s default (without --count) is 40 Hellos 3 seconds apart, two minutes in all. Stop sending and the adjacency is gone 30 seconds later.

Step 6. Variations

• A different area: sending with --var area=49.0002 --var "system_id=0000 0000 0003" still brings the adjacency Up. Only Level 1 adjacencies need a matching area address; Level 2 adjacencies cross areas (ISO 10589). To try Level 1, change isis_l2_lan_hello to isis_l1_lan_hello and the destination to 01:80:c2:00:00:14 (AllL1ISs) in the template, and set FRR to is-type level-1.
• MTU mismatch: put pdu_length back to Auto (delete the line) and the Hello is short and unpadded. FRR does not require padded Hellos from its neighbors by default, so the adjacency still comes up, but implementations that insist on padding will not form it. Use this to compare devices.
• Authentication: templates/protocols/routing/isis-l2-lan-hello.wpg.yaml carries clear-text authentication (TLV 10). wpg does not compute HMAC-MD5 values; enter them by hand.
• Other PDUs: samples of LSPs, CSNPs, PSNPs and point-to-point Hellos are in templates/protocols/routing/isis-*.wpg.yaml. The LSP checksum (Fletcher) is Auto.

Clean up:

sudo scripts/interop/frr-netns.sh --down

Next steps

• The procedure and configuration examples for real routers (IOS-XR, Junos) and routers on CML2 are in Interop checks.
• The IPv6 counterpart of the same ideas (several layers whose type, length and checksum fields are derived from each other) is IPv6 and Neighbor Discovery.

Protocol reference

This chapter is generated from the protocol definition IR of wpg-protocols (the catalog served at GET /api/protocols), so it always matches the code: 183 protocols. Each page lists the fields in wire order with their type, default, Auto rule and description, the lower layers that lead to the protocol, the next-layer table, the constraints checked after building and the bundled sample templates. The hand-written protocol notes explain how the protocols are reached, which fields you set by hand and the approximations that remain. After changing a definition, regenerate with just docs-gen.

L2 (data link)

L3 (network)

L4 (transport)

Application and control

Payload

Ethernet II (ethernet2)

• Layer: L2 (data link)
• Header: 14 octets (fixed)
• Minimum frame: 60 octets
• Notes: Encapsulation and tunnels, L2 control protocols, SRv6 SRH / SR-MPLS (P2), User-defined protocols (protocols.d)

Reached from

Fields

ethertype

Next layer

The next layer is selected by ethertype; when the field is Auto the builder writes the value of the protocol stacked above.

First 8 bits of the payload when ethertype = 34825 (0x8809)

Sample templates

• interop-bfd-session-up — templates/interop/bfd-session-up.wpg.yaml
• interop-ldp-link-hello — templates/interop/ldp-link-hello.wpg.yaml
• interop-ospfv2-hello-2way — templates/interop/ospfv2-hello-2way.wpg.yaml
• interop-pim-hello-neighbor — templates/interop/pim-hello-neighbor.wpg.yaml
• interop-ripv2-response-route — templates/interop/ripv2-response-route.wpg.yaml
• interop-vrrpv3-preempt — templates/interop/vrrpv3-preempt.wpg.yaml
• arp-bad-address-lengths — templates/malformed/arp-bad-lengths.wpg.yaml
• bad-fcs — templates/malformed/bad-fcs.wpg.yaml
• bad-ipv4-checksum — templates/malformed/ipv4-bad-checksum.wpg.yaml
• bad-ipv4-ihl — templates/malformed/ipv4-bad-ihl.wpg.yaml
• bad-ipv4-total-length — templates/malformed/ipv4-total-length-too-long.wpg.yaml
• bad-ipv4-total-length-short — templates/malformed/ipv4-total-length-too-short.wpg.yaml
• truncated-ipv4-udp — templates/malformed/ipv4-truncated.wpg.yaml
• bad-ipv6-payload-length — templates/malformed/ipv6-bad-payload-length.wpg.yaml
• bad-tcp-checksum — templates/malformed/tcp-bad-checksum.wpg.yaml
• bad-udp-checksum — templates/malformed/udp-bad-checksum.wpg.yaml
• bad-udp-length — templates/malformed/udp-bad-length.wpg.yaml
• frame-with-fcs — templates/protocols/frame/fcs-auto.wpg.yaml
• jumbo-frame-9000 — templates/protocols/frame/jumbo-9000.wpg.yaml
• min-frame-padded — templates/protocols/frame/min-frame-60.wpg.yaml
• runt-frame-unpadded — templates/protocols/frame/no-padding-runt.wpg.yaml
• arp-gratuitous — templates/protocols/l2/arp-gratuitous.wpg.yaml
• arp-reply — templates/protocols/l2/arp-reply.wpg.yaml
• arp-request — templates/protocols/l2/arp-request.wpg.yaml
• dot1ad-qinq-frame — templates/protocols/l2/dot1ad.wpg.yaml
• dot1q-frame — templates/protocols/l2/dot1q.wpg.yaml
• eth-ii-frame — templates/protocols/l2/ethernet2.wpg.yaml
• macsec — templates/protocols/l2/macsec.wpg.yaml
• icmpv4-echo-request — templates/protocols/l3/icmpv4-echo.wpg.yaml
• icmpv6-echo-request — templates/protocols/l3/icmpv6-echo.wpg.yaml
• ipv4-dscp-ecn-matrix — templates/protocols/l3/ipv4-dscp-ecn-matrix.wpg.yaml
• ipv4-fragments — templates/protocols/l3/ipv4-fragment.wpg.yaml
• ipv4-router-alert — templates/protocols/l3/ipv4-router-alert.wpg.yaml
• ipv4-udp — templates/protocols/l3/ipv4.wpg.yaml
• ipv6-dstopts — templates/protocols/l3/ipv6-dstopts.wpg.yaml
• ipv6-ext-chain — templates/protocols/l3/ipv6-ext-chain.wpg.yaml
• ipv6-fragment — templates/protocols/l3/ipv6-frag.wpg.yaml
• ipv6-hopopts-router-alert — templates/protocols/l3/ipv6-hopopts.wpg.yaml
• ipv6-routing-type2 — templates/protocols/l3/ipv6-routing.wpg.yaml
• ipv6-udp — templates/protocols/l3/ipv6.wpg.yaml
• ndp-neighbor-advertisement — templates/protocols/l3/ndp-na.wpg.yaml
• ndp-neighbor-solicitation — templates/protocols/l3/ndp-ns.wpg.yaml
• ndp-router-advertisement — templates/protocols/l3/ndp-ra.wpg.yaml
• ndp-redirect — templates/protocols/l3/ndp-redirect.wpg.yaml
• ndp-router-solicitation — templates/protocols/l3/ndp-rs.wpg.yaml
• sctp-abort — templates/protocols/l4/sctp-abort.wpg.yaml
• sctp-data — templates/protocols/l4/sctp-data.wpg.yaml
• sctp-heartbeat — templates/protocols/l4/sctp-heartbeat.wpg.yaml
• sctp-init-ack — templates/protocols/l4/sctp-init-ack.wpg.yaml
• sctp-init — templates/protocols/l4/sctp-init.wpg.yaml
• sctp-over-udp — templates/protocols/l4/sctp-over-udp.wpg.yaml
• sctp-sack — templates/protocols/l4/sctp-sack.wpg.yaml
• sctp-shutdown — templates/protocols/l4/sctp-shutdown.wpg.yaml
• tcp-data-psh-ack — templates/protocols/l4/tcp-data.wpg.yaml
• tcp-syn-options — templates/protocols/l4/tcp-syn.wpg.yaml
• udp-over-ipv6 — templates/protocols/l4/udp-ipv6.wpg.yaml
• udp-datagram — templates/protocols/l4/udp.wpg.yaml
• diameter-ccr-initial — templates/protocols/mobile/diameter-ccr-initial.wpg.yaml
• diameter-cer — templates/protocols/mobile/diameter-cer.wpg.yaml
• gtpv2-create-session-request — templates/protocols/mobile/gtpv2-create-session-request.wpg.yaml
• gtpv2-create-session-response — templates/protocols/mobile/gtpv2-create-session-response.wpg.yaml
• gtpv2-echo-request — templates/protocols/mobile/gtpv2-echo-request.wpg.yaml
• ldp-hello — templates/protocols/mpls/ldp-hello.wpg.yaml
• ldp-initialization — templates/protocols/mpls/ldp-initialization.wpg.yaml
• ldp-label-mapping — templates/protocols/mpls/ldp-label-mapping.wpg.yaml
• ldp-label-withdraw — templates/protocols/mpls/ldp-label-withdraw.wpg.yaml
• ldp-targeted-hello — templates/protocols/mpls/ldp-targeted-hello.wpg.yaml
• rsvp-hello — templates/protocols/mpls/rsvp-hello.wpg.yaml
• rsvp-path-err — templates/protocols/mpls/rsvp-path-err.wpg.yaml
• rsvp-path-tear — templates/protocols/mpls/rsvp-path-tear.wpg.yaml
• rsvp-te-path — templates/protocols/mpls/rsvp-te-path.wpg.yaml
• rsvp-te-resv — templates/protocols/mpls/rsvp-te-resv.wpg.yaml
• sr-mpls-entropy — templates/protocols/mpls/sr-mpls-entropy.wpg.yaml
• bfd-auth — templates/protocols/oam/bfd-auth.wpg.yaml
• bfd-multihop-ipv6 — templates/protocols/oam/bfd-multihop-ipv6.wpg.yaml
• bfd-single-hop — templates/protocols/oam/bfd-single-hop.wpg.yaml
• cfm-ccm — templates/protocols/oam/cfm-ccm.wpg.yaml
• cfm-generic — templates/protocols/oam/cfm-generic.wpg.yaml
• cfm-lbm — templates/protocols/oam/cfm-lbm.wpg.yaml
• cfm-lbr — templates/protocols/oam/cfm-lbr.wpg.yaml
• cfm-ltm — templates/protocols/oam/cfm-ltm.wpg.yaml
• cfm-ltr — templates/protocols/oam/cfm-ltr.wpg.yaml
• efm-oam-event — templates/protocols/oam/efm-oam-event.wpg.yaml
• efm-oam-generic — templates/protocols/oam/efm-oam-generic.wpg.yaml
• efm-oam-information — templates/protocols/oam/efm-oam-information.wpg.yaml
• efm-oam-loopback — templates/protocols/oam/efm-oam-loopback.wpg.yaml
• efm-oam-organization-specific — templates/protocols/oam/efm-oam-organization-specific.wpg.yaml
• efm-oam-variable-request — templates/protocols/oam/efm-oam-variable-request.wpg.yaml
• efm-oam-variable-response — templates/protocols/oam/efm-oam-variable-response.wpg.yaml
• erps-raps-nr-rb — templates/protocols/oam/erps-raps-nr-rb.wpg.yaml
• erps-raps-sf — templates/protocols/oam/erps-raps-sf.wpg.yaml
• micro-bfd — templates/protocols/oam/micro-bfd.wpg.yaml
• y1731-1dm — templates/protocols/oam/y1731-1dm.wpg.yaml
• y1731-1sl — templates/protocols/oam/y1731-1sl.wpg.yaml
• y1731-ais — templates/protocols/oam/y1731-ais.wpg.yaml
• y1731-csf — templates/protocols/oam/y1731-csf.wpg.yaml
• y1731-dmm — templates/protocols/oam/y1731-dmm.wpg.yaml
• y1731-dmr — templates/protocols/oam/y1731-dmr.wpg.yaml
• y1731-lck — templates/protocols/oam/y1731-lck.wpg.yaml
• y1731-lmm — templates/protocols/oam/y1731-lmm.wpg.yaml
• y1731-lmr — templates/protocols/oam/y1731-lmr.wpg.yaml
• y1731-slm — templates/protocols/oam/y1731-slm.wpg.yaml
• y1731-slr — templates/protocols/oam/y1731-slr.wpg.yaml
• y1731-tst — templates/protocols/oam/y1731-tst.wpg.yaml
• srv6-end-dx2-hmac — templates/protocols/srv6/srv6-end-dx2-hmac.wpg.yaml
• srv6-h-encaps-ipv4 — templates/protocols/srv6/srv6-h-encaps-ipv4.wpg.yaml
• srv6-srh-udp — templates/protocols/srv6/srv6-srh-udp.wpg.yaml
• esmc-event-dnu — templates/protocols/timing/esmc-event-dnu.wpg.yaml
• esmc-ql-prc — templates/protocols/timing/esmc-ql-prc.wpg.yaml
• ptp-announce-udp — templates/protocols/timing/ptp-announce-udp.wpg.yaml
• ptp-delay-req-udp — templates/protocols/timing/ptp-delay-req-udp.wpg.yaml
• ptp-delay-resp-udp — templates/protocols/timing/ptp-delay-resp-udp.wpg.yaml
• ptp-follow-up-l2 — templates/protocols/timing/ptp-follow-up-l2.wpg.yaml
• ptp-generic — templates/protocols/timing/ptp-generic.wpg.yaml
• ptp-management-get — templates/protocols/timing/ptp-management-get.wpg.yaml
• ptp-pdelay-req-l2 — templates/protocols/timing/ptp-pdelay-req-l2.wpg.yaml
• ptp-pdelay-resp-follow-up-l2 — templates/protocols/timing/ptp-pdelay-resp-follow-up-l2.wpg.yaml
• ptp-pdelay-resp-l2 — templates/protocols/timing/ptp-pdelay-resp-l2.wpg.yaml
• ptp-signaling-unicast — templates/protocols/timing/ptp-signaling-unicast.wpg.yaml
• ptp-sync-two-step-l2 — templates/protocols/timing/ptp-sync-two-step-l2.wpg.yaml
• rtcp-feedback-app — templates/protocols/voip/rtcp-feedback-app.wpg.yaml
• rtcp-rr-bye — templates/protocols/voip/rtcp-rr-bye.wpg.yaml
• rtcp-sr-sdes — templates/protocols/voip/rtcp-sr-sdes.wpg.yaml
• rtp-pcmu — templates/protocols/voip/rtp-pcmu.wpg.yaml
• sip-invite — templates/protocols/voip/sip-invite.wpg.yaml
• sip-register — templates/protocols/voip/sip-register.wpg.yaml
• scenario-arp-sweep-slash22 — templates/scenarios/arp-sweep-slash22.wpg.yaml
• scenario-dhcp-discover-flood — templates/scenarios/dhcp-discover-flood.wpg.yaml
• scenario-frame-size-sweep — templates/scenarios/frame-size-sweep.wpg.yaml
• scenario-jumbo-udp-mtu-probe — templates/scenarios/jumbo-udp-mtu-probe.wpg.yaml
• scenario-mac-flood — templates/scenarios/mac-flood.wpg.yaml
• scenario-ndp-ns-sweep — templates/scenarios/ndp-ns-sweep.wpg.yaml
• scenario-ping-sweep-pattern — templates/scenarios/ping-sweep-pattern.wpg.yaml
• scenario-qinq-service-sweep — templates/scenarios/qinq-service-sweep.wpg.yaml
• scenario-ipv6-ra-flood — templates/scenarios/ra-flood.wpg.yaml
• sr-mpls-prefix-sid-sweep — templates/scenarios/sr-mpls-prefix-sid-sweep.wpg.yaml
• scenario-tcp-syn-port-scan — templates/scenarios/tcp-syn-port-scan.wpg.yaml
• scenario-ttl-sweep — templates/scenarios/ttl-sweep.wpg.yaml
• scenario-udp-qos-matrix — templates/scenarios/udp-qos-matrix.wpg.yaml
• scenario-vlan-arp-sweep — templates/scenarios/vlan-arp-sweep.wpg.yaml
• scenario-vlan-id-sweep — templates/scenarios/vlan-id-sweep.wpg.yaml
• scenario-vlan-syn-flood — templates/scenarios/vlan-syn-flood.wpg.yaml

802.1Q VLAN (dot1q)

• Layer: L2 (data link)
• Header: 4 octets (fixed)
• Notes: User-defined protocols (protocols.d)

Reached from

Fields

ethertype

Next layer

The next layer is selected by ethertype; when the field is Auto the builder writes the value of the protocol stacked above.

Constraints

Sample templates

• dot1ad-qinq-frame — templates/protocols/l2/dot1ad.wpg.yaml
• dot1q-frame — templates/protocols/l2/dot1q.wpg.yaml
• cfm-ccm — templates/protocols/oam/cfm-ccm.wpg.yaml
• erps-raps-nr-rb — templates/protocols/oam/erps-raps-nr-rb.wpg.yaml
• erps-raps-sf — templates/protocols/oam/erps-raps-sf.wpg.yaml
• scenario-qinq-service-sweep — templates/scenarios/qinq-service-sweep.wpg.yaml
• scenario-vlan-arp-sweep — templates/scenarios/vlan-arp-sweep.wpg.yaml
• scenario-vlan-id-sweep — templates/scenarios/vlan-id-sweep.wpg.yaml
• scenario-vlan-syn-flood — templates/scenarios/vlan-syn-flood.wpg.yaml

802.1ad S-VLAN (dot1ad)

• Layer: L2 (data link)
• Header: 4 octets (fixed)

Reached from

Fields

ethertype

Next layer

The next layer is selected by ethertype; when the field is Auto the builder writes the value of the protocol stacked above.

Constraints

Sample templates

• dot1ad-qinq-frame — templates/protocols/l2/dot1ad.wpg.yaml
• scenario-qinq-service-sweep — templates/scenarios/qinq-service-sweep.wpg.yaml

IEEE 802.3 (dot3)

• Layer: L2 (data link)
• Header: 14 octets (fixed)
• Minimum frame: 60 octets
• Notes: L2 control protocols

Reached from

Fields

Next layer

The next layer is selected by length; when the field is Auto the builder writes the value of the protocol stacked above.

Constraints

Sample templates

• interop-isis-l2-lan-hello-up — templates/interop/isis-l2-lan-hello-up.wpg.yaml
• dot3-llc-osi — templates/protocols/l2/dot3-llc-osi.wpg.yaml
• dot3-llc-snap-frame — templates/protocols/l2/dot3-llc-snap.wpg.yaml
• dot3-llc-frame — templates/protocols/l2/dot3-llc.wpg.yaml
• clnp-dt — templates/protocols/l3/clnp-dt.wpg.yaml
• clnp-er — templates/protocols/l3/clnp-er.wpg.yaml
• clnp-erq — templates/protocols/l3/clnp-erq.wpg.yaml
• esis-esh — templates/protocols/routing/esis-esh.wpg.yaml
• esis-generic — templates/protocols/routing/esis-generic.wpg.yaml
• esis-ish — templates/protocols/routing/esis-ish.wpg.yaml
• esis-rd — templates/protocols/routing/esis-rd.wpg.yaml
• isis-generic — templates/protocols/routing/isis-generic.wpg.yaml
• isis-l1-csnp — templates/protocols/routing/isis-l1-csnp.wpg.yaml
• isis-l1-lan-hello — templates/protocols/routing/isis-l1-lan-hello.wpg.yaml
• isis-l1-lsp — templates/protocols/routing/isis-l1-lsp.wpg.yaml
• isis-l1-psnp — templates/protocols/routing/isis-l1-psnp.wpg.yaml
• isis-l2-csnp — templates/protocols/routing/isis-l2-csnp.wpg.yaml
• isis-l2-lan-hello — templates/protocols/routing/isis-l2-lan-hello.wpg.yaml
• isis-l2-lsp — templates/protocols/routing/isis-l2-lsp.wpg.yaml
• isis-l2-psnp — templates/protocols/routing/isis-l2-psnp.wpg.yaml
• isis-p2p-hello — templates/protocols/routing/isis-p2p-hello.wpg.yaml

IEEE 802.2 LLC (llc)

• Layer: L2 (data link)
• Header: 3 octets (fixed)
• Notes: L2 control protocols, OSI encapsulation (P2)

Reached from

Fields

dsap

ssap

control

Next layer

The next layer is selected by dsap; when the field is Auto the builder writes the value of the protocol stacked above.

First 8 bits of the payload when dsap = 254 (0xfe)

Sample templates

• interop-isis-l2-lan-hello-up — templates/interop/isis-l2-lan-hello-up.wpg.yaml
• dot3-llc-osi — templates/protocols/l2/dot3-llc-osi.wpg.yaml
• dot3-llc-snap-frame — templates/protocols/l2/dot3-llc-snap.wpg.yaml
• dot3-llc-frame — templates/protocols/l2/dot3-llc.wpg.yaml
• clnp-dt — templates/protocols/l3/clnp-dt.wpg.yaml
• clnp-er — templates/protocols/l3/clnp-er.wpg.yaml
• clnp-erq — templates/protocols/l3/clnp-erq.wpg.yaml
• esis-esh — templates/protocols/routing/esis-esh.wpg.yaml
• esis-generic — templates/protocols/routing/esis-generic.wpg.yaml
• esis-ish — templates/protocols/routing/esis-ish.wpg.yaml
• esis-rd — templates/protocols/routing/esis-rd.wpg.yaml
• isis-generic — templates/protocols/routing/isis-generic.wpg.yaml
• isis-l1-csnp — templates/protocols/routing/isis-l1-csnp.wpg.yaml
• isis-l1-lan-hello — templates/protocols/routing/isis-l1-lan-hello.wpg.yaml
• isis-l1-lsp — templates/protocols/routing/isis-l1-lsp.wpg.yaml
• isis-l1-psnp — templates/protocols/routing/isis-l1-psnp.wpg.yaml
• isis-l2-csnp — templates/protocols/routing/isis-l2-csnp.wpg.yaml
• isis-l2-lan-hello — templates/protocols/routing/isis-l2-lan-hello.wpg.yaml
• isis-l2-lsp — templates/protocols/routing/isis-l2-lsp.wpg.yaml
• isis-l2-psnp — templates/protocols/routing/isis-l2-psnp.wpg.yaml
• isis-p2p-hello — templates/protocols/routing/isis-p2p-hello.wpg.yaml

SNAP (snap)

• Layer: L2 (data link)
• Header: 5 octets (fixed)
• Notes: L2 control protocols

Reached from

Fields

pid

Next layer

The next layer is selected by pid; when the field is Auto the builder writes the value of the protocol stacked above.

Sample templates

• dot3-llc-snap-frame — templates/protocols/l2/dot3-llc-snap.wpg.yaml

ARP (arp)

• Layer: L2 (data link)
• Header: 28 octets (fixed)

Reached from

Fields

htype

ptype

oper

Constraints

Sample templates

• arp-bad-address-lengths — templates/malformed/arp-bad-lengths.wpg.yaml
• min-frame-padded — templates/protocols/frame/min-frame-60.wpg.yaml
• runt-frame-unpadded — templates/protocols/frame/no-padding-runt.wpg.yaml
• arp-gratuitous — templates/protocols/l2/arp-gratuitous.wpg.yaml
• arp-reply — templates/protocols/l2/arp-reply.wpg.yaml
• arp-request — templates/protocols/l2/arp-request.wpg.yaml
• srv6-end-dx2-hmac — templates/protocols/srv6/srv6-end-dx2-hmac.wpg.yaml
• scenario-arp-sweep-slash22 — templates/scenarios/arp-sweep-slash22.wpg.yaml
• scenario-vlan-arp-sweep — templates/scenarios/vlan-arp-sweep.wpg.yaml

LLDP (lldp)

• Layer: L2 (data link)
• Header: variable length
• Notes: L2 control protocols

Reached from

Fields

tlvs

Each item is a group of the fields below.

Sample templates

• lldp — templates/protocols/l2/lldp.wpg.yaml

CDP (cdp)

• Layer: L2 (data link)
• Header: variable length
• Notes: L2 control protocols

Reached from

Fields

tlvs

• Type 16 bits, length 16 bits.
• The length counts the type and length fields too.
• Unknown types are kept as raw value octets.

Sample templates

• cdp — templates/protocols/l2/cdp.wpg.yaml

STP BPDU (stp)

• Layer: L2 (data link)
• Header: variable length
• Notes: L2 control protocols

Reached from

Fields

protocol_version

bpdu_type

flags

Constraints

Sample templates

• stp — templates/protocols/l2/stp.wpg.yaml

LACP (lacp)

• Layer: L2 (data link)
• Header: 110 octets (fixed)
• Notes: L2 control protocols, PTP / ESMC / CFM / R-APS / 802.3ah OAM (P2)

Reached from

Fields

actor_state

partner_state

Sample templates

• lacp — templates/protocols/l2/lacp.wpg.yaml

Marker Protocol (marker)

• Layer: L2 (data link)
• Header: 110 octets (fixed)
• Notes: L2 control protocols, PTP / ESMC / CFM / R-APS / 802.3ah OAM (P2)

Reached from

Fields

Sample templates

• marker — templates/protocols/l2/marker.wpg.yaml

EAPOL (eapol)

• Layer: L2 (data link)
• Header: variable length
• Notes: L2 control protocols

Reached from

Fields

type

Sample templates

• eapol — templates/protocols/l2/eapol.wpg.yaml

PPPoE Discovery (pppoe_discovery)

• Layer: L2 (data link)
• Header: variable length
• Notes: L2 control protocols

Reached from

Fields

code

tags

• Type 16 bits, length 16 bits.
• The length counts the value only.
• Unknown types are kept as raw value octets.

Sample templates

• pppoe-discovery — templates/protocols/l2/pppoe-discovery.wpg.yaml

PPPoE Session (pppoe_session)

• Layer: L2 (data link)
• Header: 6 octets (fixed)
• Notes: L2 control protocols

Reached from

Fields

Next layer

The next layer is selected by session_id; when the field is Auto the builder writes the value of the protocol stacked above.

Sample templates

• pppoe-ppp-ipcp — templates/protocols/l2/pppoe-ppp-ipcp.wpg.yaml
• pppoe-ppp-lcp — templates/protocols/l2/pppoe-ppp-lcp.wpg.yaml

PPP (ppp)

• Layer: L2 (data link)
• Header: 2 octets (fixed)
• Notes: L2 control protocols, OSI encapsulation (P2)

Reached from

Fields

protocol

Next layer

The next layer is selected by protocol; when the field is Auto the builder writes the value of the protocol stacked above.

First 8 bits of the payload when protocol = 35 (0x0023)

Sample templates

• pppoe-ppp-ipcp — templates/protocols/l2/pppoe-ppp-ipcp.wpg.yaml
• pppoe-ppp-lcp — templates/protocols/l2/pppoe-ppp-lcp.wpg.yaml

PPP LCP (ppp_lcp)

• Layer: L2 (data link)
• Header: variable length
• Notes: L2 control protocols

Reached from

Fields

code

options

• Type 8 bits, length 8 bits.
• The length counts the type and length fields too.
• Unknown types are kept as raw value octets.