---
title: "swx-perf"
slug: "swx-perf"
updated: 2025-12-19T20:16:43Z
published: 2025-12-19T20:16:43Z
canonical: "docs.swxtch.io/swx-perf"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swxtch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# swx-perf

> [!NOTE]
> **WHAT TO EXPECT**
> 
> swx-perf is a tool that creates traffic on the cloudSwXtch overlay network using roles of producers and consumers.
> 
> **In this article**, users will learn how to use the tool.

### Overview

As a **producer**,****`swx-perf`****has multiple parameters that can be configured to generate traffic flows with different characteristics. This versatile tool can generate several streams on a single instance (using ranges), can be executed several times to generate multiple instances concurrently on the same VM, and can be run as a producer on several VMs.

The mandatory arguments for a producer are the socket and the interface:

```shell
swx-perf producer --sendto <MULTICAST-ADDRESS:PORT> --nic <NETWORK_INTERFACE>
```

As a **consumer,**`swx-perf`****will pick up the traffic generated by the producer(s) in the network. It can consume one stream or a range of streams on each instance, and can be executed to generate several instances on the same VM, or on different VMs.

The mandatory arguments for a consumer are:

```shell
swx-perf consumer --recvfrom <MULTICAST-ADDRESS:PORT> --nic <NETWORK_INTERFACE>
```

In both cases, the <MULTICAST-ADDRESS:PORT> is the socket you want to use to send/receive the stream. But it can also use ranges, both in the IP and the port, separately or simultaneously. For example: 239.1.1.1-239.1.1.100;10000-10050

> [!WARNING]
> NOTE
> 
> Regarding the MULTICAST-ADDRESS, we recommend referring to the [IANA IPv4 Multicast Address Space Registry](https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml). Currently, the xNIC can’t join a multicast stream on the reserved IP 224.0.0.1.

The <NETWORK_INTERFACE> is the name of the adapter.

For example, if you have an xNIC Type 1, or 3 you can produce traffic to the multicast address 239.1.1.1 using port 10000 with the command:

```shell
swx-perf producer --sendto 239.1.1.1:10000 --nic swx0
```

On another VM, you can consume using an xNIC Type 2 with a data interface eth1 with the command:

```shell
swx-perf consumer --recvfrom 239.1.1.1:10000 --nic eth1
```

It can also:

- can produce/consume different protocols (UDP, RTP, SRT & RIST)
- can vary the payload length
- can vary its contents randomly
- can use broadcast traffic (same subnet) or generic broadcast (255.255.255.255)
- can use SSM traffic
- can produce/consume generic (no swx-perf) traffic (for example, traffic created by another tool like iPerf)
- can measure latency, both one-way (needs time-sync) or round-trip
- can be executed for a fixed amount of time or packages
- can replay a pcap file

## swx-perf

For a quick view of the functionality and usage of `swx-perf` use `-h` or `-help`.

```plaintext
$ swx-perf -h
Usage: swx-perf [--help] [--version] [--nic VAR] [--recvfrom VAR] [--sendto VAR] [--payload_length VAR] [--pps VAR] [--broadcast] [--generic-broadcast] [--broadcast-port VAR] [--ssm_include VAR...] [--ssm_exclude VAR...] [--generic] [--total_pkts VAR] [--seconds VAR] [--loopback] [--rtt-latency] [--one-way-latency] [--latency-buckets] [--dbg] [--show-full-packet-bps] [--pcap VAR] [--no-perf-header] [--random-payload] [--json-report] command

Positional arguments:
  command                 [producer|consumer] suported commands

Optional arguments:
  -h, --help              shows help message and exits
  -v, --version           prints version information and exits
  --nic                   name of NIC to use
  --recvfrom              Format: "[<protocol>://][@]<ip>:<port>"
                          Supported Protocols : [udp, rtp, srt, rist]
                          If protocol field is not defined in the argument, the protocol is UDP by default.
  --sendto                Format: "[<protocol>://][@]<ip>:<port>"
                          Supported Protocols : [udp, rtp, srt, rist]
                          If protocol field is not defined in the argument, the protocol is UDP by default.
  --payload_length        (producer command only) number of bytes for the multicast udp payload [nargs=0..1] [default: 100]
  --pps                   (producer command only) packet-rate or packet per seconds [nargs=0..1] [default: 1]
  --broadcast             Enables broadcast traffic flow on the subnet of the indicated NIC.
                          Therefore no other traffic will be handled and --sendto and --recvfrom args are ignored.
  --generic-broadcast     Sends broadcast packets to 255.255.255.255, valid only with --broadcast argument
  --broadcast-port        Port for broadcast traffic, valid only with --broadcast argument
  --ssm_include           (consumer command only) List of SSM addresses to include (i.e. 192.168.2.1 193.168.2.4) [nargs: 1 or more]
  --ssm_exclude           (consumer command only) List of SSM addresses to exclude (i.e. 192.168.2.1 193.168.2.4) [nargs: 1 or more]
  --generic               (consumer command only) to consume generic packets
  --total_pkts            Total packets to send/receive. To run without this limit use 0 [nargs=0..1] [default: 0]
  --seconds               Number of seconds to run the application. To run without this limit use 0 [nargs=0..1] [default: 0]
  --loopback              Receives packets from --recvfrom and sends packets to --sendto
  --rtt-latency           Enables measurement of RTT/2 where RTT = round trip time
  --one-way-latency       Enables measurement of one way latency
  --latency-buckets       Enables histogram of latency.
  --dbg                   Enables more information in the logs
  --show-full-packet-bps  Shows the bps with all headers included
  --pcap                  PCAP arguments. Format is : "pcap_file_name,enable_timestamp,enable_loopback".
                          Pcap file name is the only mandatory parameter, the other parameters are false by default. [nargs=0..1] [default: ""]
  --no-perf-header        Does not include perf-header into packets payload.
  --random-payload        Fill payload with random data. If not set, payload will be 0.
  --json-report           Displays a JSON report with the totals on exit.
```

