NUTTCP(8)

📦
version 8.2.2.rpm · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 nuttcp — network performance measurement tool 💅

okay so bestie, you're reading NUTTCP(8) — the Under Construction edition, no cap — and it's literally the manual for nuttcp, the tool that tells you how fast your network actually is. Buckle up, it's giving ✨encyclopedia✨ but make it fun. 🌈

🌸 NAME 🌸

nuttcp — network performance measurement tool 🫶

✨ SYNOPSIS ✨

nutttcp -h
nutttcp -V
nutttcp -t [ -bdDsuv ] [ -cdscp_value ] [ -lbuffer_len ] [ -nnum_bufs ]
          [ -wwindow_size ] [ -wsserver_window ] [ -wb ]
          [ -pdata_port ] [ -Pcontrol_port ]
          [ -Nnum_streams ] [ -F ] [ -Rxmit_rate_limit [m|g] ]
          [ -Txmit_timeout [m] ] host [ < input ]
nutttcp -r [ -bBdsuv ] [ -cdscp_value ] [ -lbuffer_len ] [ -nnum_bufs ]
          [ -wwindow_size ] [ -wsserver_window ] [ -wb ]
          [ -pdata_port ] [ -Pcontrol_port ]
          [ -Nnum_streams ] [ -F ] [ -Rxmit_rate_limit [m|g] ]
          [ -Txmit_timeout [m] ] [ host ] [ > output ]
nutttcp -S [ -Pcontrol_port ]
nutttcp -1 [ -Pcontrol_port ]
heads up: the flag letters above are glued to their values (-cdscp_value, -lbuffer_len, -wwindow_size, -pdata_port, -Pcontrol_port, -Nnum_streams, -Rxmit_rate_limit, -Txmit_timeout) — that's how they're written, so don't go adding spaces and then being confused. 💀

👑 DESCRIPTION 👑

nutttcp is a network performance measurement tool made for network and system managers. Its most basic whole entire job is figuring out the raw TCP (or UDP) network layer throughput by yeeting memory buffers from a source system across an interconnecting network to a destination system. You can do that either by transferring data for a specified time interval, or by transferring a specified number of bytes — dealer's choice, bestie. 🎀

And it's not just Mbps and done, no ma'am. On top of reporting the achieved network throughput in Mbps, nutttcp also hands you extra useful info about the transfer: user, system, and wall-clock time, transmitter and receiver CPU utilization, and loss percentage (that last one is for UDP transfers). Obsessed. 🔥

🦋 the lore (history era) 🦋

nutttcp is based on nttcp, which was itself an enhancement by someone at Silicon Graphics (SGI) on the original ttcp. And ttcp was written by Mike Muuss at BRL sometime before December 1984 — the whole point being to compare the performance of TCP stacks by U.C. Berkeley and BBN so DARPA could decide which version to put in the first BSD Unix release. Literally historic. 👑

nutttcp has several useful features beyond those of the basic ttcp/nttcp, like:

  • a server mode 🖥️
  • rate limiting 🚦
  • multiple parallel streams 🌊🌊🌊
  • timer based usage ⏱️

More recent changes include IPv6 support, IPv4 multicast, and the ability to set the maximum segment size or TOS/DSCP bits. And nutttcp is continuing to evolve to meet new requirements that arise and to add desired new features — she's growing, okay? 🌱

It has been successfully built and run on a variety of Solaris, SGI, and PPC/X86 Linux systems, and should probably work fine on most flavors of Unix. It has also been used successfully on various versions of the Windows operating system. Versatile queen. 💅

🎀 the two modes of operation 🎀

There are two basic modes of operation for nutttcp. Let's break them down, bestie:

🌸 1. classic transmitter/receiver mode

The original or classic mode is the transmitter/receiver mode, which is also the way the original ttcp and nttcp worked. In this mode:

  1. a receiver is first initiated on the destination host using "nuttcp -r", and then
  2. a transmitter must be started on the source host using "nuttcp -t".
