1 .\"
2 .\" CDDL HEADER START
3 .\"
4 .\" This file and its contents are supplied under the terms of the
5 .\" Common Development and Distribution License ("CDDL"), version 1.0.
6 .\" You may only use this file in accordance with the terms of version
7 .\" 1.0 of the CDDL.
8 .\"
9 .\" A full copy of the text of the CDDL should have accompanied this
10 .\" source. A copy of the CDDL is also available via the Internet at
11 .\" http://www.illumos.org/license/CDDL.
12 .\"
13 .\" CDDL HEADER END
14 .\"
15 .\"
16 .\" Copyright (c) 2016 by Delphix. All rights reserved.
17 .\"
18 .Dd July 5, 2016
19 .Dt CONNSTAT 1M
20 .Os
21 .Sh NAME
22 .Nm connstat
23 .Nd report TCP connection statistics
24 .Sh SYNOPSIS
25 .Nm
26 .Op Fl eLP
27 .Op Fl 4 Ns | Ns Fl 6
28 .Op Fl T Sy d Ns | Ns Sy u
29 .Op Fl F Ar filter
30 .Op Fl i Ar interval
31 .Op Fl c Ar count
32 .Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
33 .Sh DESCRIPTION
34 The
35 .Nm
36 command reports TCP connection statistics in tabular form.
37 Each row of the table represents the activity of one connection.
38 The
39 .Nm
40 command adds virtually no overhead to run as it is aggregating statistics that
41 are always collected in the kernel.
42 .Pp
43 With no arguments,
44 .Nm
45 prints a single report containing all TCP connections, and includes a basic
46 set of fields representing IP address and port information, as well as connection
47 state.
48 The
49 .Fl o
50 flag can be used to specify which fields to display, and other arguments to
51 filter the set of connections included in the output.
52 .Sh OPTIONS
53 The arguments are as follows:
54 .Bl -tag -width ""
55 .It Fl 4 , Fl -ipv4
56 Only displays IPv4 connections.
57 .It Fl 6 , Fl -ipv6
58 Only displays IPv6 connections
59 .It Fl c Ar count , Fl -count Ns = Ns Ar count
60 Print a specified number of reports before exiting.
61 This is used in conjunction with
62 .Fl i .
63 .It Fl e , Fl -established
64 Only display connections that are in state ESTABLISHED.
65 This is equivalent to including
66 .Sy state=ESTABLISHED
67 in the filter argument to the
68 .Fl F
69 option.
70 .It Fl F Ar filter , Fl -filter Ns = Ns Ar filter
71 Only display connections that match the filter argument provided.
72 The format of the filter is:
73 .Pp
74 .Ar field Ns = Ns Ar value Ns Oo , Ns Ar field Ns = Ns Ar value Oc Ns ...
75 .Pp
76 Fields that can currently be filtered are
77 .Ar laddr , Ar lport , Ar raddr , Ar rport , and Ar state .
78 See the
79 .Sx Fields
80 section for a description of these fields.
81 The filter matches a connection if all of the filter elements match, and a
82 field must only appears once in the filter.
83 .It Fl i Ar interval , Fl -interval Ns = Ns Ar interval
84 Specify an output interval in seconds.
85 For each interval, a report containing all connections appropriate given other
86 command-line options is printed.
87 .It Fl L , Fl -no-loopback
88 Exclude connections to the loopback address.
89 .It Fl o Ar fields , Fl -output Ns = Ns Ar fields
90 Restrict the output to the specified comma-delimited list of field names.
91 See the
92 .Sx Fields
93 section for information about possible fields.
94 .It Fl P , Fl -parsable
95 Display using a stable, machine-parsable output format.
96 The
97 .Fl o
98 flag must also be given to specify which fields to output and their order.
99 Each line of output will consist of comma-delimited (,) fields,
100 and no header will be emittted.
101 When also using the
102 .Fl T
103 option, lines indicating the current time will begin with
104 .Dq "= " .
105 See
106 .Sx Example 4
107 for an example of how to process parsable output.
108 .It Fl T Sy d Ns | Ns Sy u , Fl -timestamp Ns = Ns Sy d Ns | Ns Sy u
109 Print a timestamp before each block of output.
110 .Pp
111 Specify
112 .Sy u
113 for a printed representation of the internal representation of time (see
114 .Xr time 2 Ns ).
115 Specify
116 .Sy d
117 for standard date format (see
118 .Xr date 1 Ns ).
119 .El
120 .Ss Fields
121 The following fields are supported.
122 Field names are case insensitive.
123 Unless otherwise indicated, the values of fields that represent a count (e.g.
124 bytes or segments) are cumulative since the connection was established.
125 Some of these fields refer to data segments, which are segments that contain
126 non-zero amount of data.
127 All sizes are in bytes.
128 .Bl -tag -width "inunorderbytes"
129 .It Sy cwnd
130 The size of the local TCP congestion window at this instant.
131 .It Sy inbytes
132 The number of data bytes received.
133 This does not include duplicate bytes received.
134 .It Sy insegs
135 The number of data segments received.
136 This does not include duplicate segments received.
137 .It Sy inunorderbytes
138 The number of data bytes that were received out of order.
139 .It Sy inunordersegs
140 The number of data segments that were received out of order.
141 .It Sy laddr
142 The local IP address.
143 .It Sy lport
144 The local TCP port.
145 .It Sy mss
146 The maximum TCP segment size for this connection.
147 .It Sy outbytes
148 The number of data bytes sent.
149 This does not include retransmitted bytes counted by
150 .Sy retransbytes .
151 .It Sy outsegs
152 The number of data segments sent.
153 This does not include segments containing retransmitted bytes counted by
154 .Sy retranssegs .
155 .It Sy raddr
156 The remote IP address.
157 .It Sy retransbytes
158 The number of data bytes retransmitted.
159 .It Sy retranssegs
160 The number of data segments sent that contained retransmitted bytes.
161 .It Sy rport
162 The remote TCP port.
163 .It Sy rto
164 The current retransmission timeout in milliseconds.
165 .It Sy rtt
166 The current smoothed round-trip time to the peer in microseconds.
167 The smoothed RTT average algorithm used is as described in RFC 6298.
168 .It Sy rttc
169 The number of times that a round-trip sample was added to
170 .Sy rtts .
171 See
172 .Sy rtts
173 for a description of how these two fields can be used together to calculate the
174 average round-trip over a given period.
175 .It Sy rtts
176 The sum of all round-trip samples taken over the lifetime of the connection in
177 microseconds.
178 Each time TCP updates the value of
179 .Sy rtt
180 with a new sample, that sample's value is added to
181 .Sy rtts .
182 To calculate the average round-trip over a given period (e.g. between T1 and T2),
183 take samples of
184 .Sy rtts
185 and
186 .Sy rttc
187 at T1 and T2, and calculate
188 .br
189 ((
190 .Sy rtts Ns
191 _T2 -
192 .Sy rtts Ns
193 _T1 ) / (
194 .Sy rttc Ns
195 _T2 -
196 .Sy rttc Ns
197 _T1 )).
198 .br
199 See
200 .Sx Example 4
201 for an example of how this can be done programmatically from a shell script.
202 .It Sy rwnd
203 The size of the local TCP receive window at this instant.
204 .It Sy state
205 The TCP connection state.
206 Possible values are:
207 .Bl -tag -width "SYN_RECEIVED"
208 .It Sy BOUND
209 Bound, ready to connect or listen.
210 .It Sy CLOSED
211 Closed.
212 The local endpoint (e.g. socket) is not being used.
213 .It Sy CLOSING
214 Closed, but still waiting for a termination acknowledgment from the peer.
215 .It Sy CLOSE_WAIT
216 The peer has shutdown; waiting for the local endpoint to close.
217 .It Sy ESTABLISHED
218 Connection has been established and data can be transferred.
219 .It Sy FIN_WAIT_1
220 Local endpoint is closed, but waiting for termination acknowledgment from the
221 peer.
222 .It Sy FIN_WAIT_2
223 Local endpoint is closed, but waiting for a termination request from the peer.
224 .It Sy IDLE
225 The local endpoint (e.g. socket) has been opened, but is not bound.
226 .It Sy LAST_ACK
227 The remote endpoint has terminated, and the local endpoint has sent a termination
228 request.
229 The acknowledgment for this request has not been received.
230 .It Sy LISTEN
231 Listening for incoming connections.
232 .It Sy SYN_RECEIVED
233 Initial connection request has been received and acknowledged, and a connection
234 request has been sent but not yet acknowledged.
235 .It Sy SYN_SENT
236 A connection establishment request has been sent but not yet acknowledged.
237 .It Sy TIME_WAIT
238 Waiting for time to pass after having sent an acknowledgment for the peer's
239 connection termination request.
240 .El
241 .Pp
242 See RFC 793 for a more complete understanding of the TCP protocol and TCP
243 connection states.
244 .It Sy suna
245 The number of unacknowledged bytes outstanding at this instant.
246 .It Sy swnd
247 The size of the local TCP send window (the peer's receive window) at this
248 instant.
249 .It Sy unsent
250 The number of unsent bytes in the local TCP transmit queue at this instant.
251 .El
252 .Sh EXIT STATUS
253 The
254 .Nm
255 utility exits 0 on success, or 1 if an error occurs.
256 .Sh EXAMPLES
257 .Bl -tag -width ""
258 .It Sy Example 1 List established connections.
259 By default, connstat lists basic connection details.
260 Using the
261 .Fl e
262 option allows the user to get a quick glance of established connections.
263 .Bd -literal
264 $ connstat -e
265 LADDR LPORT RADDR RPORT STATE
266 10.43.37.172 51275 172.16.105.4 389 ESTABLISHED
267 10.43.37.172 22 172.16.98.16 62270 ESTABLISHED
268 10.43.37.172 1020 172.16.100.162 2049 ESTABLISHED
269 10.43.37.172 1019 10.43.11.64 2049 ESTABLISHED
270 10.43.37.172 22 172.16.98.16 61520 ESTABLISHED
271 10.43.37.172 80 10.43.16.132 59467 ESTABLISHED
272 .Ed
273 .It Sy Example 2 Show one connection's I/O stats every second
274 The
275 .Fl F
276 option is used to filter a specific connection,
277 .Fl o
278 is used to output specific fields, and
279 .Fl i
280 to provide the output interval in seconds.
281 .Bd -literal
282 $ connstat -F lport=22,rport=49675,raddr=172.16.168.30 \e
283 -o inbytes,outbytes -i 1
284 INBYTES OUTBYTES
285 9589 18101
286 INBYTES OUTBYTES
287 9589 18341
288 INBYTES OUTBYTES
289 9589 18501
290 INBYTES OUTBYTES
291 9589 18661
292 ...
293 .Ed
294 .It Sy Example 3 Understanding the bottleneck for a given connection
295 Understanding the transmit bottleneck for a connection requires knowing the
296 size of the congestion window, whether the window is full, and the round-trip
297 time to the peer.
298 The congestion window is full when
299 .Sy suna
300 is equal to
301 .Sy cwnd .
302 If the window is full, then the throughput is limited by the size of the window
303 and the round-trip time.
304 In that case, knowing these two values is critical.
305 Either the window is small because of retransmissions, or the round-trip
306 latency is high, or both.
307 In the example below, the window is small due to high congestion or an
308 unreliable network.
309 .Bd -literal
310 $ connstat -F lport=41934,rport=50001 \e
311 -o outbytes,suna,cwnd,unsent,retransbytes,rtt -T d -i 1
312 July 7, 2016 11:04:40 AM EDT
313 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
314 1647048093 47784 47784 3017352 3701844 495
315 July 7, 2016 11:04:41 AM EDT
316 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
317 1660720109 41992 41992 1535032 3765556 673
318 July 7, 2016 11:04:42 AM EDT
319 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
320 1661875613 26064 26064 4311688 3829268 571
321 July 7, 2016 11:04:43 AM EDT
322 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
323 1681478637 41992 41992 437304 3932076 1471
324 July 7, 2016 11:04:44 AM EDT
325 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
326 1692028765 44888 44888 1945800 4014612 921
327 \&...
328 .Ed
329 .It Sy Example 4 Calculating average RTT over intervals
330 As described in the
331 .Sx Fields
332 section, the
333 .Sy rtts
334 and
335 .Sy rttc
336 fields can be used to calculate average RTT over a period of time.
337 The following example combines machine parsable output with these fields to do
338 this programmatically.
339 The script:
340 .Bd -literal
341 #!/bin/bash
342
343 i=0
344 connstat -P -F lport=41934,rport=50001 -o rttc,rtts -i 1 | \e
345 while IFS=, read rttc[$i] rtts[$i]; do
346 if [[ $i != 0 ]]; then
347 let rtt="(${rtts[$i]} - ${rtts[$i - 1]}) / \e
348 (${rttc[$i]} - ${rttc[$i - 1]})"
349 print "avg rtt = ${rtt}us"
350 fi
351 ((i++))
352 done
353 .Ed
354 .Pp
355 The output:
356 .Bd -literal
357 \&...
358 avg rtt = 992us
359 avg rtt = 829us
360 avg rtt = 712us
361 avg rtt = 869us
362 \&...
363 .Ed
364 .It Sy Example 5 Show HTTP server connections in TIME_WAIT state
365 Connections accumulating in TIME_WAIT state can sometimes be an issue, as these
366 connections linger and take up port number space while their time wait timer
367 is ticking.
368 .Bd -literal
369 $ connstat -F state=time_wait,lport=80
370 LADDR LPORT RADDR RPORT STATE
371 10.43.37.172 80 172.16.168.30 56067 TIME_WAIT
372 10.43.37.172 80 172.16.168.30 56068 TIME_WAIT
373 10.43.37.172 80 172.16.168.30 56070 TIME_WAIT
374 .Ed
375 .El
376 .Sh INTERFACE STABILITY
377 The command line options for this command are stable, but the output format
378 when not using the
379 .Fl P
380 option and diagnostic messages are not.
381 .Sh SEE ALSO
382 .Xr netstat 1M
383 .Rs
384 .%A J. Postel
385 .%B Transmission Control Protocol, STD 7, RFC 793
386 .%D September 1981
387 .Re
388 .Rs
389 .%A V. Paxson
390 .%A M. Allman
391 .%A J. Chu
392 .%A M. Sargent
393 .%B Computing TCP's Retransmission Timer, RFC 6298
394 .%D June 2011
395 .Re