### Parameters

| Argument | Description | Default Value | Valid Range | Mode |
| --- | --- | --- | --- | --- |
| `h` | Shows commands that are available. |  |  |  |
| `v` | Shows version. |  |  | Both |
| `nic` | Specify the name of the network interface that swx-perf will use to produce or consume. **This argument is mandatory.** |  | Name of the adaptor as displayed by the OS | Both |
| `recvfrom` | Specify the IPv4 socket used to receive. **Mandatory *for Consumer mode***. Can be a range of IPs or ports. |  | Any valid IP for unicast, any valid multicast IP for multicast. Port should be in the range between 1024 and 65535. Express a range using a hyphen. | Consumer |
| `sendto` | Specify the IPv4 socket used to send packets. **Mandatory *for Producer mode***. Can be a range of IPs or ports. |  | Any valid IP for unicast, any valid multicast IP for multicast. Port should be in the range between 1024 and 65535. Express a range using a hyphen. | Producer |
| `payload_length` | Number of bytes per packet (excluding the headers). | 100 | 8 and 65475 | Producer |
| `pps` | Packets Per Second specifies the rate at which the producer will send packets. | 1 | Unbounded. Depends on the producer’s hardware ability to generate the traffic | Producer |
| `broadcast` | Sets swx-perf to use normal broadcast mode (i.e., will use the broadcast address of the network segment). When sending, it will use the IP of the `--nic` argument. | false | true/false | Both |
| `generic-broadcast` | Sets `swx-perf` to use generic broadcast mode using the IP 255.255.255.255. | false | true/false | Both |
| `broadcast-port` | Sets the port to be used for broadcast, and is only valid with `--broadcast` and `--generic-broadcast` arguments, and it is **mandatory *when using those arguments***. |  | Between 1024 and 65535 | Both |
| `ssm_include` | List of SSM addresses to include (i.e. 192.168.2.1 193.168.2.4) |  | 1 or more | Consumer |
| `ssm_exclude` | List of SSM addresses to exclude (i.e. 192.168.2.1 193.168.2.4) |  | 1 or more | Consumer |
| `generic` | Consume generic packets. Useful to consume a stream generated by a different tool. | false | true/false | Consumer |
| `total_pkts` | Number of packets to receive or send before exiting `swx-perf`. | No limit | 8 and 3750 | Producer |
| `seconds` | Number of seconds to run the application; use 0 to run without a limit. | 0 | No limit | Both |
| `loopback` | Receives packets from `recvfrom` and sends packets to `sendto`. | false | true/false | Both |
| `rtt-latency` | Enables timestamp propagation and measurement of RTT/2 where RTT = round-trip time. | false | true/false |  |
| `one-way-latency` | Enables timestamp propagation and measurement of one-way latency. | false | true/false | Both |
| `latency-buckets` | Shows a histogram of latency. Must be used with `--latency` | false | true/false |  |
| `dbg` | Enables more information in the logs | false | true/false | Both |
| `show-full-packet-bps` | Shows the BPS with all headers included. | false | true/false | Both |
| `pcap` | Allows the use of a PCAP file. |  | File name is mandatory. | Both |
| `no-perf-header` | Tells `swx-perf` not to include perf-header in packet payload. | false | true/false | Both |
| `random-payload` | Fill payload with random data. | false | true/false | Both |
| `json-report` | Displays a JSON report with the totals on exit. | false | true/false | Both |

### Examples

#### Multicast

1. Single multicast stream: Run this command on a VM using xNIC Type 1 to produce a multicast group on the address `239.1.1.1` and port `10000`:

