netperfmeter(1)

📦
version 1.9.6 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, welcome to netperfmeter(1) — the General Commands Manual page — aka the Network Performance Meter. it's giving main character energy for network benchmarking 💅

🌸 SYNOPSIS 🌸

netperfmeter [Port]
netperfmeter [Destination:Port] -control-over-tcp
             -local=Address[,Address,...]
             -controllocal=Address[,Address,...] -runtime=Seconds
             -config=Name -scalar=Name -vector=Name
             -activenodename=Description -passivenodename=Description
             -quiet -verbose -verbosity=Level -v6only -pathmgr=name
             -scheduler=name -sndbuf=bytes -rcvbuf=bytes -tcp -sctp -udp
             -dccp [FLOWSPEC] [...]

🦋 DESCRIPTION 🦋

netperfmeter is a network performance meter, and no cap, it handles the UDP, TCP, MPTCP, SCTP and DCCP transport protocols. it simultaneously transmits bidirectional flows to an endpoint and measures the resulting flow bandwidths. and then? the results get written out as vector and scalar files. obsessed. 😌✨

💖 ARGUMENTS 💖

these are the arguments you have to provide, fr fr:

  • Port — the port number for the passive side's data socket. the port number of the control socket is gonna be port+1. and the way that specifying a port number turns netperfmeter into passive mode… it just sits there and waits for incoming connections. lowkey iconic of it 🫶
  • Destination:Port — specifies the destination endpoint to connect to. this flips netperfmeter into active mode, meaning it goes and connects to that remote endpoint. no waiting around, she's proactive 💅
  • -control-over-tcp — use TCP instead of SCTP for the control connection. super handy for NAT traversal, iykyk.
  • -local=Address[,Address,...] — specifies address(es) of the local data endpoint. ⚠️ heads up: for TCP, UDP and DCCP, only the first address is used! on an active node, this option applies to the following flows, so it must be set before specifying a flow. periodt.
  • -controllocal=Address[,Address,...] — specifies address(es) of the local control endpoint (SCTP or TCP). and again: for TCP, only the first address is used!
  • -runtime — specifies the measurement runtime in seconds. after that time span is up, netperfmeter finishes the measurement. bye bestie 👋
  • -config=Name — specifies the name of the configuration file to write. default is output.config.
  • -vector=Name — specifies the name pattern of the vector files to write. if the suffix of this name is .bz2, the file gets BZip2-compressed on the fly ✨. the vector name is automatically extended to name the flow vector files by adding -<active|passive>-<flow_id>-<stream_id> before the suffix. default is vector.vec.bz2, so the name of the vector file for flow 5, stream 2 on the passive node will be vector-passive-00000005-0002.vec.bz2. cute, right?
  • -scalar=Name — specifies the name pattern of the scalar files to write. if the suffix is .bz2, it gets BZip2-compressed on the fly too. the scalar name is automatically extended to name the flow scalar files by adding -<active|passive>-<flow_id>-<stream_id> before the suffix. default is scalar.vec.bz2, so the name of the scalar file for flow 5, stream 2 on the passive node will be scalar-passive-00000005-0002.vec.bz2.
  • -activenodename=Description — sets a textual description of the active node (e.g. Client).
  • -passivenodename=Description — sets a textual description of the passive node (e.g. Server).
  • -quiet — reduces verbosity of log output. may be specified multiple times.
  • -verbose — increases verbosity of log output. may be specified multiple times.
  • -verbosity=Level — sets the verbosity of the log output to a given level, from 0 (lowest) to 6 (highest). pick your vibe 🌈
  • -v6only — use sockets with IPv6 only (by setting the IPV6_V6ONLY socket option).
  • -pathmgr=name — set MPTCP path manager for the passive node (MPTCP for Linux only. requires socket options kernel patch!). on an active node, this option applies to the following flows, so it must be set before specifying a flow!
  • -scheduler=name — set MPTCP scheduler for the passive node (MPTCP for Linux only. requires socket options kernel patch!). on an active node, this option applies to the following flows, so it must be set before specifying a flow!
  • rcvbuf=bytes — sets the receiver buffer size (on the listening socket) to the given number of bytes.
  • sndbuf=bytes — sets the sender buffer size (on the listening socket) to the given number of bytes.
  • -sctp — establish a new SCTP association. the streams of this association must be specified by one or more FLOWSPEC specifications as following parameters.
  • -tcp — establish a new TCP or MPTCP connection. the flow of this connection must be specified by a FLOWSPEC specification as following parameter. MPTCP support in NetPerfMeter is realized as an additional "MPTCP" socket (i.e. another TCP socket, but bound to another port number and with CMT enabled). so for MPTCP usage, it must contain the option cmt=mptcp (see below) to usage the MPTCP socket instead of the TCP socket. 🧚
  • -udp — establish a new UDP connection. the flow of this connection must be specified by a FLOWSPEC specification as following parameter.
  • -dccp — establish a new DCCP connection. the flow of this connection must be specified by a FLOWSPEC specification as following parameter. note that DCCP is not available on all platforms yet. currently, only Linux provides DCCP in its official kernel. 💀
  • FLOWSPEC — specifies a new flow. the format is:
