Packet Constructor
The Packet Constructor plugin generates frames from a template that you build from a header stack, from Ethernet to VXLAN. For each field, you define how it changes from frame to frame: a fixed value, increment, decrement, list, random value, or addresses from the task's sources and targets. One entry can hold several streams with different templates and rates. Before the run, you can view the frames in the preview and export them to pcap: the preview is built by the same code as the generator, so the preview frames match the transmitted frames byte for byte.
The plugin has two sides: the Client builds and sends frames, and the Server receives them and counts reception, loss, duplicates, order, and delay for each stream and, if needed, for each combination of field values.
Use the plugin to test how non-standard and specially crafted frames are handled: QinQ and MPLS label stacks, tunnel encapsulation, address and port sweeps, frames with an intentionally invalid checksum, and frame size mixes. With the server side, it shows which streams the DUT lost, duplicated, or reordered and how much delay it added.
The plugin belongs to the Network Testing module (see Pricing) and is configured in the Data Plane: select Packet Constructor in the plugin catalog and choose the Client or Server side. The client has the Sources, Targets, Packet template, and Duration sections; the server has only Sources and Duration.
Client and Server
| Side | What it does | What you configure |
|---|---|---|
| Client | Builds frames from the template and sends them from every port in Sources | Sources, targets, packet template, streams, rate, duration |
| Server | Receives frames on the ports in its Sources and keeps per-stream statistics: reception, loss, duplicates, order, delay | Sources (receive ports) and duration. The server has no template |
If the task has at least one Packet Constructor server entry, the client writes a signature into the last 16 bytes of every frame before the FCS: the task tag, stream number, source port number, frame number, and transmit time. The server uses the signature to assign a frame to its stream and to count loss, duplicates, order, and delay. The frame size does not change: the signature takes the end of the payload. Therefore the smallest frame of every enabled stream must fit the headers, the 16-byte signature, and the 4-byte FCS; otherwise the task is not saved and shows the error "для сигнатуры кадр должен быть не меньше N байт" (the frame must be at least N bytes for the signature). A 64-byte frame with Ethernet II, IPv4, and UDP (42 bytes of headers) fits the signature.
Without a server, no signature is written: frames go out exactly as the template defines, and only transmission is counted. The client form shows which mode applies: Signature enabled or Only transmission is counted.
- The server needs at least one Packet Constructor client entry in the same task. The server counts the streams of all client entries of the task.
- The client and the server can run on different agents. Delay is measured only when the client and the server run on the same agent (see Delay and Probes).
- The client and the server can use the same port: the DUT returns the frames to the port they left from, for example by routing them into another VLAN of that port. This is how the DUT delay is measured on a single tester port.
- The server only receives frames and does not respond to them.
Running a Test
- Create a separate task and add a client Packet Constructor entry to it. Other plugins cannot be added to this task; Packet Constructor client and server entries can.
- Under the client's Sources, select the agents, interfaces, and networks that will send frames. Frames are sent from every selected port; fields that take values from sources get the addresses of that port's networks on each port.
- Under Targets, select destination networks if template fields must take addresses, MACs, or ports from the targets. If all fields are set manually, targets are not required.
- In the Packet template section, build the header stack and configure the fields, frame size, and payload on the Packet tab, and the rate and frame count on the Transmit tab. Check the frames on the Frames tab. To send frames from other templates from the same ports, add streams (see Streams).
- To count reception, loss, order, and delay, add a server Packet Constructor entry and select, under its Sources, the ports to which the DUT returns the frames.
- Set the Duration and start the task. The reception results are shown on the Packet Constructor dashboard on the Metrics tab (see Flow Statistics).
The template is validated when the task is saved and when it starts. Errors are shown with the "Конструктор пакетов:" (Packet Constructor) prefix and the path to the template field; errors of a particular stream have the "Конструктор пакетов: поток «name»:" (Packet Constructor: stream "name") prefix.
Packet Template
The Packet template section contains the Packet, Groups, Transmit, Frames, and Streams tabs. Above the tabs is the Stream selector: the Packet, Groups, Transmit, and Frames tabs show the selected stream, and the Streams tab shows all streams of the entry.
Section buttons:
| Button | What it does |
|---|---|
| Ready-made templates | Replaces the selected stream's template with a typical one: UDP over IPv4 (64 bytes or IMIX), UDP with 4096 address and port combinations, TCP SYN, ICMP Echo Request, VLAN 802.1Q, QinQ 802.1ad, two MPLS labels, UDP over IPv6, VXLAN, GRE (IPv4 in IPv4), ARP request. The previous template can be restored with the Restore previous button |
| Library | Opens saved templates (see Template Library) |
| To library | Saves the selected stream's template to the library |
| Download pcap | Exports the first 1000 frames of the selected stream for viewing in Wireshark |
The button in the upper right corner expands the constructor to the full page width and brings the settings list back.
Packet
The Packet tab is a three-column packet editor, like the Packet Editor of Keysight IxNetwork:
- Packet editor: the header stack of the selected stream as chips, from Ethernet II to Payload. The selected header is highlighted. The + button to the right of a header adds a header after it; the × button removes the header.
- Fields of the selected header: the field name and its value in the frame, for example
<Auto> 0x0800,Inc: 49152, 1, 100, or<From source> 192.168.1.10. The Filter… box keeps the fields whose names contain the entered text. The IPv4 priority and flag fields, the TCP flags, and the VLAN tag are grouped into the collapsible Priority, Flags, and VLAN tag sections. An icon next to the name marks a field the stream is tracked by. - Field editor: the values of the selected field: the Auto checkbox, the Pattern and its parameters, the Group, and the Tracking checkbox (see below).
The Hex view under the editor shows the bytes of the first frame, colored by header. You can also select a field by clicking its byte; the Hex view button collapses the dump.
The + button opens the protocol list: the Filter… box at the top, then Pinned protocols (Ethernet II, MPLS, VLAN, IPv4, IPv6, GRE, VXLAN, TCP, UDP), then Other protocols. A protocol that cannot stand in this position is grayed out, and its tooltip gives the reason: for example, after VLAN you can add another VLAN (QinQ), after MPLS another label or IP, and after UDP a VXLAN header. You can type a protocol name or its standard in the filter box and press Enter to add the first match. A header that its neighbors need in order to follow each other cannot be removed.
| Header | Standard | Length, bytes | What can follow |
|---|---|---|---|
| Ethernet II | IEEE 802.3 | 14 | ARP, Ethernet II, IPv4, IPv6, MPLS, VLAN |
| VLAN | IEEE 802.1Q | 4 | ARP, Ethernet II, IPv4, IPv6, MPLS, VLAN |
| MPLS | RFC 3032 | 4 | Ethernet II, IPv4, IPv6, MPLS |
| ARP | RFC 826 | 28 | — |
| IPv4 | RFC 791 | 20 | GRE, ICMP, ICMPv6, IPv4, IPv6, TCP, UDP |
| IPv6 | RFC 8200 | 40 | GRE, ICMP, ICMPv6, IPv4, IPv6, TCP, UDP |
| GRE | RFC 2784 | 4 | ARP, Ethernet II, IPv4, IPv6, MPLS, VLAN |
| ICMP | RFC 792 | 8 | — |
| ICMPv6 | RFC 4443 | 8 | — |
| TCP | RFC 9293 | 20 | — |
| UDP | RFC 768 | 8 | VXLAN |
| VXLAN | RFC 7348 | 8 | Ethernet II |
The stack can contain up to 32 headers. IPv4 and TCP options and IPv6 extension headers are not supported; the IPv4 header length (IHL) and TCP Data Offset fields are read-only. If the outer QinQ tag keeps the TPID 0x8100, the constructor offers to replace it with 0x88a8 per IEEE 802.1ad with the Make it 0x88a8 button: a switch port in trunk mode drops frames tagged 0x8100 from VLANs it does not carry.
To configure a field, select it in the fields column. Values are entered in the field's format: a decimal or hexadecimal (0x) number, a MAC address, or an IPv4 or IPv6 address.
| Pattern | Value in the frame |
|---|---|
| Single value | One fixed value in all frames |
| Increment | Start, Step, and Count of values; after the last value, counting starts over |
| Decrement | Same as increment, but the value decreases |
| List | Values in rotation; entered one per line or separated by commas, up to 65,536 values. The Import CSV button fills the list from a CSV or text file |
| Repeatable random | Random bits under a mask (optional); the remaining bits are taken from the fixed bits. For example, the mask 0.0.0.255 randomizes the last octet of an IPv4 address |
| Random from range | A uniformly random value from the series "from", "from + step", …, no greater than "to" |
| From source | MACs, IP addresses, or ports of the source port's network |
| From target | Next-hop MAC, IP addresses, or ports of the target networks |
Auto fields have the Auto checkbox: while it is selected, the value is calculated automatically and the pattern is unavailable. Clearing the checkbox gives the field the value it had in the frame, with the Single value pattern.
For random patterns, you can set a seed: with the same seed, the sequence repeats on every run.
The Tracking checkbox turns on flow statistics by this field: the server counts each combination of the values of the checked fields separately (see Tracking). The checkbox is available with the Increment, Decrement, List, From source, and From target patterns.
Auto fields are filled in automatically until you set them manually:
- the next-protocol field (EtherType, IP protocol, Next Header, GRE protocol type, UDP destination port), based on the next header in the stack;
- the MPLS Bottom of Stack bit: 1 if no MPLS label follows;
- length fields, for each frame based on its size;
- IPv4 header, UDP, TCP, ICMP, and ICMPv6 checksums, for each frame.
Clearing the Auto checkbox of a length or checksum field and setting a value turns off the calculation. This is how frames with an intentionally invalid checksum are built for negative tests.
Fields from sources and targets. MAC, IP address, and port fields can take values from the task, as in other plugins:
| Field | From source | From target |
|---|---|---|
| MAC | MAC of each source address according to its network's MAC policy: the port MAC, a fixed MAC, or a separate MAC for each address | Next-hop MAC toward the targets: the gateway MAC from the source network or one resolved by ARP/ND at startup |
| IPv4 / IPv6 | Addresses of the source port's networks: the subnet without the gateway and exclusions, and for IPv4 without .0 and .255 addresses | Addresses of all target networks in order, following the same rules |
| Port | Ports configured in the source port's networks | Ports configured in the target networks |
If the task's sources and targets are already selected while MACs, IPs, and ports are set manually, the constructor offers to fill them in from the task with the Fill in from task button or to keep them with the Keep manual button.
Payload and Frame Size
The Payload chip at the end of the stack opens two settings, Frame size and Fill:
| Setting | Description | Value |
|---|---|---|
| Frame size with FCS | Fixed: one size. Increment: from "From" to "To" with a step. Random: a random size from the range with a step. IMIX: Simple IMIX 7:4:1 (64 bytes × 7, 594 × 4, 1518 × 1, sizes evenly interleaved). Custom IMIX: your own sizes and weights. Auto: the smallest size for the header stack, but not less than 64 bytes | 64 to 9216 bytes; fixed 128 bytes by default. The sum of custom IMIX weights is no more than 4096 |
| Fill: bytes after the last header | Byte pattern (hex, repeated to the end of the frame, for example 0xDEADBEEF, up to 1024 bytes), Incrementing bytes, Decrementing bytes, or Random bytes (with an optional seed) | Zeros by default. The payload is the same in all frames and is truncated to the frame size |
The network card adds the four FCS bytes; they are not shown in the preview. If the task has a server, the last 16 bytes before the FCS hold the signature (see Client and Server).
Groups
Groups define how variable fields are combined:
- fields in one group change together, each cycling on its own, like independent increments;
- different groups are nested like counter digits: the top group is the outermost, and the bottom one changes fastest. This produces all combinations of fields from different groups.
Fields without a group go into the Default group. A group is selected in the field editor with the increment, decrement, list, from source, and from target patterns; random patterns do not belong to groups. A template can have up to 16 groups in addition to the default group. The tab shows the number of unique frames before the fields repeat (no more than 2^62).
Transmit
The rate and frame count are set for the selected stream; with several streams, the section heading names the stream.
| Setting | Description | Value |
|---|---|---|
| Rate mode | % of line rate: a share of the speed of each source port. Frames per second: the stream's frame rate on each source port | Line share greater than 0 and no more than 100%, 10% by default; frame rate from 1 to 1,000,000,000 frames per second |
| Frames per port | How many frames of the stream to send from each source port. After that, the stream stays silent while the other streams go on; if there is only one stream, the port stays silent until the end of the task duration | 0 (default) means sending until the end of the task duration |
| Plugin run time | The run time shared by all streams of the entry; the same values as in the Duration section | — |
When the line rate is calculated, 20 bytes of preamble and interframe gap are added to the mean frame size. Under the rate field, the constructor shows how many frames per second this gives on each source port, and for a rate in frames per second, what share of the port's line it takes. If the specified frame count cannot be sent within the task duration, the Frames per port field shows how many frames will actually be sent. The % of line rate mode requires a known port speed; if it cannot be detected, set the rate in frames per second.
Frames
The Frames tab shows the frames of the selected stream page by page: a frame table, a breakdown of the selected frame by headers and fields, and its bytes. The summary shows the number of unique frames, frame size, header length, and size cycle. If the task has several source ports, the port for the preview is selected in the Source port field: fields from the source take the addresses of that port's networks.
The port MAC and the gateway MAC become known only at startup, so the preview and pcap contain zeros in their place. The server signature is written at transmission, so the preview and pcap do not contain it. If sources or targets are not selected yet, fields that take values from them show default values in the preview. Such a task cannot be saved until the required sources and targets are selected.
The pcap file contains frames without FCS; the timestamp of frame n is n µs.
Streams
One client entry can hold up to 32 streams. Each stream has its own template, groups, rate, frame count, and tracking. All enabled streams go out together from every source port: the port shares its time between them according to their rates and interleaves the frames evenly, so over any interval a stream lags behind its share by no more than one frame. A stream that has sent its frame count goes silent, and the other streams keep their rates.
The stream actions are next to the Stream selector above the tabs:
| Button | What it does |
|---|---|
| New stream | Adds a stream with the default template (Ethernet II, IPv4, UDP) after the current one |
| Copy stream | Adds a copy of the selected stream after it: template, groups, rate, and tracking |
| Delete stream | Deletes the selected stream. The only stream cannot be deleted |
| All streams (N) | Opens the Streams tab. The button is shown when there is more than one stream |
On the Streams tab, a table shows every stream: name, headers, frame size, rate, frame count per port, and whether the stream is sent. Clicking a row selects the stream; double-clicking it or the Edit stream template button opens its template on the Packet tab. Below the table, you configure the selected stream:
- Stream name: up to 64 characters. Without a name, the stream is called "Stream N" ("Поток N"). The stream appears under this name in the selector and on the dashboard.
- Send stream: a disabled stream stays in the task but sends no frames and takes no share of the line. At least one stream must be sent.
- Tracking: how the server splits the stream into tracked flows (see Tracking).
The Line share per port block shows the sum of the streams set in % of line rate and, for each source port with a known speed, the share of the line that all enabled streams take together with the streams set in frames per second (based on the mean frame size). If the sum of the streams in % of line rate exceeds 100%, the task is not saved. If a port gets more than 100% of the line once the streams in frames per second are added, the port cannot send all the frames, and the stream rates drop. For a stream in frames per second with the Minimum frame size, the line share cannot be calculated in advance.
Tracking
The server keeps separate statistics (reception, loss, duplicates, order, delay) for each tracked flow. How a stream is split into tracked flows is set for each stream in the Tracking block on the Streams tab or with the Tracking checkbox in the field editor on the Packet tab:
| Mode | What counts as one tracked flow |
|---|---|
| Whole stream | The entire stream. This is the default mode |
| By fields | Each combination of the values of the selected fields. For example, if the source address (256 values) and the source port (16 values) are in different groups, tracking by both fields gives 4096 tracked flows |
The By fields mode is available when the stream's template has a field with the Increment, Decrement, List, From source, or From target pattern. Auto fields and fields with the Single value, Repeatable random, and Random from range patterns cannot be tracked: their value cannot be derived from the frame number. A tracked field switched to such a pattern stops being tracked. When you switch to By fields, all trackable fields are selected; clear the ones you do not need in the table, which shows the header, mode, and number of values for each field.
The number of tracked flows is shown under the table. For fields from sources and targets, it depends on each port's networks and is determined at startup. One stream can have up to 16,777,216 tracked flows; with more, the task is not saved, and with fields from sources and targets it does not start. If there are more than 1024 tracked flows, the server records the worst of them while the task runs, and the full table of all flows is available after the task stops.
Template Library
You can save a template to the library (a name of up to 128 characters and a description) to use it in another task. The library supports searching by name, description, and headers; a template can be opened, updated, or deleted. A task keeps its own copy of the template: changing or deleting the template in the library does not affect tasks.
Flow Statistics
Tracked flow statistics are on the Packet Constructor dashboard on the task's Metrics tab, in the Tracked flows section. The data is collected by the server: if the task has no server entry or has not run yet, the panels are empty.
- Flow table snapshot: which data is shown: a live snapshot (updated every second), the worst flows (while the task runs, if there are more than 1024 tracked flows: the worst by loss and delay, updated every 5 seconds), or the task result (all flows after the task stops).
- Tracked flows: the total number of tracked flows, how many of them are With loss, and how many are Silent (more than zero sent, zero received).
- Flows by loss share: how many tracked flows fall into each loss share range.
- Worst flows: up to 100 flows with loss, duplicates, or reordered frames, worst first.
- All tracked flows: the first 10,000 tracked flows by loss share, page by page. Click a column header to sort the table; the filter icon in a header selects rows by the column's values.
Columns of the flow tables:
| Column | What it shows |
|---|---|
| Stream | Stream name |
| Port | Source port number. The ports of all client entries of the task are numbered in order starting from 0 |
| Flow No. | Number of the tracked flow within the stream |
| Fields | Values of the tracked fields of this tracked flow, for example Source Address: 192.168.1.10, Source Port: 49152. A dash means the stream is tracked as a whole |
| Sent, Received | Frames sent and received |
| Lost, Loss, % | In the task result, sent frames that were not received (duplicates do not count as received); while the task runs, gaps in the numbers of received frames. The share is of the expected frames |
| Duplicates | Frames received more than once |
| Reordered | Frames that arrived after a frame with a higher number |
| Min, avg, max delay, µs | Delay of data frames, from transmission to reception. Empty if the server took no measurement: the client runs on another agent, or the stream's frames did not arrive |
| Jitter, µs | Mean change of delay between consecutive frames of the flow |
Delay and Probes
The delay in the tracked flow table is measured on data frames: the server compares the transmit time from the signature with the receive time. It can be measured only when the client and the server run on the same agent; otherwise, the delay columns are empty. While the port load is far from line rate, this delay does not include the tester's queue. At a load close to line rate, it includes the time the frame waits in the tester's own queue.
Probes measure the delay of the DUT itself at any load, up to line rate. A probe is a copy of a frame of one of the streams that the port sends at a random moment. The network card stamps the probe with the time it leaves the port, so the tester's queue is not part of the result. Probes go out at one per 1,000 data frames, but no more than 20,000 per second per port, and are not part of the stream counters: TX and RX in the table count data frames only. The result is shown in the DUT delay from probes section of the dashboard: mean, minimum, p99, p99.9, maximum, and the number of probes it is based on, as well as the delay per stream and its change over time.
Probes work when all of the following conditions are met:
- the source port is on an NVIDIA ConnectX-6 Dx network card, which stamps the time a frame leaves the port;
- the client and the server run on the same agent;
- the port sends at least 1,000 frames per second.
If there are no probes, the DUT delay from probes section is empty, and the DUT delay is shown by the delay columns for data frames: while the tester is far from the port limit, they do not include its queue.
Probes are a sample: percentiles over tens of thousands of probes are accurate, but a probe may miss a one-off delay spike of a single frame. Such a spike shows up in the Max delay column for data frames.
Metrics
Transmitted traffic appears in the common transmit metrics: packets, bytes, L1 bits, line utilization, and transmit drops (see Total Metrics).
The Metrics tab of a task with the Packet Constructor offers the Packet Constructor dashboard: transmission and reception per stream, loss, duplicates, order, delay from data frames and from probes, tracked flow statistics with the values of their fields (see Flow Statistics), and the server counters: frames without a signature and frames dropped by the network card. Without a server entry, the dashboard shows only per-stream transmission.
Limitations
- A task with the Packet Constructor can contain only Packet Constructor client and server entries; create a separate task for other plugins.
- The server receives and counts frames but does not respond to them: there is no TCP connection state. The TCP header is built as a regular frame header.
- The server needs at least one client entry in the same task. In a task with a server, all client entries together can have no more than 256 source ports, and the smallest frame of every enabled stream must fit the headers, the 16-byte signature, and the FCS.
- Delay is measured only when the client and the server run on the same agent. DUT delay from probes requires an NVIDIA ConnectX-6 Dx network card on the source port and at least 1,000 frames per second per port.
- Access networks (access groups) are not supported as sources or targets. Profiles from the Network Tunnels library are not applied: GRE, VXLAN, MPLS, and IP-in-IP are added as headers in the stack.
- If a MAC field takes its value from the target, the source network must have a gateway. If the gateway MAC is not set in the network, the port resolves it by ARP/ND at startup, and the task does not start until the gateway responds.
- Each source port needs at least one CPU core: the agent splits the cores between source ports. For frames larger than 1518 bytes, the agent enables jumbo frames; if there are not enough hugepages for all cores, the task does not start. In that case, set 4 to 8 cores in Advanced settings.
- Template: up to 32 headers, up to 16 groups, up to 65,536 values in one list and up to 2^20 values in the whole template, and up to 2^62 unique frames. Values from several address ranges of the task are limited to 65,536.
- Entry: up to 32 streams and up to 16,777,216 tracked flows per stream.
- The preview shows up to 1000 frames at a time, and the pcap export from the interface contains the first 1000 frames.
- The task can only run on agents whose version supports the Packet Constructor. Several enabled streams and a server entry require an agent version that supports streams and reception on all agents of the task.