```shell
swx-perf producer --sendto 239.1.1.1:10000 --nic swx0
```

****Example with output:****

```shell
$ swx-perf producer --sendto 239.1.1.1:10000 --nic swx0
Config:
        Sending traffic.
        Ip Address: 239.1.1.1 - Port: 10000
        Interface IP Address: 172.30.0.126
        Running without a total packet counter limit
        Running the application without a timing limit
|------------------------------------------------------------------------------------|
|                  TX TOTALS                 |             TX THIS PERIOD            |
|--------------------------------------------|---------------------------------------|
|      PKTS     |    BYTES   |     MISSING   |     PPS   |    BPS    |    MISSING    |
|---------------|------------|---------------|-----------|-----------|---------------|
|             1 |        100 |             0 |         0 |         0 |             0 |
|             2 |        200 |             0 |         1 |       794 |             0 |
|             3 |        300 |             0 |         1 |       794 |             0 |
|             4 |        400 |             0 |         1 |       794 |             0 |
|             5 |        500 |             0 |         1 |       794 |             0 |
|             6 |        600 |             0 |         1 |       794 |             0 |
|             7 |        700 |             0 |         1 |       794 |             0 |
^C
Results Producer:
        Complete in 8004 ms.
        Processed a total of: 7 packets.
        0.9 datagrams per second.
Group           Port            Packets       Bytes
------------------------------------------------------------
239.1.1.1       10000           7             700
------------------------------------------------------------
Totals:                         7             700
Percentages over total packets : Processed: 100.00% - Dropped:  0.00%
 Closing swx-perf...
```
2. Run this command on one VM to consume the traffic produced in the previous step:

```shell
swx-perf consumer --recvfrom 239.1.1.1:10000 --nic swx0
```

****Example with output:****

```shell
$ swx-perf consumer --recvfrom 239.1.1.1:10000 --nic swx0
Config:
        Waiting traffic
        Ip Address: 239.1.1.1 - Port: 10000
        Interface IP Address: 172.30.0.204
        Running without a total packet counter limit
        Running the application without a timing limit
|-------------------------------------------------------------------------------------------------------|
|                   RX TOTALS                   |                     RX THIS PERIOD                    |
|-----------------------------------------------|-------------------------------------------------------|
|      PKTS     |       OOO     |    MISSING    |       OOO     |    MISSING    |    PPS    |    BPS    |
|---------------|---------------|---------------|---------------|---------------|-----------|-----------|
|             0 |             0 |             0 |             0 |             0 |         0 |         0 |
|             0 |             0 |             0 |             0 |             0 |         0 |         0 |
|             1 |             0 |             0 |             0 |             0 |         1 |       794 |
|             2 |             0 |             0 |             0 |             0 |         1 |       794 |
|             3 |             0 |             0 |             0 |             0 |         1 |       794 |
|             4 |             0 |             0 |             0 |             0 |         1 |       794 |
|             5 |             0 |             0 |             0 |             0 |         1 |       794 |
|             6 |             0 |             0 |             0 |             0 |         1 |       794 |
|             7 |             0 |             0 |             0 |             0 |         1 |       794 |
|             8 |             0 |             0 |             0 |             0 |         1 |       794 |
|             9 |             0 |             0 |             0 |             0 |         1 |       794 |
|            10 |             0 |             0 |             0 |             0 |         1 |       794 |
|            11 |             0 |             0 |             0 |             0 |         1 |       794 |
^C
Results Consumer:
Complete in 13732 ms.
        Processed a total of: 12 packets.
        0.9 datagrams per second.
Group           Port            Packets       Bytes         OutOfOrder    Drops         Last Seq
---------------------------------------------------------------------------------------------------
239.1.1.1       10000           12            1200          0             0             57
---------------------------------------------------------------------------------------------------
Totals:                         12            1200          0             0
Total packets received:             12
Percentages over total packets : Processed: 100.00%  - Dropped  0.00% - OutOfOrder  0.00%
 Closing swx-perf...
```
3. Multiple multicast streams: Run this command on a VM to create 10 streams from 239.1.1.1 to 239.1.1.10 on port 10000, with a rate of 10000 PPS and a payload length of 3000 bytes on an xNIC Type 3:

```shell
swx-perf producer --sendto 239.1.1.1-10:10000 --pps 10000 --payload_length 3000 --nic swx0
```

****Example with output:****

