UDPBENCH(1)

NAME
udpbench - udp network benchmarking tool

SYNOPSIS
udpbench [-DGHw] [-B bitrate] [-b bufsize] [-C pseudo] [-d delay] [-I ifaddr] [-i idle] [-L loop] [-l length] [-m mmsglen] [-N repeat] [-P packetrate] [-p port] [-R remoteprog] [-r remotessh] [-T ttl] [-t timeout] send | recv [hostname]

DESCRIPTION
The udpbench benchmark tool sends or receives UDP packets between two IP end points. It measures the throughput on both sides. The local action has to be given as send or recv. hostname is the IP address for connect(2) when sending or bind(2) when receiving. In the latter case it is optional, then the unspecified address is used. hostname may also be a multicast group. For receiving multicast, the interface has to be specified with the -I ifaddr option.

The options are as follows:

-B bitrate
    The value specifies the number of bits to send over the wire within a second. The size of the ethernet frame is calculated from UDP payload length. This adds a small delay between send(2) system calls if packets would be generated too fast otherwise.

-b bufsize
    Set size of send or receive socket buffer.

-C pseudo
    Account for the given pseudo interface type when calculating payload sizes.

-D  OpenBSD pf(4) divert-packet is used to receive packets on divert socket. The pf rule has to be configured manually, the option only changes the socket type on the recv side. In send mode this option has no effect on local sending. With dynamic ssh the option is passed to the remote process.

-d delay
    Sleep some seconds before sending packets with payload. This is useful to wait for setup of multiple processes via ssh. An initial empty packet is sent before delay to trigger setup. Default is 0 seconds which disables the feature.

-G  Use UDP send and receive offload. This requires setting -m mmsglen and -l length greater than 0. This option is only available on systems that define UDP_SEGMENT and UDP_GSO.

-H  Use IPv6 hop-by-hop option by adding a router alert when sending.

-I ifaddr
    If hostname is a multicast group, the interface has to be specified. For IPv4 this must be an interface address, while IPv6 requires the interface name.

-i idle
    After a period of not receiving any packets, the recv side will stop. Default is 1 second, 0 will ignore idle periods.

-L loop
    When sending UDP multicast, set loop to 1 to receive a copy of the packet on the loopback interface.

-l length
    Set length of the UDP payload for sending, or length of the userland buffer for receiving the packet. By default the payload is empty.

-m mmsglen
    Use recvmmsg(2) and sendmmsg(2) and set the amount of simultaneously handled messages. Default is to use recv(2) and send(2). This can be explicitly enforced by setting mmsglen to 0.

-N repeat
    Fork multiple processes to send or receive in parallel. For each process the IP address is incremented by one to get load balancing.

-P packetrate
    The value specifies the number of packets to send within a second. This adds a small delay between send(2) system calls if packets would be generated too fast otherwise.

-p port
    The destination UDP port is 12345 by default. When set to 0, a random port is used.

-R remoteprog
    When the remote side is started dynamically via ssh, use this path for the udpbench program. By default the remote program is invoked the same way as the local udpbench.

-r remotessh
    The receiving and sending process can be started manually or dynamically. If the remotessh location is given as user@host, an udpbench process is started on the remote machine with the send and recv parameter exchanged.

-T ttl
    When sending UDP multicast, set ttl to specify the IPv4 time to live or IPv6 hop limit of the outgoing packet. The default kernel multicast ttl value is 1 and 255 maximum. Reset a previous ttl option to default with -1.

-t timeout
    Set the duration for sending packets. When receiving, all packets have to arrive within this timeout plus two seconds. Disable timeout with 0 and run forever. Default is 1 second.

-w  Use write(2) instead of send(2) for the send action or read(2) instead of recv(2) for the recv action. They may have different throughput on some systems.

EXAMPLES
Receive UDP packets on any address and port 12345. Run for 12 seconds to process all input.
    udpbench -t 10 recv

Send empty UDP packets to local host port 12345. Run for 10 seconds and process as much as possible.
    udpbench -t 10 send 127.0.0.1

Test throughput of loopback interface for one second. Two udpbench processes are started, one with send and one dynamically with recv. As the destination port is random, but is the same for both sides, multiple instances can be started in parallel.
    udpbench -r localhost -p 0 send 127.0.0.1

Log into remote host and receive packets from there. The address of the receiving side is not optional.
    udpbench -r root@remotehost recv localip

This sends the traffic in the opposite direction of the previous example.
    udpbench -r root@remotehost send remoteip

Receive packets from remote host and divert them to local socket. This needs configuration in pf.conf(5).
    pass proto udp to localip port 1234 divert-packet port 1234
    udpbench -D -p 1234 -r root@remotehost recv localip

DIAGNOSTICS

udpbench recv: recv 1: Interrupted system call While the receiver was waiting for the first packet, the timeout triggered. Check connectivity, start sender quickly after receiver, increase -t timeout.

udpbench recv: not enough idle time For the receiving side the stream of packets finishes after 1 second idle time. If the receive timeout happens earlier, the measurement is incomplete. Increase -t timeout.

send: syscalls 812635, packets 812635, frame 1, payload 1452, ip 1500, ether 1538, begin 1706272739.464771, end 1706272749.464692, duration 9.999921, bit/s 9.99874e+08, start 1706272738.464447, stop 1706272749.464716

Summary of udpbench sending side. Status is printed as single line just before exit.

syscalls
    Number of send(2), write(2), or sendmmsg(2) system calls made.

packets
    Number of packets sent.

frame
    Number of ethernet frames for each packet.

payload
    Bytes in the UDP payload.

ip  Length of IP packet.

ether
    Length of ethernet frame.

begin
    Time stamp when the first packet with payload was sent. If -d delay is set, this is after the sleeping delay.

end Time stamp after the final packet was sent.

duration
    Time between begin and end.

bit/s
    Bits of all packets in ethernet size during duration per second.

start
    Time stamp after socket is connected.

stop
    Time stamp before socket is closed.

recv: syscalls 374484, packets 374431, frame 1, payload 1452, ip 1500, ether 1538, begin 1706272739.464876, end 1706272749.473193, duration 10.008317, bit/s 4.60317e+08, start 1706272738.024436, stop 1706272754.024705

Summary of udpbench receiving side, only difference to send is explained.

syscalls
    Number of recv(2), read(2), or recvmmsg(2) system calls made.

packets
    Number of packets received.

begin
    Time stamp when the first packet with payload was received. If -d delay is set, this is after the empty packet starting the delay.

end Time stamp after the final packet was received. If -i idle is set, end is the time before idle timed out.

start
    Time stamp after socket is bound.

SEE ALSO
tcpbench(1)

AUTHORS
The udpbench program was written by Alexander Bluhm <bluhm@genua.de>.

CAVEATS
Using -r remotessh together with multicast groups usually does not work. The interface address and name are different on the remote machine, but -I ifaddr affects both local and remote.

BUGS
The number of ethernet frames and their size is calculated. With vlan or jumbo it will be wrong.