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