```shell
$ swx-perf producer --sendto 239.1.1.1-10:10000 --pps 10000 --payload_length 3000 --nic swx0
Config:
        Sending traffic.
        Ip Address: 239.1.1.1 - Port: 10000
        Ip Address: 239.1.1.2 - Port: 10000
        Ip Address: 239.1.1.3 - Port: 10000
        Ip Address: 239.1.1.4 - Port: 10000
        Ip Address: 239.1.1.5 - Port: 10000
        Ip Address: 239.1.1.6 - Port: 10000
        Ip Address: 239.1.1.7 - Port: 10000
        Ip Address: 239.1.1.8 - Port: 10000
        Ip Address: 239.1.1.9 - Port: 10000
        Ip Address: 239.1.1.10 - Port: 10000
        Interface IP Address: 172.30.0.126
        Running without a total packet counter limit
        Running the application without a timing limit
|------------------------------------------------------------------------------------|
|                  TX TOTALS                 |             TX THIS PERIOD            |
|--------------------------------------------|---------------------------------------|
|      PKTS     |    BYTES   |     MISSING   |     PPS   |    BPS    |    MISSING    |
|---------------|------------|---------------|-----------|-----------|---------------|
|           780 |      2.33M |             0 |         0 |         0 |             0 |
|       116,590 |       349M |             0 |      115K |      2.7G |             0 |
|       230,090 |       690M |             0 |      112K |      2.7G |             0 |
|       341,320 |      1.02G |             0 |      110K |      2.6G |             0 |
|       449,880 |      1.34G |             0 |      107K |      2.5G |             0 |
|       557,880 |      1.67G |             0 |      107K |      2.5G |             0 |
|       663,830 |      1.99G |             0 |      105K |      2.5G |             0 |
|       769,610 |      2.30G |             0 |      105K |      2.5G |             0 |
|       874,970 |      2.62G |             0 |      104K |      2.5G |             0 |
|       979,930 |      2.93G |             0 |      104K |      2.5G |             0 |
|     1,083,840 |      3.25G |             0 |      103K |      2.4G |             0 |
|     1,187,130 |      3.56G |             0 |      102K |      2.4G |             0 |
|     1,289,780 |      3.86G |             0 |      102K |      2.4G |             0 |
|     1,392,120 |      4.17G |             0 |      101K |      2.4G |             0 |
|     1,493,850 |      4.48G |             0 |      101K |      2.4G |             0 |
|     1,595,370 |      4.78G |             0 |      100K |      2.4G |             0 |
|------------------------------------------------------------------------------------|
|                  TX TOTALS                 |             TX THIS PERIOD            |
|--------------------------------------------|---------------------------------------|
|      PKTS     |    BYTES   |     MISSING   |     PPS   |    BPS    |    MISSING    |
|---------------|------------|---------------|-----------|-----------|---------------|
|     1,696,916 |      5.09G |             0 |      100K |      2.4G |             0 |
|     1,798,710 |      5.39G |             0 |      101K |      2.4G |             0 |
|     1,900,340 |      5.70G |             0 |      100K |      2.4G |             0 |
|     2,001,950 |      6.00G |             0 |      100K |      2.4G |             0 |
|     2,103,150 |      6.30G |             0 |      100K |      2.4G |             0 |
^C
Results Producer:
        Complete in 21714 ms.
        Processed a total of: 2154400 packets.
        99217.1 datagrams per second.
Group           Port            Packets       Bytes
------------------------------------------------------------
239.1.1.1       10000           215440        646320000
239.1.1.2       10000           215440        646320000
239.1.1.3       10000           215440        646320000
239.1.1.4       10000           215440        646320000
239.1.1.5       10000           215440        646320000
239.1.1.6       10000           215440        646320000
239.1.1.7       10000           215440        646320000
239.1.1.8       10000           215440        646320000
239.1.1.9       10000           215440        646320000
239.1.1.10      10000           215440        646320000
------------------------------------------------------------
Totals:                         2154400       6463200000
Percentages over total packets : Processed: 100.00% - Dropped:  0.00%
 Closing swx-perf...
```
4. Single UDP traffic: Run this command on an xNIC Type 3 to send UDP traffic on the NIC eth1 with a payload size of 1000 bytes (excluding headers) for 10 seconds:

```shell
swx-perf producer --sendto UDP://239.1.1.1-10:10000-10010 --pps 1000 --nic eth1 --payload_length 1000 --seconds 10
```
5. Consume broadcast traffic: Run this command on an xNIC Type 2 using data NIC eth1 to consume broadcast traffic:

```shell
swx-perf consumer --broadcast --nic eth1
```
6. Latency measurement: Run these commands on xNIC Type 1 VMs to measure latency using ping-pong mode: Producer

```shell
swx-perf producer --nic swx0 --sendto 230.1.1.1:10000 --rtt-latency --loopback --recvfrom 230.1.1.2:10001 --pps 1000 --seconds 1200
```

Consumer

```plaintext
swx-perf consumer --nic swx0 --recvfrom 230.1.1.1:10000 --loopback --sendto 230.1.1.2:10001
```