outgoing_frame_rate:outgoing_frame_size:incoming_frame_rate:incoming_frame_size:option:...

the first four parameters (outgoing_frame_rate:outgoing_frame_size:incoming_frame_rate:incoming_frame_size:option) may be substituted by the option "default", creating a flow with some more or less useful default parameters.

  • outgoing_frame_rate — the frame rate of the outgoing transfer (i.e. active node to passive node). if set to const0, the sender will be saturarted, i.e. it will try to send as much as possible. go off, sender 💅
  • outgoing_frame_size — the frame size of the outgoing transfer (i.e. active node to passive node). if set to const0, there will be no data transmission in this direction. like, nothing. zero. silence. 😭
  • incoming_frame_rate — the frame rate of the incoming transfer (i.e. passive node to active node). see outgoing_frame_rate for details.
  • incoming_frame_size — the frame size of the incoming transfer (i.e. active node to passive node). see outgoing_frame_size for details.

🎀 possible options 🎀

  • id=Flow Identifier — sets an ID number for the flow. ⚠️ the IDs within a measurement must be unique!
  • description=Description — sets a textual description of the flow (e.g. HTTP-Flow). do not use spaces in the description! bestie. please.
  • maxmsgsize=Bytes — splits frames into messages of at most the given number of bytes. messages may not exceed 65535 bytes.
  • defragtimeout=Milliseconds — messages not received within this timeout after the last successfully received message are accounted as lost. NOTE: this also happens if the transport protocol is reliable and the message is actually received later! 😭 yes, really. it's giving unfair but that's the spec.
  • unordered=Fraction — specifies the fraction of the messages that will be sent in unordered mode (SCTP only).
  • ordered=Fraction — specifies the fraction of the messages that will be sent in ordered mode (SCTP only).
  • reliable=Fraction — specifies the fraction of the messages that will be sent in reliable mode (SCTP only).
  • unreliable=Fraction — specifies the fraction of the messages that will be sent in unreliable mode (SCTP only).
  • rtx_timeout=Milliseconds — sets the retransmission timeout for unreliable messages (SCTP only; not available on all platforms!).
  • rtx_trials=Trials — sets the retransmission trials for unreliable messages (SCTP only; not available on all platforms!).
  • rcvbuf=Bytes — sets the receiver buffer size to the given number of bytes.
  • sndbuf=Bytes — sets the sender buffer size to the given number of bytes.
  • onoff=t1,t2,...[,repeat] — a list of time stamps when the flow should be activated or deactivated. if onoff is given, the flow is off at startup. at t1, it will be turned on; at t2, it will be turned off, etc.. time stamps can be given as absolute values (e.g. onoff=0,10,30 — to turn on at t=0, turn off at t=10 and turn on again at t=30 until end of measurement) or relative values (e.g. on=10,+30,+60 — to turn on at t=10, turn off at t=40 and turn on again at t=100 until end of measurement). a repetition of the list is possible with the keyword "repeat" at the end of the list. then, all values need to be relative values and the number of items must be even. 🌸
  • error_on_abort=on|off — by default, the active side stops with an error when a transmission tails (e.g. on connection abort). this parameter turns this behaviour on or off. your call bestie 💅
  • nodelay=on|off — kills the Nagle algorithm, aka stops your packets from being held back waiting for more data to glom onto. TCP and SCTP only, bestie. Default is off 💅
  • debug=on|off — flips debug mode on the socket. Currently MPTCP for Linux only, and ngl it requires the socket options kernel patch! So no patch, no debug, no cap 🫶
  • ndiffports=number — sets how many different MPTCP subflows you want. MPTCP for Linux only, and again it requires the socket options kernel patch! ⭐
  • -v6only — use a socket that's IPv6 only, by setting the IPV6_V6ONLY socket option. Iconic, exclusive, no crossover energy 🌈
  • pathmgr=name — set the MPTCP path manager. MPTCP for Linux only, and yep, it requires the socket options kernel patch! 🧚
  • scheduler=name — set the MPTCP scheduler. MPTCP for Linux only, and once more with feeling: requires the socket options kernel patch! 💀
  • cc=name — set the congestion control name. TCP and MPTCP for Linux only 🍓
  • cmt=off|cmt|cmtrpv1|cmtrpv2|like-mptcp|mptcp-like|mptcp — configures whether Concurrent Multipath Transfer (CMT) gets used, and honestly the way this one has a whole menu of moods:
    • off — turned off, and this is the default 💤
    • cmt — independent paths
    • cmtrpv1 — CMT/RPv1
    • cmtrpv2 — CMT/RPv2
    • mptcp / like-mptcp / mptcp-like — MPTCP
    • 0-255 — a custom value, if you're feeling spicy

