netperfmeter(1)

NAME
netperfmeter - Network Performance Meter

SYNOPSIS
netperfmeter local_port
[-x | --control-over-sctp | -X | --no-control-over-sctp]
[-y | --control-over-tcp | -Y | --no-control-over-tcp | -w | --control-over-mptcp | -W | --no-control-over-mptcp]
[-L address[,address,...] | --local address[,address,...]]
[-l address[,address,...] | --controllocal address[,address,...]]
[-K key_file | --tls-key key_file] [-J certificate_file | --tls-cert certificate_file] [-I ca_certificate_file | --tls-ca ca_certificate_file]
[--6 | --v6only]
[--display | --nodisplay]
[--loglevel level] [--logcolor on|off] [--logfile file] [--logappend file]
[-q | --quiet] [! | --verbose]
netperfmeter remote_endpoint:remote_port
[-x | --control-over-sctp | -y | --control-over-tcp | -w | --control-over-mptcp]
[-L address[,address,...] | --local address[,address,...]]
[-l address[,address,...] | --controllocal address[,address,...]]
[-H hostname_file | --tls-hostname hostname]
[--6 | --v6only] [--display | --nodisplay]
[-o bytes | --sndbuf bytes] [-i bytes | --rcvbuf bytes] [-N count | --count count]
[-T seconds | --runtime seconds]
[-C configuration_file | --Ar -config -configuration_file]
[-S scalar_file_pattern | --scalar scalar_file_pattern]
[-V vector_file_pattern | --vector vector_file_pattern]
[-A description | --activenodename description]
[-P description | --passivenodename description]
[--loglevel level] [--logcolor on|off] [--logfile file] [--logappend file]
[-t FLOWSPEC | --tcp FLOWSPEC]
[-m FLOWSPEC | --mptcp FLOWSPEC]
[-u FLOWSPEC | --udp FLOWSPEC]
[-d FLOWSPEC | --dccp FLOWSPEC]
[-s FLOWSPEC | --sctp FLOWSPEC [FLOWSPEC ...]]
[-k FLOWSPEC | --quic FLOWSPEC [FLOWSPEC ...]]
[-q | --quiet] [! | --verbose]
FLOWSPEC := outgoing_frame_rate:outgoing_frame_size:incoming_frame_rate:incoming_frame_size:option:...
netperfmeter [-h | --help]
netperfmeter [-v | --version]

DESCRIPTION
netperfmeter is a network performance meter for the TCP, MPTCP, UDP, DCCP and SCTP transport protocols over IPv4 and IPv6. It simultaneously transmits bidirectional flows to an endpoint and measures the resulting flow bandwidths and QoS. The results can be written as scalar files (summary of the run) and vector files (details per frame). These files can be processed further, e.g. for analysis and plotting of the results.

ARGUMENTS
The following arguments can to be provided:

local_port
    The port number for the passive side's data socket for TCP, UDP, DCCP, SCTP. For MPTCP, the port number will be local_port-1, to allow for both, TCP and MPTCP connections. The port number of the control socket will be local_port+1. Specifying a port number turns NetPerfMeter into passive mode, i.e. it will wait for incoming connections.

remote_endpoint:remote_port
    Specifies the passive endpoint to connect to (number as given for local_port on the passive instance). Specifying remote_endpoint:remote_port turns NetPerfMeter into active mode, i.e. it will connect to the specified remote endpoint.

x | --control-over-sctp
    On the passive side, this option enables accepting control connections via SCTP (default). It enables SCTP in addition to other protocols for the control transport. On the active side, this option uses SCTP for the control connection to the passive side. This is the default, but may cause connection problems in restricted networks or due to NAT traversal.

-X | --no-control-over-sctp
    On the passive side, this option disables incoming control connections via SCTP.

-y | --control-over-tcp | -Y | --no-control-over-tcp
    On the passive side, this option enables accepting control connections via TCP (default). It enables TCP in addition to other protocols for the control transport. Note: By default, both -- SCTP and TCP -- are enabled on the passive side. On the active side, this option uses TCP for the control connection to the passive side. This may be necessary for NAT traversal or due to restrictive firewalls.

-Y | --no-control-over-tcp
    On the passive side, this option disables incoming control connections via TCP. This implicitly also disables control connections over MPTCP.

-w | --control-over-mptcp
    On the passive side, this option enables accepting control connections via MPTCP. This implicitly also enables control connections over TCP! On the active side, this option uses MPTCP for the control connection to the passive side.

-W | --no-control-over-tcp
    On the passive side, this option disables incoming control connections via MPTCP. However, it does not deactivate TCP!

-L address[,address,...] | --local address[,address,...]
    Specifies address(es) of the local *data* endpoint. For TCP, UDP and DCCP, only the first address is used! On an active node, this option applies to the following flows, i.e. it must be set before specifying a flow!

