1NUTTCP(8) Under Construction NUTTCP(8)
2
6 nuttcp - network performance measurement tool
7
9 nuttcp -h
10 nuttcp -V
11 nuttcp -t [ -bdDsuv ] [ -cdscp_value ] [ -lbuffer_len ] [ -nnum_bufs ]
12 [ -wwindow_size ] [ -wsserver_window ] [ -wb ]
13 [ -pdata_port ] [ -Pcontrol_port ]
14 [ -Nnum_streams ] [ -Rxmit_rate_limit [m|g] ]
15 [ -Txmit_timeout [m] ] host [ < input ]
16 nuttcp -r [ -bBdsuv ] [ -cdscp_value ] [ -lbuffer_len ] [ -nnum_bufs ]
17 [ -wwindow_size ] [ -wsserver_window ] [ -wb ]
18 [ -pdata_port ] [ -Pcontrol_port ]
19 [ -Nnum_streams ] [ -Rxmit_rate_limit [m|g] ]
20 [ -Txmit_timeout [m] ] [ host ] [ > output ]
21 nuttcp -S [ -Pcontrol_port ]
22 nuttcp -1 [ -Pcontrol_port ]
23
25 nuttcp is a network performance measurement tool intended for use by
26 network and system managers. Its most basic usage is to determine the
27 raw TCP (or UDP) network layer throughput by transferring memory buf‐
28 fers from a source system across an interconnecting network to a desti‐
29 nation system, either transferring data for a specified time interval,
30 or alternatively transferring a specified number of bytes. In addition
31 to reporting the achieved network throughput in Mbps, nuttcp also pro‐
32 vides additional useful information related to the data transfer such
33 as user, system, and wall-clock time, transmitter and receiver CPU uti‐
34 lization, and loss percentage (for UDP transfers).
35 nuttcp is based on nttcp, which in turn was an enhancement by someone
37 at Silicon Graphics (SGI) on the original ttcp, which was written by
38 Mike Muuss at BRL sometime before December 1984, to compare the perfor‐
39 mance of TCP stacks by U.C. Berkeley and BBN to help DARPA decide which
40 version to place in the first BSD Unix release. nuttcp has several
41 useful features beyond those of the basic ttcp/nttcp, such as a server
42 mode, rate limiting, multiple parallel streams, and timer based usage.
43 More recent changes include IPv6 support, IPv4 multicast, and the abil‐
44 ity to set the maximum segment size or TOS/DSCP bits. nuttcp is con‐
45 tinuing to evolve to meet new requirements that arise and to add
46 desired new features. nuttcp has been successfully built and run on a
47 variety of Solaris, SGI, and PPC/X86 Linux systems, and should probably
48 work fine on most flavors of Unix. It has also been used successfully
49 on various versions of the Windows operating system.
50 There are two basic modes of operation for nuttcp. The original or
52 classic mode is the transmitter/receiver mode, which is also the way
53 the original ttcp and nttcp worked. In this mode, a receiver is first
54 initiated on the destination host using "nuttcp -r", and then a trans‐
55 mitter must be started on the source host using "nuttcp -t". This mode
56 is somewhat deprecated and is no longer recommended for general use.
57 The preferred and recommended mode of operation for nuttcp is the new
58 client/server mode. With this mode, a server is first started on one
59 system using "nuttcp -S" (or "nuttcp -1"), and then a client may either
60 transmit data to (using "nuttcp -t") or receive data from (using
61 "nuttcp -r") the server system. All the information provided by nuttcp
62 is reported by the client, including the information from the server,
63 thus providing a full snapshot of both the transmitter and receiver
64 ends of the data transfer.
65 The server may be started by a normal, non-privileged user by issuing
67 either a "nuttcp -S" or a "nuttcp -1" command. However, the optimal
68 and recommended method of running a server is to run "nuttcp -S" via
69 the inetd/xinetd daemon. This method has several significant advan‐
70 tages, including being more robust, allowing multiple simultaneous con‐
71 nections, and providing for access control over who is allowed to use
72 the nuttcp server via the hosts.allow (and hosts.deny) file. By
73 default, the nuttcp server listens for commands on port 5000, and the
74 actual nuttcp data transfers take place on port 5001.
75 The host parameter must be specified for the transmitter, and provides
77 the host name or IP address of the receiver. In classic transmit‐
78 ter/receiver mode, the host parameter may not be specified for the
79 receiver. In client/server mode, when the client is the receiver, the
80 host parameter specifies the host name or IP address of the transmitter
81 (server).
82 Normally, a nuttcp data transfer is memory-to-memory. However, by
84 using the "-s" option, it is possible to also perform memory-to-disk,
85 disk-to-memory, and disk-to-disk data transfers. Using the "-s" option
86 with the transmitter will cause nuttcp to read its data from the stan‐
87 dard input instead of using a prefabricated memory buffer, while using
88 the "-s" option on the receiver causes nuttcp to write its data to
89 standard output. All these types of data transfers are possible with
90 the classic transmitter/receiver mode. For security reasons, the "-s"
91 option is disabled on the server, so it is not possible to access the
92 disk on the server side of a data transfer.
93 The allowed options to nuttcp are:
95
97 -h Print out a usage statement. Running nuttcp with no arguments
98 will also produce a usage statement.
99 -V Prints the nuttcp version number. The nuttcp version is also
101 printed as part of the normal nuttcp output when the "-v" ver‐
102 bose output is used (but not when using the default brief out‐
103 put). In client/server mode, the version number of both the
104 client and server is identified.
105 -t Indicates that this nuttcp is the transmitter. In client/server
107 mode, this means the server specified by the host parameter is
108 the receiver.
109 -r Indicates that this nuttcp is the receiver. In client/server
111 mode, this means the server specified by the host parameter is
112 the transmitter.
113 -S Indicates that this nuttcp is the server. The only option that
115 may be specified to the server is the "-P" option, which allows
116 one to change the control port used by the server, but only when
117 the server is started by a normal, non-privileged user. When
118 the server is initiated by inetd/xinetd, the server control port
119 should be specified in the services file.
120 -1 Basically the same as the "-S" option, but indicates a one-shot
122 server, i.e. the server exits after the first data transfer ini‐
123 tiated by a client. The "-1" option should only be used when
124 the server is started by a normal, non-privileged user. This
125 option will probably rarely need to be used, but can be useful
126 for a quick test and eliminates the possibilty of leaving a non-
127 access controlled nuttcp server running on the system (which can
128 happen when using the "-S" option and forgetting to kill the
129 nuttcp server after finishing a series of tests).
130 -b Produce brief one-line output, which includes the amount of data
132 transferred in MB (1024**2 bytes), the time interval in seconds,
133 the TCP (or UDP) network throughput in Mbps (millions of bits
134 per second), the transmitter and/or receiver CPU utilization,
135 and for UDP data transfers also outputs the loss percentage. In
136 client/server mode, most of the printed statistics are from the
137 viewpoint of the receiver. This is the default output format.
138 -B This option is only valid for the receiver, and forces the
140 receiver to read a full buffer (as specified by the "-l" buffer
141 length option) from the network. It is mainly intended to be
142 used with the "-s" option to only output full buffers to stan‐
143 dard output (e.g. for use with tar). It is also implicitly set
144 whenever the number of streams as specified by the "-N" option
145 is greater than 1. This option is not passed to the server.
146 -d For TCP data transfers, sets the SO_DEBUG option on the data
148 socket. This option is not passed to the server. It is a
149 rarely used option which may possibly be removed or renamed in a
150 future version of nuttcp.
151 -D This option is only valid for the transmitter, and only for TCP
153 data transfers, in which case it sets the TCP_NODELAY option on
154 the data socket, which turns off the Nagle algorithm causing
155 data packets to be sent as soon as possible without introducing
156 any unnecessary delays. This option is not passed to the
157 server. It is a rarely used option which may possibly be
158 removed or renamed in a future version of nuttcp.
159 -s Setting the "-s" option causes nuttcp to either read its data
161 from standard input rather than using prefabricated memory buf‐
162 fers (for "nuttcp -t"), or to write its data out to standard
163 output (for "nuttcp -r"). The "-s" option is disabled for secu‐
164 rity reasons on the server.
165 -u Use UDP for the data transfer instead of the default of TCP.
167 -v Verbose output that provides some additional information related
169 to the data transfer. In client/server mode, the server is
170 always verbose (implicit "-v" option), but the client controls
171 the extent and type of output via the "-v" and "-b" options.
172 -cdscp_value
174 Sets the socket option to support COS. Either takes a dscp
175 value or with the t|T modifier it takes the full TOS field.
176 -lbuffer_len
178 Length of the network write/read buffer in bytes for the trans‐
179 mitter/receiver. It defaults to 64 KB (65536) for TCP data
180 transfers and to 8 KB (8192) for UDP. For client/server mode,
181 it sets both the client and server buffer lengths.
182 -nnum_bufs
184 Specifies the number of source buffers written to the network
185 (default is unlimited), and is ignored by the receiver. For
186 client/server mode, if the client issues a "nuttcp -r" command
187 making it the receiver, this parameter is passed to the server
188 since the server is the transmitter in this case. This parame‐
189 ter is also ignored if the "-s" parameter is specified to the
190 transmitter.
191 -wwindow_size
193 Indicates the window size in KB of the transmitter (for "nuttcp
194 -t") or receiver (for "nuttcp -r"). Actually, to be technically
195 correct, it sets the sender or receiver TCP socket buffer size,
196 which then effectively sets the window size. For client/server
197 mode, both the transmitter and receiver window sizes are set.
198 The default window size is architecture and system dependent.
199 Note recent Linux systems, out of a misguided desire to be help‐
200 ful, double whatever window size is actually specified by the
201 user (this is not a bug with nuttcp but a bug/feature of the
202 Linux kernel). Also, with these Linux systems, the actual win‐
203 dow size that's used on the intervening network, as observed
204 with tcpdump, is greater than the requested window size, but
205 less than the doubled value set by Linux.
206 -wsserver_window
208 For client/server mode, the "-ws" option provides a mechanism
209 for setting a different window size on the server than the
210 client window size as specified with the "-w" option.
211 -wb Normally, to conserve memory, the transmitter only sets the TCP
213 send socket buffer size and the receiver only sets the TCP
214 receive socket buffer size. However, if the "-wb" option is
215 used, the transmitter will also set the TCP receive socket buf‐
216 fer size and the receiver will also set the TCP send socket buf‐
217 fer size. Under normal circumstances, this should never be nec‐
218 essary. This option was implemented because certain early
219 braindead Solaris 2.8 systems would not properly set the TCP
220 window size unless both the TCP send and receive socket buffer
221 sizes were set (later Solaris 2.8 systems have corrected this
222 deficiency). Thus the 'b' in this option can stand either for
223 "braindead" or "both".
224 -pdata_port
226 Port number used for the data connection, which defaults to port
227 5001. If multiple streams are specified with the "-N" option,
228 the "-p" option specifies the starting port number for the data
229 connection. For example, if four streams are specified using
230 the default data connection port number, nuttcp will use ports
231 5001, 5002, 5003, and 5004 for the four TCP (or UDP) connections
232 used to perform the data transfer.
233 -Pcontrol_port
235 For client/server mode, specifies the port number used for the
236 control connection between the client and server, and defaults
237 to port 5000. On the server side, the "-P" option should only
238 be used when the server is started manually by the user. If the
239 server is started by inetd/xinetd (the preferred method), the
240 control connection must be specified by adding a nuttcp entry to
241 the services file.
242 -Nnum_streams
244 Species the number of parallel TCP (or UDP) data streams to be
245 used for the data transfer, with the default being a single data
246 stream. The maximum number of parallel data streams that can be
247 used is 128. If the number of streams is greater than one, the
248 "-B" option is implicitly set. The current implementation does
249 not fork off separate processes for each data stream, so speci‐
250 fying multiple streams on an SMP machine will not take advantage
251 of its multiple processors. Of course it is always possible to
252 run multiple nuttcp commands in parallel on an SMP system to
253 determine if there is any advantage to running on multiple pro‐
254 cessors. This is especially simple to do when running in
255 client/server mode when the server is started from the
256 inetd/xinetd daemon. When running multiple nuttcp commands in
257 parallel, the "-T" transmitter timeout option may be used to
258 insure that all the nuttcp commands finish at approximately the
259 same time.
260 -Rxmit_rate_limit[m|g]
262 The transmitter rate limit throttles the speed at which the
263 transmitter sends data to the network, and by default is in
264 Kbps, although the 'm' or 'g' suffix may be used to specify Mbps
265 or Gbps. This option may be used with either TCP or UDP data
266 streams. Because of the way this option is currently imple‐
267 mented, it will consume all the available CPU on the transmitter
268 side of the connection so the "%TX" stats are not meaningful
269 when using the rate limit option. By default the rate limit is
270 applied to the average rate of the data transfer in real time,
271 and not in CPU time, so if nuttcp is switched out of the proces‐
272 sor for any reason, when it is switched back in, it is possible
273 that the instantaneous rate may momentarily exceed the specified
274 value. There is an 'i' qualifier to the rate limit option
275 (specified as "-Ri") that will restrict the instantaneous rate
276 at any given point in time to the specified value, although in
277 this case the final rate reported by nuttcp may be less than the
278 specified value since nuttcp won't attempt to catch up if other
279 processes gain control of the CPU. The default is no rate
280 limit. Note another way to throttle the throughput of TCP data
281 streams is to reduce the window size.
282 -Txmit_time_limit[m]
284 Limits the amount of time that the transmitter will send data to
285 the specified number of seconds, or number of minutes if the 'm'
286 suffix is used. Normally a data transfer will either specify a
287 fixed amount of data to send using the "-n" option, or a fixed
288 period of time to send using the "-T" option. However, if both
289 the "-n" and "-T" options are used, the data transfer will be
290 stopped by whichever option takes affect first. The default is
291 a 10 second time limit for the data transfer.
292
294 Under Construction
295 For now, consult the README file for basic usage guidelines.
297
299 Under Construction
300 For now, see the examples.txt file for some examples of using nuttcp.
302
304 ping(8), traceroute(8), tracepath(8), pathchar(8), netstat(1),
305 mtrace(8)
306
308 Developed by Bill Fink based on nttcp which in turn was an enhancement
309 of the original ttcp developed by Mike Muuss at BRL. IPv6 capability
310 and some other fixes and enhancements contributed by Rob Scott. Many
311 useful suggestions and testing performed by Phil Dykstra and others.
312 The current version is available via anonymous ftp from:
314 ftp://ftp.lcp.nrl.navy.mil/pub/nuttcp/
316 The authors can be reached at nuttcp@lcp.nrl.navy.mil.
318
320 Please send bug reports to nuttcp-bugs@lcp.nrl.navy.mil.
321nuttcp-v6.1.2 3 February 2007 NUTTCP(8)