Currently only supported by CMT-SCTP on FreeBSD systems and MPTCP on Linux systems. And heads up: CMT for MPTCP always uses MPTCP congestion control. Periodt ✨

🌸 EXAMPLES 🌸

Some netperfmeter usage examples, because seeing it in action hits different:

netperfmeter 9000

Start in passive mode, i.e. accepting connections, on port 9000 💖

netperfmeter 172.16.255.254:9000 -vector=output.vec.bz2
-scalar=output.sca.bz2 -sctp
const5:exp1000:const3:exp500:description="Alpha":onoff=+10
const5:exp1000:const3:exp500:description="Beta":onoff=+30 -tcp
const5:exp1000:const3:exp500:description="Gamma":onoff=+60
-runtime=300

Start in active mode, i.e. establish connection to 172.16.255.254, port 9000. Frames will be segmented into messages of up to 4096 bytes. Write vectors to output.vec.bz2 (BZip2-compressed). Write scalars to output.sca.bz2 (BZip2-compressed). Establish SCTP association. At t=10s, start flow "Alpha" as first stream of this association, using a frame rate of 5 (constant) and average frame size of 1000 bytes (negative exponential distribution) for the outgoing data and a frame rate of 3 (constant) and average frame size of 500 bytes (negative exponential distribution) for the incoming data. At t=30s, start flow "Beta" as second stream on the SCTP association (same parameters as flow "Alpha"). Start TCP connection. At t=60s, start flow "Gamma" over the TCP connection (same parameters as flow "Alpha"). At t=300s, stop the measurement. Main character energy, honestly 👑

netperfmeter 172.16.255.254:9000 -control-over-tcp -tcp const2:const1000

Start in active mode, i.e. establish connection to 172.16.255.254, port 9000. The control connection uses TCP instead of SCTP. Simple, clean, slay 🔥

🎀 AUTHORS 🎀

Thomas Dreibholz 💜

okay bestie that's the whole page!! This was the netperfmeter(1) manual, dated April 29, 2016 — go forth and measure your networks, you absolute legend 🦋✨💖

📦 where this page comes from