-l address[,address,...] | --controllocal address[,address,...]
    Specifies address(es) of the local *control* endpoint (SCTP or TCP). For TCP, only the first address is used!

-K key_file | --tls-key key_file
    Specifies the TLS key file for QUIC authentication. This option is used by the passive side.

-J certificate_file | --tls-cert certificate_file
    Specifies the TLS certificate file for QUIC authentication. This option is used by the passive side. The certificate file must correspond to the key file provided by --tls-key. The certificate must be for server usage (X.509 Extended Key Usage: TLS Web Server Authentication).

-I ca_certificate_file | --tls-ca ca_certificate_file
    Specifies the TLS root CA certificate file for QUIC authentication.

-H hostname_file | --tls-hostname hostname
    Specifies the TLS certificate hostname for QUIC authentication. It is used by the active side. The hostname must match the remote (i.e. passive side's) hostname, as provided by the passide side's TLS certificate, to allow for hostname verification. As alternative, it is possible to add the IP addresses into the X.509 SubjectAltName of its certificate.

--6 | --v6only
    Use sockets with IPv6 only (by setting IPV6_V6ONLY socket option).

--display
    Display live I/O statistics, updated every second. This is enabled by default.

--nodisplay
    No not display live I/O statistics. This is useful for running NetPerfMeter in background as a service.

-o bytes | --sndbuf bytes
    Sets the sender buffer size to the given number of bytes.

-i bytes | --rcvbuf bytes
    Sets the receiver buffer size to the given number of bytes.

-N count | --count count
    Add all specified flows the given number of times. That is, given a count of 5, each specified flow will be added 5 times. This allows one to easily create multiple flows with the same parameters.

-T seconds | --runtime seconds
    Specifies the measurement runtime in seconds. After the given time span, NetPerfMeter will finish the measurement.

-C configuration_file | --Ar -config -configuration_file
    Specifies the name of the configuration file to write. The configuration file will contain the used flow parameters.

-S scalar_file_pattern | --scalar scalar_file_pattern
    Specifies the name pattern of the scalar files to write. If the suffix of this name is .bz2, the file will be BZip2-compressed on the fly. The scalar name is automatically extended to name the flow scalar files by adding -<active|passive>-<flow_id>-<stream_id> before the suffix. For example for scalar.vec.bz2, the name of the scalar file for flow 5, stream 2 on the active node will be scalar-active-00000005-0002.vec.bz2.

-V vector_file_pattern | --vector vector_file_pattern
    Specifies the name pattern of the vector files to write. If the suffix of this name is .bz2, the file will be 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. For example for vector.vec.bz2, the name of the vector file for flow 5, stream 2 on the passive node will be vector-passive-00000005-0002.vec.bz2.

-A description | --activenodename description
    Sets a textual description of the active node (e.g. Client).

-P description | --passivenodename description
    Sets a textual description of the passive node (e.g. Server).

--loglevel level
    Sets the minimum logging level to the provided value: 0=trace, 1=debug, 2=info, 3=warning, 4=error, 5=fatal. Default: 2 (info).

--logcolor on|off
    Enables (on) or disables (off) the usage of ANSI color escape sequences to colorise the log output according to its level. Default: on.

--logappend file
    Sets a file name for appending the log output to. If a log file is set, no log output is made to the console (stderr). Otherwise, all log output will be written to the console.

--logfile file
    Sets a file name for writing the log output to. Existing content is truncated. If a log file is set, no log output is made to the console (stderr). Otherwise, all log output will be written to the console.

-q | --quiet
    Sets the logging level to 4 (error).

! | --verbose
    Sets the logging level to 0 (trace).

-t FLOWSPEC | --tcp FLOWSPEC
    Establish a new TCP connection. The flow of this connection must be specified by a FLOWSPEC specification as following parameter. For backwards compatibility, the option cmt=mptcp creates an MPTCP connection instead of a TCP connection.

-m FLOWSPEC | --mptcp FLOWSPEC
    Establish a new MPTCP connection. The flow of this connection must be specified by a FLOWSPEC specification as following parameter. Note: DCCP is not available on all platforms, yet. Currently, only Linux provides MPTCP in its official kernel.

-u FLOWSPEC | --udp FLOWSPEC
    Establish a new UDP connection. The flow of this connection must be specified by a FLOWSPEC specification as following parameter.

-d FLOWSPEC | --dccp FLOWSPEC
    Establish a new DCCP connection. The flow of this connection must be specified by a FLOWSPEC specification as following parameter. Note: DCCP is not available on all platforms, yet. Currently, only Linux provides DCCP in its official kernel.

-s FLOWSPEC | --sctp FLOWSPEC [FLOWSPEC ...]
    Establish a new SCTP association. The streams of this association must be specified by one or more FLOWSPEC specifications as following parameters.

-k FLOWSPEC | --quic FLOWSPEC [FLOWSPEC ...]
    Establish a new QUIC connection. The streams of this connection must be specified by one or more FLOWSPEC specifications as following parameters.

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) 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.

    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.

    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. passive node to active node). See outgoing_frame_size for details.

    Random distribution:
        Frame rate and frame size may be distributed randomly, using different random distributions. A new random value is drawn for the next frame send time or next frame size. The following distributions are supported:

        const<value>
            Constant, i.e. always the same. Example: a frame rate const1000 means that all frames have a size of 1000 bytes.

        uniform<a>,<b>
            Uniform distribution from the interval [a,b). Example: uniform900,1100.

        exp<mean>
            Exponential distribution with mean <mean>. Example: exp1000.

        pareto<location>,<shape>
            Pareto distribution with location <location> and shape <shape>. Example: pareto0.166667,1.5.

        normal<mean>,<stddev>
            Normal distribution with mean <mean> and standard deviation <stddev>. Example: normal1000,500. Note that normal distribution may result in negative values, which may be ignored (frame size) or interpreted as saturated traffic (frame rate). Use truncnormal to prevent negative values.

        truncnormal<mean>,<stddev>
            Truncated normal distribution with mean <mean> and standard deviation <stddev>, i.e. normal distribution without negative values. Example: truncnormal1000,500.

    Possible flow 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!

        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!

        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).

        rtx_trials=Trials
            Sets the retransmission trials for unreliable messages (SCTP only).

        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.

        nodelay=on|off
            Deactivate Nagle algorithm (TCP and SCTP only; default: off).

        debug=on|off
            Set debug mode for flow (default: off). Note: this is for debugging and testing NetPerfMeter only; it (usually) has no function!

        v6only
            Use socket with IPv6 only (by setting IPV6_V6ONLY socket option).

        cc=name
            Set congestion control name (TCP and MPTCP for Linux only).

        cmt=off|cmt|cmtrpv1|cmtrpv2|like-mptcp|mptcp-like|mptcp
            Configures usage of Concurrent Multipath Transfer (CMT): off (turned off; default), cmt (independent paths), cmtrpv1 (CMT/RPv1), cmtrpv1 (CMT/RPv2), mptcp/like-mptcp/mptcp-like (MPTCP), 0-255 (custom value). Currently only supported by CMT-SCTP on FreeBSD systems and MPTCP on Linux systems. Note: CMT for MPTCP always uses MPTCP congestion control.

