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