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 .Pp
53 The arguments are as folows:
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 conjuction 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 With this option, each line of output consists of comma (,) delimited fields,
97 and the fields displayed are specified using the
98 .Fl o
99 option.
100 See
101 .Sx Example 4
102 for an example of how to process parsable output.
103 .It Fl T Sy d Ns | Ns Sy u , Fl -timestamp Ns = Ns Sy d Ns | Ns Sy u
104 Print a timestamp before each block of output.
105 .Pp
106 Specify
107 .Sy u
108 for a printed representation of the internal representation of time (see
109 .Xr time 2 Ns ).
110 Specify
111 .Sy d
112 for standard date format (see
113 .Xr date 1 Ns ).
114 .El
115 .Ss Fields
116 The following fields are supported.
117 Field names are case insensitive.
118 Unless otherwise indicated, the values of fields that represent a count (e.g.
119 bytes or segments) are cumulative since the connection was established.
120 Some of these fields refer to data segments, which are segments that contain
121 non-zero amount of data.
122 All sizes are in bytes.
123 .Bl -tag -width "inunorderbytes"
124 .It Sy cwnd
125 The size of the local TCP congestion window at this instant.
126 .It Sy inbytes
127 The number of data bytes received.
128 This does not include duplicate bytes received.
129 .It Sy insegs
130 The number of data segments received.
131 This does not include duplicate segments received.
132 .It Sy inunorderbytes
133 The number of data bytes that were received out of order.
134 .It Sy inunordersegs
135 The number of data segments that were received out of order.
136 .It Sy laddr
137 The local IP address.
138 .It Sy lport
139 The local TCP port.
140 .It Sy mss
141 The maximum TCP segment size for this connection.
142 .It Sy outbytes
143 The number of data bytes sent.
144 This does not include retransmitted bytes counted by
145 .Sy retransbytes .
146 .It Sy outsegs
147 The number of data segments sent.
148 This does not include segments containing retransmitted bytes counted by
149 .Sy retranssegs .
150 .It Sy raddr
151 The remote IP address.
152 .It Sy retransbytes
153 The number of data bytes retransmitted.
154 .It Sy retranssegs
155 The number of data segments sent that contained retransmitted bytes.
156 .It Sy rport
157 The remote TCP port.
158 .It Sy rto
159 The current retransmission timeout in milliseconds.
160 .It Sy rtt
161 The current smoothed round-trip time to the peer in microseconds.
162 The smoothed RTT average algorithm used is as described in RFC 6298.
163 .It Sy rttc
164 The number of times that a round-trip sample was added to
165 .Sy rtts .
166 See
167 .Sy rtts
168 for a description of how these two fields can be used together to calculate the
169 average round-trip over a given period.
170 .It Sy rtts
171 The sum of all round-trip samples taken over the lifetime of the connection in
172 microseconds.
173 Each time TCP updates the value of
174 .Sy rtt
175 with a new sample, that sample's value is added to
176 .Sy rtts .
177 To calculate the average round-trip over a given period (e.g. between T1 and T2),
178 take samples of
179 .Sy rtts
180 and
181 .Sy rttc
182 at T1 and T2, and calculate
183 .br
184 ((
185 .Sy rtts Ns
186 _T2 -
187 .Sy rtts Ns
188 _T1 ) / (
189 .Sy rttc Ns
190 _T2 -
191 .Sy rttc Ns
192 _T1 )).
193 .br
194 See
195 .Sx Example 4
196 for an example of how this can be done programatically from a shell script.
197 .It Sy rwnd
198 The size of the local TCP receive window at this instant.
199 .It Sy state
200 The TCP connection state.
201 Possible values are:
202 .Bl -tag -width "SYN_RECEIVED"
203 .It Sy BOUND
204 Bound, ready to connect or listen.
205 .It Sy CLOSED
206 Closed.
207 The local endpoint (e.g. socket) is not being used.
208 .It Sy CLOSING
209 Closed, but still waiting for a termination acknowledgment from the peer.
210 .It Sy CLOSE_WAIT
211 The peer has shutdown; waiting for the local endpoint to close.
212 .It Sy ESTABLISHED
213 Connection has been established and data can be transfered.
214 .It Sy FIN_WAIT_1
215 Local endpoint is closed, but waiting for termination acknowledgment from the
216 peer.
217 .It Sy FIN_WAIT_2
218 Local endpoint is closed, but waiting for a termination request from the peer.
219 .It Sy IDLE
220 The local endpoint (e.g. socket) has been opened, but is not bound.
221 .It Sy LAST_ACK
222 The remote endpoint has terminated, and the local endpoint has sent a termination
223 request.
224 The acknowledgment for this request has not been received.
225 .It Sy LISTEN
226 Listening for incoming connections.
227 .It Sy SYN_RECEIVED
228 Initial connection request has been received and acknowledged, and a connection
229 request has been sent but not yet acknowledged.
230 .It Sy SYN_SENT
231 A connection establishment request has been sent but not yet acknowledged.
232 .It Sy TIME_WAIT
233 Waiting for time to pass after having sent an acknowledgment for the peer's
234 connection termination request.
235 .El
236 .Pp
237 See RFC 793 for a more complete understanding of the TCP protocol and TCP
238 connection states.
239 .It Sy suna
240 The number of unacknowledged bytes outstanding at this instant.
241 .It Sy swnd
242 The size of the local TCP send window (the peer's receive window) at this
243 instant.
244 .It Sy unsent
245 The number of unsent bytes in the local TCP transmit queue at this instant.
246 .El
247 .Sh EXIT STATUS
248 The
249 .Nm
250 utility exits 0 on success, or 1 if an error occurs.
251 .Sh EXAMPLES
252 .Bl -tag -width ""
253 .It Sy Example 1 List established connections.
254 By default, connstat lists basic connection details.
255 Using the
256 .Fl e
257 option allows the user to get a quick glance of established connections.
258 .Bd -literal
259 $ connstat -e
260 LADDR LPORT RADDR RPORT STATE
261 10.43.37.172 51275 172.16.105.4 389 ESTABLISHED
262 10.43.37.172 22 172.16.98.16 62270 ESTABLISHED
263 10.43.37.172 1020 172.16.100.162 2049 ESTABLISHED
264 10.43.37.172 1019 10.43.11.64 2049 ESTABLISHED
265 10.43.37.172 22 172.16.98.16 61520 ESTABLISHED
266 10.43.37.172 80 10.43.16.132 59467 ESTABLISHED
267 .Ed
268 .It Sy Example 2 Show one connection's I/O stats every second
269 The
270 .Fl F
271 option is used to filter a specific connection,
272 .Fl o
273 is used to output specific fields, and
274 .Fl i
275 to provide the output interval in seconds.
276 .Bd -literal
277 $ connstat -F lport=22,rport=49675,raddr=172.16.168.30 \e
278 -o inbytes,outbytes -i 1
279 INBYTES OUTBYTES
280 9589 18101
281 INBYTES OUTBYTES
282 9589 18341
283 INBYTES OUTBYTES
284 9589 18501
285 INBYTES OUTBYTES
286 9589 18661
287 ...
288 .Ed
289 .It Sy Example 3 Understanding the bottleneck for a given connection
290 Understanding the transmit bottleneck for a connection requires knowing the
291 size of the congestion window, whether the window is full, and the round-trip
292 time to the peer.
293 The congestion window is full when
294 .Sy suna
295 is equal to
296 .Sy cwnd .
297 If the window is full, then the throughput is limited by the size of the window
298 and the round-trip time.
299 In that case, knowing these two values is critical.
300 Either the window is small because of retransmissions, or the the round-trip
301 latency is high, or both.
302 In the example below, the window is small due to high congestion or an
303 unreliable network.
304 .Bd -literal
305 $ connstat -F lport=41934,rport=50001 \e
306 -o outbytes,suna,cwnd,unsent,retransbytes,rtt -T d -i 1
307 July 7, 2016 11:04:40 AM EDT
308 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
309 1647048093 47784 47784 3017352 3701844 495
310 July 7, 2016 11:04:41 AM EDT
311 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
312 1660720109 41992 41992 1535032 3765556 673
313 July 7, 2016 11:04:42 AM EDT
314 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
315 1661875613 26064 26064 4311688 3829268 571
316 July 7, 2016 11:04:43 AM EDT
317 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
318 1681478637 41992 41992 437304 3932076 1471
319 July 7, 2016 11:04:44 AM EDT
320 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
321 1692028765 44888 44888 1945800 4014612 921
322 \&...
323 .Ed
324 .It Sy Example 4 Calculating average RTT over intervals
325 As described in the
326 .Sx Fields
327 section, the
328 .Sy rtts
329 and
330 .Sy rttc
331 fields can be used to calculate average RTT over a period of time.
332 The following example combines machine parsable output with these fields to do
333 this programatically.
334 The script:
335 .Bd -literal
336 #!/bin/bash
337
338 i=0
339 connstat -P -F lport=41934,rport=50001 -o rttc,rtts -i 1 | \e
340 while IFS=, read rttc[$i] rtts[$i]; do
341 if [[ $i != 0 ]]; then
342 let rtt="(${rtts[$i]} - ${rtts[$i - 1]}) / \e
343 (${rttc[$i]} - ${rttc[$i - 1]})"
344 print "avg rtt = ${rtt}us"
345 fi
346 ((i++))
347 done
348 .Ed
349 .Pp
350 The output:
351 .Bd -literal
352 \&...
353 avg rtt = 992us
354 avg rtt = 829us
355 avg rtt = 712us
356 avg rtt = 869us
357 \&...
358 .Ed
359 .It Sy Example 5 Show HTTP server connections in TIME_WAIT state
360 Connections accumulating in TIME_WAIT state can sometimes be an issue, as these
361 connections linger and take up port number space while their time wait timer
362 is ticking.
363 .Bd -literal
364 $ connstat -F state=time_wait,lport=80
365 LADDR LPORT RADDR RPORT STATE
366 10.43.37.172 80 172.16.168.30 56067 TIME_WAIT
367 10.43.37.172 80 172.16.168.30 56068 TIME_WAIT
368 10.43.37.172 80 172.16.168.30 56070 TIME_WAIT
369 .Ed
370 .El
371 .Sh INTERFACE STABILITY
372 .Sy Commited .
373 .Sh SEE ALSO
374 .Xr netstat 1M
375 .Rs
376 .%A J. Postel
377 .%B Transmission Control Protocol, STD 7, RFC 793
378 .%D September 1981
379 .Re
380 .Rs
381 .%A V. Paxson
382 .%A M. Allman
383 .%A J. Chu
384 .%A M. Sargent
385 .%B Computing TCP's Retransmission Timer, RFC 6298
386 .%D June 2011
387 .Re