-h | --help
    Prints command help.

-v | --version
    Prints program version.

EXIT STATUS
The netperfmeter tool exits with 0 on success, and >0 in case of an error.

EXAMPLES
Some netperfmeter usage examples:

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

netperfmeter 172.31.33.2:9000 -config=output.config -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.31.33.2, port 9000. Frames will be segmented into messages of up to 4096 bytes. Write configuration to output-*.config. 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.

netperfmeter 172.31.33.2:9000 -control-over-tcp -tcp const2:const1000
    Start in active mode, i.e. establish connection to 172.31.33.2, port 9000. The control connection uses TCP instead of SCTP.

netperfmeter 172.31.33.2:9000 -sctp const0:const0:uniform20,30:uniform900,1100
    SCTP traffic with some variation.

netperfmeter 172.31.33.2:9000 -udp const0:const0:const25:const2500:onoff=+pareto0.166667,1.5,+pareto0.166667,1.5,repeat
    Some on-off background traffic with Pareto distribution.

netperfmeter 9000 -tls-key my-server.key -tls-cert my-server.crt -tls-ca my-ca.crt
    Start in passive mode, with TLS setup for QUIC. See https://www.nntb.no/~dreibh/netperfmeter/#quic-communication for details about QUIC usage!

netperfmeter 172.31.33.2:9000 -tls-hostname my-server.domain -tls-ca my-ca.crt -quic const10:const128:const25:const1200
    Start in active mode, i.e. establish connection to 172.31.33.2, port 9000. Set TLS server name of 172.31.33.2 for QUIC to my-server.domain. See https://www.nntb.no/~dreibh/netperfmeter/#quic-communication for details about QUIC usage!

netperfmeter -version
    Shows the version.

netperfmeter -help
    Shows usage help.

SEE ALSO
combinesummaries(1), createsummary(1), netperfmeter(1), netperfmeter-module-loader(1), plot-netperfmeter-results(1), runtimeestimator(1)

NOTES
This program is part of NetPerfMeter. The latest version of NetPerfMeter can be found on the NetPerfMeter Homepage at NetPerfMeter Homepage: https://www.nntb.no/~dreibh/netperfmeter/.

AUTHORS
Thomas Dreibholz, Homepage: https://www.nntb.no/~dreibh