Tribblix: manual page: connstat.8

CONNSTAT(8) Maintenance Commands and Procedures CONNSTAT(8)

NAME

connstat - report TCP connection statistics

SYNOPSIS

connstat [-eLP] [-4|-6] [-T d|u] [-F filter] [-i interval] [-c count]
[-o field[,field]...]

DESCRIPTION

The connstat command reports TCP connection statistics in tabular form.
Each row of the table represents the activity of one connection. The
connstat command adds virtually no overhead to run as it is aggregating
statistics that are always collected in the kernel.

With no arguments, connstat prints a single report containing all TCP
connections, and includes a basic set of fields representing IP address
and port information, as well as connection state. The -o flag can be
used to specify which fields to display, and other arguments to filter
the set of connections included in the output.

OPTIONS

The arguments are as follows:

-4, --ipv4
Only displays IPv4 connections.

-6, --ipv6
Only displays IPv6 connections

-c count, --count=count
Print a specified number of reports before exiting. This is used in
conjunction with -i.

-e, --established
Only display connections that are in state ESTABLISHED. This is
equivalent to including state=ESTABLISHED in the filter argument to
the -F option.

-F filter, --filter=filter
Only display connections that match the filter argument provided.
The format of the filter is:

field=value[,field=value]...

Fields that can currently be filtered are laddr, lport, raddr, rport,
and state. See the Fields section for a description of these fields.
The filter matches a connection if all of the filter elements match,
and a field must only appears once in the filter.

-i interval, --interval=interval
Specify an output interval in seconds. For each interval, a report
containing all connections appropriate given other command-line
options is printed.

-L, --no-loopback
Exclude connections to the loopback address.

-o fields, --output=fields
Restrict the output to the specified comma-delimited list of field
names. See the Fields section for information about possible fields.

-P, --parsable
Display using a stable, machine-parsable output format. The -o flag
must also be given to specify which fields to output and their order.
Each line of output will consist of comma-delimited (,) fields, and
no header will be emitted. When also using the -T option, lines
indicating the current time will begin with "= ". See Example 4 for
an example of how to process parsable output.

-T d|u, --timestamp=d|u
Print a timestamp before each block of output.

Specify u for a printed representation of the internal representation
of time (see time(2)). Specify d for standard date format (see
date(1)).

Fields

The following fields are supported. Field names are case insensitive.
Unless otherwise indicated, the values of fields that represent a count
(e.g. bytes or segments) are cumulative since the connection was
established. Some of these fields refer to data segments, which are
segments that contain non-zero amount of data. All sizes are in bytes.

cwnd The size of the local TCP congestion window at this
instant.

inbytes The number of data bytes received. This does not
include duplicate bytes received.

insegs The number of data segments received. This does not
include duplicate segments received.

inunorderbytes The number of data bytes that were received out of
order.

inunordersegs The number of data segments that were received out of
order.

laddr The local IP address.

lport The local TCP port.

mss The maximum TCP segment size for this connection.

outbytes The number of data bytes sent. This does not include
retransmitted bytes counted by retransbytes.

outsegs The number of data segments sent. This does not
include segments containing retransmitted bytes counted
by retranssegs.

raddr The remote IP address.

retransbytes The number of data bytes retransmitted.

retranssegs The number of data segments sent that contained
retransmitted bytes.

rport The remote TCP port.

rto The current retransmission timeout in milliseconds.

rtt The current smoothed round-trip time to the peer in
microseconds. The smoothed RTT average algorithm used
is as described in RFC 6298.

rttc The number of times that a round-trip sample was added
to rtts. See rtts for a description of how these two
fields can be used together to calculate the average
round-trip over a given period.

rtts The sum of all round-trip samples taken over the
lifetime of the connection in microseconds. Each time
TCP updates the value of rtt with a new sample, that
sample's value is added to rtts. To calculate the
average round-trip over a given period (e.g. between T1
and T2), take samples of rtts and rttc at T1 and T2,
and calculate
(( rtts_T2 - rtts_T1 ) / ( rttc_T2 - rttc_T1 )).
See Example 4 for an example of how this can be done
programmatically from a shell script.

rwnd The size of the local TCP receive window at this
instant.

state The TCP connection state. Possible values are:

BOUND Bound, ready to connect or listen.

CLOSED Closed. The local endpoint (e.g. socket)
is not being used.

CLOSING Closed, but still waiting for a
termination acknowledgment from the peer.

CLOSE_WAIT The peer has shutdown; waiting for the
local endpoint to close.

ESTABLISHED Connection has been established and data
can be transferred.

FIN_WAIT_1 Local endpoint is closed, but waiting for
termination acknowledgment from the peer.

FIN_WAIT_2 Local endpoint is closed, but waiting for
a termination request from the peer.