vibe check: this mode is somewhat deprecated and is no longer recommended for general use. It's giving legacy energy. 🫠

💖 2. client/server mode (the preferred one)

The preferred and recommended mode of operation for nutttcp is the new client/server mode. With this mode:

  1. a server is first started on one system using "nuttcp -S" (or "nuttcp -1"), and then
  2. a client may either transmit data to (using "nuttcp -t") or receive data from (using "nuttcp -r") the server system.

All the information provided by nutttcp is reported by the client, including the information from the server, thus providing a full snapshot of both the transmitter and receiver ends of the data transfer. Full picture, no crumbs. 📸

🌈 running the server (the tea) 🌈

The server may be started by a normal, non-privileged user by issuing either a "nuttcp -S" or a "nuttcp -1" command. However, the optimal and recommended method of running a server is to run "nuttcp -S" via the inetd/xinetd daemon. 🧚

This method has several significant advantages, including:

  • being more robust 💪
  • allowing multiple simultaneous connections 👯
  • providing for access control over who is allowed to use the nutttcp server via the hosts.allow (and hosts.deny) file 🔐

By default, the nutttcp server listens for commands on port 5000, and the actual nutttcp data transfers take place on port 5001. Remember those two numbers, bestie, they come up again. ✨

🦄 the host parameter 🦄

The host parameter must be specified for the transmitter, and it provides the host name or IP address of the receiver. But it depends on the mode:

  • In classic transmitter/receiver mode, the host parameter may not be specified for the receiver.
  • In client/server mode, when the client is the receiver, the host parameter specifies the host name or IP address of the transmitter (server).

💾 memory vs disk (the -s situation) 💾

Normally, a nutttcp data transfer is memory-to-memory. However, by using the "-s" option, it is possible to also perform:

  • memory-to-disk 💽
  • disk-to-memory 💽
  • disk-to-disk 💽

Using the "-s" option with the transmitter will cause nutttcp to read its data from the standard input instead of using a prefabricated memory buffer, while using the "-s" option on the receiver causes nutttcp to write its data to standard output. All these types of data transfers are possible with the classic transmitter/receiver mode.

security tea: for security reasons, the "-s" option is disabled on the server, so it is not possible to access the disk on the server side of a data transfer. The server is not your personal file system tour guide, sorry. 🙈

The allowed options to nutttcp are:

