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 March 10, 2023 19.Dt CONNSTAT 8 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 34The 35.Nm 36command reports TCP connection statistics in tabular form. 37Each row of the table represents the activity of one connection. 38The 39.Nm 40command adds virtually no overhead to run as it is aggregating statistics that 41are always collected in the kernel. 42.Pp 43With no arguments, 44.Nm 45prints a single report containing all TCP connections, and includes a basic 46set of fields representing IP address and port information, as well as connection 47state. 48The 49.Fl o 50flag can be used to specify which fields to display, and other arguments to 51filter the set of connections included in the output. 52.Sh OPTIONS 53The arguments are as follows: 54.Bl -tag -width "" 55.It Fl 4 , Fl -ipv4 56Only displays IPv4 connections. 57.It Fl 6 , Fl -ipv6 58Only displays IPv6 connections 59.It Fl c Ar count , Fl -count Ns = Ns Ar count 60Print a specified number of reports before exiting. 61This is used in conjunction with 62.Fl i . 63.It Fl e , Fl -established 64Only display connections that are in state ESTABLISHED. 65This is equivalent to including 66.Sy state=ESTABLISHED 67in the filter argument to the 68.Fl F 69option. 70.It Fl F Ar filter , Fl -filter Ns = Ns Ar filter 71Only display connections that match the filter argument provided. 72The 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 76Fields that can currently be filtered are 77.Ar laddr , Ar lport , Ar raddr , Ar rport , and Ar state . 78See the 79.Sx Fields 80section for a description of these fields. 81The filter matches a connection if all of the filter elements match, and a 82field must only appears once in the filter. 83.It Fl i Ar interval , Fl -interval Ns = Ns Ar interval 84Specify an output interval in seconds. 85For each interval, a report containing all connections appropriate given other 86command-line options is printed. 87.It Fl L , Fl -no-loopback 88Exclude connections to the loopback address. 89.It Fl o Ar fields , Fl -output Ns = Ns Ar fields 90Restrict the output to the specified comma-delimited list of field names. 91See the 92.Sx Fields 93section for information about possible fields. 94.It Fl P , Fl -parsable 95Display using a stable, machine-parsable output format. 96The 97.Fl o 98flag must also be given to specify which fields to output and their order. 99Each line of output will consist of comma-delimited (,) fields, 100and no header will be emitted. 101When also using the 102.Fl T 103option, lines indicating the current time will begin with 104.Dq "= " . 105See 106.Sx Example 4 107for 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 109Print a timestamp before each block of output. 110.Pp 111Specify 112.Sy u 113for a printed representation of the internal representation of time (see 114.Xr time 2 Ns ). 115Specify 116.Sy d 117for standard date format (see 118.Xr date 1 Ns ). 119.El 120.Ss Fields 121The following fields are supported. 122Field names are case insensitive. 123Unless otherwise indicated, the values of fields that represent a count (e.g. 124bytes or segments) are cumulative since the connection was established. 125Some of these fields refer to data segments, which are segments that contain 126non-zero amount of data. 127All sizes are in bytes. 128.Bl -tag -width "inunorderbytes" 129.It Sy cwnd 130The size of the local TCP congestion window at this instant. 131.It Sy inbytes 132The number of data bytes received. 133This does not include duplicate bytes received. 134.It Sy insegs 135The number of data segments received. 136This does not include duplicate segments received. 137.It Sy inunorderbytes 138The number of data bytes that were received out of order. 139.It Sy inunordersegs 140The number of data segments that were received out of order. 141.It Sy laddr 142The local IP address. 143.It Sy lport 144The local TCP port. 145.It Sy mss 146The maximum TCP segment size for this connection. 147.It Sy outbytes 148The number of data bytes sent. 149This does not include retransmitted bytes counted by 150.Sy retransbytes . 151.It Sy outsegs 152The number of data segments sent. 153This does not include segments containing retransmitted bytes counted by 154.Sy retranssegs . 155.It Sy raddr 156The remote IP address. 157.It Sy retransbytes 158The number of data bytes retransmitted. 159.It Sy retranssegs 160The number of data segments sent that contained retransmitted bytes. 161.It Sy rport 162The remote TCP port. 163.It Sy rto 164The current retransmission timeout in milliseconds. 165.It Sy rtt 166The current smoothed round-trip time to the peer in microseconds. 167The smoothed RTT average algorithm used is as described in RFC 6298. 168.It Sy rttc 169The number of times that a round-trip sample was added to 170.Sy rtts . 171See 172.Sy rtts 173for a description of how these two fields can be used together to calculate the 174average round-trip over a given period. 175.It Sy rtts 176The sum of all round-trip samples taken over the lifetime of the connection in 177microseconds. 178Each time TCP updates the value of 179.Sy rtt 180with a new sample, that sample's value is added to 181.Sy rtts . 182To calculate the average round-trip over a given period (e.g. between T1 and T2), 183take samples of 184.Sy rtts 185and 186.Sy rttc 187at 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 199See 200.Sx Example 4 201for an example of how this can be done programmatically from a shell script. 202.It Sy rwnd 203The size of the local TCP receive window at this instant. 204.It Sy state 205The TCP connection state. 206Possible values are: 207.Bl -tag -width "SYN_RECEIVED" 208.It Sy BOUND 209Bound, ready to connect or listen. 210.It Sy CLOSED 211Closed. 212The local endpoint (e.g. socket) is not being used. 213.It Sy CLOSING 214Closed, but still waiting for a termination acknowledgment from the peer. 215.It Sy CLOSE_WAIT 216The peer has shutdown; waiting for the local endpoint to close. 217.It Sy ESTABLISHED 218Connection has been established and data can be transferred. 219.It Sy FIN_WAIT_1 220Local endpoint is closed, but waiting for termination acknowledgment from the 221peer. 222.It Sy FIN_WAIT_2 223Local endpoint is closed, but waiting for a termination request from the peer. 224.It Sy IDLE 225The local endpoint (e.g. socket) has been opened, but is not bound. 226.It Sy LAST_ACK 227The remote endpoint has terminated, and the local endpoint has sent a termination 228request. 229The acknowledgment for this request has not been received. 230.It Sy LISTEN 231Listening for incoming connections. 232.It Sy SYN_RECEIVED 233Initial connection request has been received and acknowledged, and a connection 234request has been sent but not yet acknowledged. 235.It Sy SYN_SENT 236A connection establishment request has been sent but not yet acknowledged. 237.It Sy TIME_WAIT 238Waiting for time to pass after having sent an acknowledgment for the peer's 239connection termination request. 240.El 241.Pp 242See RFC 793 for a more complete understanding of the TCP protocol and TCP 243connection states. 244.It Sy suna 245The number of unacknowledged bytes outstanding at this instant. 246.It Sy swnd 247The size of the local TCP send window (the peer's receive window) at this 248instant. 249.It Sy unsent 250The number of unsent bytes in the local TCP transmit queue at this instant. 251.El 252.Sh EXIT STATUS 253The 254.Nm 255utility 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. 259By default, connstat lists basic connection details. 260Using the 261.Fl e 262option 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 274The 275.Fl F 276option is used to filter a specific connection, 277.Fl o 278is used to output specific fields, and 279.Fl i 280to 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 295Understanding the transmit bottleneck for a connection requires knowing the 296size of the congestion window, whether the window is full, and the round-trip 297time to the peer. 298The congestion window is full when 299.Sy suna 300is equal to 301.Sy cwnd . 302If the window is full, then the throughput is limited by the size of the window 303and the round-trip time. 304In that case, knowing these two values is critical. 305Either the window is small because of retransmissions, or the round-trip 306latency is high, or both. 307In the example below, the window is small due to high congestion or an 308unreliable network. 309.Bd -literal 310$ connstat -F lport=41934,rport=50001 \e 311 -o outbytes,suna,cwnd,unsent,retransbytes,rtt -T d -i 1 312July 7, 2016 11:04:40 AM EDT 313 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT 314 1647048093 47784 47784 3017352 3701844 495 315July 7, 2016 11:04:41 AM EDT 316 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT 317 1660720109 41992 41992 1535032 3765556 673 318July 7, 2016 11:04:42 AM EDT 319 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT 320 1661875613 26064 26064 4311688 3829268 571 321July 7, 2016 11:04:43 AM EDT 322 OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT 323 1681478637 41992 41992 437304 3932076 1471 324July 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 330As described in the 331.Sx Fields 332section, the 333.Sy rtts 334and 335.Sy rttc 336fields can be used to calculate average RTT over a period of time. 337The following example combines machine parsable output with these fields to do 338this programmatically. 339The script: 340.Bd -literal 341#!/bin/bash 342 343i=0 344connstat -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++)) 352done 353.Ed 354.Pp 355The output: 356.Bd -literal 357\&... 358avg rtt = 992us 359avg rtt = 829us 360avg rtt = 712us 361avg rtt = 869us 362\&... 363.Ed 364.It Sy Example 5 Show HTTP server connections in TIME_WAIT state 365Connections accumulating in TIME_WAIT state can sometimes be an issue, as these 366connections linger and take up port number space while their time wait timer 367is 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 377The command line options for this command are stable, but the output format 378when not using the 379.Fl P 380option and diagnostic messages are not. 381.Sh SEE ALSO 382.Xr netstat 8 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 396