IDLE The local endpoint (e.g. socket) has been
opened, but is not bound.

LAST_ACK The remote endpoint has terminated, and
the local endpoint has sent a termination
request. The acknowledgment for this
request has not been received.

LISTEN Listening for incoming connections.

SYN_RECEIVED Initial connection request has been
received and acknowledged, and a
connection request has been sent but not
yet acknowledged.

SYN_SENT A connection establishment request has
been sent but not yet acknowledged.

TIME_WAIT Waiting for time to pass after having
sent an acknowledgment for the peer's
connection termination request.

See RFC 793 for a more complete understanding of the
TCP protocol and TCP connection states.

suna The number of unacknowledged bytes outstanding at this
instant.

swnd The size of the local TCP send window (the peer's
receive window) at this instant.

unsent The number of unsent bytes in the local TCP transmit
queue at this instant.

EXIT STATUS

The connstat utility exits 0 on success, or 1 if an error occurs.

EXAMPLES

Example 1 List established connections.
By default, connstat lists basic connection details. Using the -e
option allows the user to get a quick glance of established
connections.

$ connstat -e
LADDR LPORT RADDR RPORT STATE
10.43.37.172 51275 172.16.105.4 389 ESTABLISHED
10.43.37.172 22 172.16.98.16 62270 ESTABLISHED
10.43.37.172 1020 172.16.100.162 2049 ESTABLISHED
10.43.37.172 1019 10.43.11.64 2049 ESTABLISHED
10.43.37.172 22 172.16.98.16 61520 ESTABLISHED
10.43.37.172 80 10.43.16.132 59467 ESTABLISHED

Example 2 Show one connection's I/O stats every second
The -F option is used to filter a specific connection, -o is used to
output specific fields, and -i to provide the output interval in
seconds.

$ connstat -F lport=22,rport=49675,raddr=172.16.168.30 \
-o inbytes,outbytes -i 1
INBYTES OUTBYTES
9589 18101
INBYTES OUTBYTES
9589 18341
INBYTES OUTBYTES
9589 18501
INBYTES OUTBYTES
9589 18661
...

Example 3 Understanding the bottleneck for a given connection
Understanding the transmit bottleneck for a connection requires
knowing the size of the congestion window, whether the window is
full, and the round-trip time to the peer. The congestion window is
full when suna is equal to cwnd. If the window is full, then the
throughput is limited by the size of the window and the round-trip
time. In that case, knowing these two values is critical. Either
the window is small because of retransmissions, or the round-trip
latency is high, or both. In the example below, the window is small
due to high congestion or an unreliable network.

$ connstat -F lport=41934,rport=50001 \
-o outbytes,suna,cwnd,unsent,retransbytes,rtt -T d -i 1
July 7, 2016 11:04:40 AM EDT
OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
1647048093 47784 47784 3017352 3701844 495
July 7, 2016 11:04:41 AM EDT
OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
1660720109 41992 41992 1535032 3765556 673
July 7, 2016 11:04:42 AM EDT
OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
1661875613 26064 26064 4311688 3829268 571
July 7, 2016 11:04:43 AM EDT
OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
1681478637 41992 41992 437304 3932076 1471
July 7, 2016 11:04:44 AM EDT
OUTBYTES SUNA CWND UNSENT RETRANSBYTES RTT
1692028765 44888 44888 1945800 4014612 921
...

Example 4 Calculating average RTT over intervals
As described in the Fields section, the rtts and rttc fields can be
used to calculate average RTT over a period of time. The following
example combines machine parsable output with these fields to do this
programmatically. The script:

#!/bin/bash

i=0
connstat -P -F lport=41934,rport=50001 -o rttc,rtts -i 1 | \
while IFS=, read rttc[$i] rtts[$i]; do
if [[ $i != 0 ]]; then
let rtt="(${rtts[$i]} - ${rtts[$i - 1]}) / \
(${rttc[$i]} - ${rttc[$i - 1]})"
print "avg rtt = ${rtt}us"
fi
((i++))
done

The output:

...
avg rtt = 992us
avg rtt = 829us
avg rtt = 712us
avg rtt = 869us
...

Example 5 Show HTTP server connections in TIME_WAIT state
Connections accumulating in TIME_WAIT state can sometimes be an
issue, as these connections linger and take up port number space
while their time wait timer is ticking.

$ connstat -F state=time_wait,lport=80
LADDR LPORT RADDR RPORT STATE
10.43.37.172 80 172.16.168.30 56067 TIME_WAIT
10.43.37.172 80 172.16.168.30 56068 TIME_WAIT
10.43.37.172 80 172.16.168.30 56070 TIME_WAIT

INTERFACE STABILITY

The command line options for this command are stable, but the output
format when not using the -P option and diagnostic messages are not.