💅 OPTIONS 💅

  • -h — Print out a usage statement. Running nutttcp with no arguments will also produce a usage statement. (Little help menu moment. 🫶)
  • -V — Prints the nutttcp version number. The nutttcp version is also printed as part of the normal nutttcp output when the "-v" verbose output is used (but not when using the default brief output). In client/server mode, the version number of both the client and server is identified. So you know exactly who you're talking to. 👀
  • -t — Indicates that this nutttcp is the transmitter. In client/server mode, this means the server specified by the host parameter is the receiver. 📤
  • -r — Indicates that this nutttcp is the receiver. In client/server mode, this means the server specified by the host parameter is the transmitter. 📥
  • -S — Indicates that this nutttcp is the server. The only option that may be specified to the server is the "-P" option, which allows one to change the control port used by the server, but only when the server is started by a normal, non-privileged user. When the server is initiated by inetd/xinetd, the server control port should be specified in the services file. 🖥️✨
  • -1 — Basically the same as the "-S" option, but indicates a one-shot server, i.e. the server exits after the first data transfer initiated by a client. The "-1" option should only be used when the server is started by a normal, non-privileged user. This option will probably rarely need to be used, but can be useful for a quick test and eliminates the possibilty of leaving a non-access controlled nutttcp server running on the system (which can happen when using the "-S" option and forgetting to kill the nutttcp server after finishing a series of tests). 👻 (yes, that typo is in the original, we're preserving the artifact, it's iconic)
  • -b — Produce brief one-line output, which includes the amount of data transferred in MB (1024**2 bytes), the time interval in seconds, the TCP (or UDP) network throughput in Mbps (millions of bits per second), the transmitter and/or receiver CPU utilization, and for UDP data transfers also outputs the loss percentage. In client/server mode, most of the printed statistics are from the viewpoint of the receiver. This is the default output format. 🎀
  • -B — This option is only valid for the receiver, and forces the receiver to read a full buffer (as specified by the "-l" buffer length option) from the network. It is mainly intended to be used with the "-s" option to only output full buffers to standard output (e.g. for use with tar). It is also implicitly set whenever the number of streams as specified by the "-N" option is greater than 1. This option is not passed to the server. 📦
  • -d — For TCP data transfers, sets the SO_DEBUG option on the data socket. This option is not passed to the server. It is a rarely used option which may possibly be removed or renamed in a future version of nutttcp. 🐛
  • -D — This option is only valid for the transmitter, and only for TCP data transfers, in which case it sets the TCP_NODELAY option on the data socket, which turns off the Nagle algorithm causing data packets to be sent as soon as possible without introducing any unnecessary delays. This option is not passed to the server. It is a rarely used option which may possibly be removed or renamed in a future version of nutttcp. 🚀
  • -s — Setting the "-s" option causes nutttcp to either read its data from standard input rather than using prefabricated memory buffers (for "nuttcp -t"), or to write its data out to standard output (for "nuttcp -r"). The "-s" option is disabled for security reasons on the server. 🚫💽
  • -u — Use UDP for the data transfer instead of the default of TCP. 📡
  • -v — Verbose output that provides some additional information related to the data transfer. In client/server mode, the server is always verbose (implicit "-v" option), but the client controls the extent and type of output via the "-v" and "-b" options. 🗣️
  • -cdscp_value — Sets the socket option to support COS. Either takes a dscp value or with the t|T modifier it takes the full TOS field. ✨
  • -lbuffer_len — Length of the network write/read buffer in bytes for the transmitter/receiver. It defaults to 64 KB (65536) for TCP data transfers and to 8 KB (8192) for UDP. For client/server mode, it sets both the client and server buffer lengths. 🧺
  • -nnum_bufs — Specifies the number of source buffers written to the network (default is unlimited), and is ignored by the receiver. For client/server mode, if the client issues a "nuttcp -r" command making it the receiver, this parameter is passed to the server since the server is the transmitter in this case. This parameter is also ignored if the "-s" parameter is specified to the transmitter. 🔢
  • -wwindow_size — indicates the window size in KB of the transmitter (for nuttcp -t) or receiver (for nuttcp -r). actually, to be technically correct, it sets the sender or receiver TCP socket buffer size, which then effectively sets the window size. For client/server mode, both the transmitter and receiver window sizes are set. The default window size is architecture and system dependent. heads up: recent Linux systems, out of a misguided desire to be helpful, double whatever window size is actually specified by the user (this is not a bug with nuttcp but a bug/feature of the Linux kernel). Also, with these Linux systems, the actual window size that's used on the intervening network, as observed with tcpdump, is greater than the requested window size, but less than the doubled value set by Linux. 😭
  • -wsserver_window — for client/server mode, the -ws option provides a mechanism for setting a different window size on the server than the client window size as specified with the -w option. ✨
  • -wb — normally, to conserve memory, the transmitter only sets the TCP send socket buffer size and the receiver only sets the TCP receive socket buffer size. However, if the -wb option is used, the transmitter will also set the TCP receive socket buffer size and the receiver will also set the TCP send socket buffer size. Under normal circumstances, this should never be necessary. This option was implemented because certain early braindead Solaris 2.8 systems would not properly set the TCP window size unless both the TCP send and receive socket buffer sizes were set (later Solaris 2.8 systems have corrected this deficiency). Thus the 'b' in this option can stand either for "braindead" or "both". 💀
  • -pdata_port — port number used for the data connection, which defaults to port 5001. If multiple streams are specified with the -N option, the -p option specifies the starting port number for the data connection. for example, if four streams are specified using the default data connection port number, nuttcp will use ports 5001, 5002, 5003, and 5004 for the four TCP (or UDP) connections used to perform the data transfer. 🫶
  • -Pcontrol_port — for client/server mode, specifies the port number used for the control connection between the client and server, and defaults to port 5000. On the server side, the -P option should only be used when the server is started manually by the user. If the server is started by inetd/xinetd (the preferred method), the control connection must be specified by adding a nuttcp entry to the services file. 👑
  • -Nnum_streams — specifies the number of parallel TCP (or UDP) data streams to be used for the data transfer, with the default being a single data stream. The maximum number of parallel data streams that can be used is 128. If the number of streams is greater than one, the -B option is implicitly set. The current implementation does not fork off separate processes for each data stream, so specifying multiple streams on an SMP machine will not take advantage of its multiple processors. Of course it is always possible to run multiple nuttcp commands in parallel on an SMP system to determine if there is any advantage to running on multiple processors. This is especially simple to do when running in client/server mode when the server is started from the inetd/xinetd daemon. When running multiple nuttcp commands in parallel, the -T transmitter timeout option may be used to insure that all the nuttcp commands finish at approximately the same time. 🔥
  • -F — this flips the connect, which you don't need to understand. What you need to know is that if you are behind a NAT, or a port block, this allows you to do a receive by doing -r -F. 💅
  • -Rxmit_rate_limit[m|g] — the transmitter rate limit throttles the speed at which the transmitter sends data to the network, and by default is in Kbps, although the m or g suffix may be used to specify Mbps or Gbps. This option may be used with either TCP or UDP data streams. Because of the way this option is currently implemented, it will consume all the available CPU on the transmitter side of the connection so the %TX stats are not meaningful when using the rate limit option. By default the rate limit is applied to the average rate of the data transfer in real time, and not in CPU time, so if nuttcp is switched out of the processor for any reason, when it is switched back in, it is possible that the instantaneous rate may momentarily exceed the specified value. There is an i qualifier to the rate limit option (specified as -Ri) that will restrict the instantaneous rate at any given point in time to the specified value, although in this case the final rate reported by nuttcp may be less than the specified value since nuttcp won't attempt to catch up if other processes gain control of the CPU. The default is no rate limit. Note another way to throttle the throughput of TCP data streams is to reduce the window size. 🧚
  • -Txmit_time_limit[m] — limits the amount of time that the transmitter will send data to the specified number of seconds, or number of minutes if the m suffix is used. Normally a data transfer will either specify a fixed amount of data to send using the -n option, or a fixed period of time to send using the -T option. However, if both the -n and -T options are used, the data transfer will be stopped by whichever option takes affect first. The default is a 10 second time limit for the data transfer. ⏳

🚧 USAGE 🚧

Under Construction

For now, consult the README file for basic usage guidelines.

🧪 EXAMPLES 🧪

Under Construction

For now, see the examples.txt file for some examples of using nuttcp.

👀 SEE ALSO 👀

💖 AUTHORS 💖

Developed by Bill Fink based on nttcp which in turn was an enhancement of the original ttcp developed by Mike Muuss at BRL. IPv6 capability and some other fixes and enhancements contributed by Rob Scott. Many useful suggestions and testing performed by Phil Dykstra and others.

The current version is available via anonymous ftp from:

ftp://ftp.lcp.nrl.navy.mil/pub/nuttcp/

The authors can be reached at nuttcp@lcp.nrl.navy.mil.

🐛 BUGS 🐛

Please send bug reports to nuttcp-bugs@lcp.nrl.navy.mil.

and that's the whole vibe! 💖 this page is from nuttcp-v8.2.2, dated 3 February 2007, and it lives in NUTTCP(8). periodt. 👑

📦 where this page comes from