nicstat.1

.\" nicstat.1 -	Man page for nicstat(1)
.\"
.\" Copyright (c) 2009-2014, Tim Cook, Oracle Corporation

.\" nicstat is licensed under the Artistic License 2.0.  You can find a
.\" copy of this license as LICENSE.txt included with the nicstat
.\" distribution, or at http://www.perlfoundation.org/artistic_license_2_0
.\" 
.\" @(#)nicstat.1	1.4	11/04/25 timothy.cook@oracle.com
.\"
.TH nicstat 1 "27 Jan 2014"
.UC 4
.\" ========================================================================

.SH NAME

nicstat, enicstat \- print network traffic statistics
.\" ========================================================================
.SH SYNOPSIS
.B nicstat
[-hvnsxpztualkMU]
.RI [-i interface]
.RI [-S int:mbps[fd|hd]]
.I [interval
.I [count]]
.PP
.B enicstat
\fI<same options & operands>
.\" ========================================================================

.SH DESCRIPTION

.I nicstat
prints out network statistics for all network cards (NICs),
including packets, kilobytes per second, average packet sizes and more.
.\" ========================================================================

.SH OPTIONS

.TP 1i
.B \-h
Display brief usage information (help).
.TP 1i
.B \-v
Display nicstat version (and additional fields when combined with '-l')
.TP 1i
.B \-n 
Show statistics for non-local (i.e. non-loopback) interfaces only.
.TP 1i
.B \-s
Display summary output - just the amount of data received (read) and
transmitted (written).
.TP 1i
.B \-x
Display extended output.  See \fBOUTPUT\fR section for details.
.TP 1i
.B \-U
Display separate read and write utilization statistics. This affects
the default, extended (-x) and all (-a) format outputs. For the
default format the "Sat" statistic is dropped to fit the output in 80
columns.
.TP 1i
.B \-M
Display interface throughput statistics in Mbps (megabits per second),
instead of the default KB/s (kilobytes per second).

NOTE - interface statistics are reported to operating systems in bytes.
nicstat does not know if Ethernet or other hardware overheads are
included in the statistic on each platform.
.TP 1i
.B \-p
Display output in parseable format.  This outputs one line per
interface, in the following formats (which correspond to the
default, -x, -t and -u options; respectively):
.TP 1i
.PP
.I time:In:rKB/s:wKB/s:rPk/s:wPk/s:%Util:Sat
.I time:In:rKB/s:wKB/s:rPk/s:wPk/s:%Util:Sat:IErr:OErr:Coll:NoCP:Defer
.I time:\fRTCP\fI:InKB:OutKB:InSeg:OutSeg:Reset:AttF:%ReTX:InConn:OutCon:Drops
.I time:\fRUDP\fI:InDG:OutDG:InErr:OutErr
.TP 1i
.B \ 
where \fItime\fR is the number of seconds since midnight,
Jan 1 1970 (UST) and the other fields are as described in the
\fBOUTPUT\fR section below.

NOTE - throughput statistics are always in KB/s (kilbytes per second)
for parseable formats, even if the "-M" flag has been specified.
.TP 1i
.B \-z
Skip interfaces for which there was zero traffic for the sample period.
.TP 1i
.B \-t
Show TCP statistics.
.TP 1i
.B \-u
Show UDP statistics.
.TP 1i
.B \-a
Equvalent to '-x -t -u'.
.TP 1i
.B \-l
Just list interfaces.
.TP 1i
.BI \-i interface[,interface ...]
Show statistics for only the interface(s) listed.  Multiple interfaces
can be listed, separated by commas (,).
.TP 1i
.BI \-S int:speed[fd|hd]
(Linux only).
Specify the speed (and optionally duplex mode) of one or more interfaces.
The given speed(s) are in megabits/second.
The duplex mode will default to "full" unless a suffix beginning with
"h" or "H" is specified.
Speed and duplex mode are obtained automatically on Solaris using the
"ifspeed" and "link_duplex" kstat values.
.TP 1i
.B \-k
(Solaris only).
Search for active network interfaces by looking for kstat "link_state"
statistics with a value of 1.  This is only of value on systems
running Solaris 10 (or early releases of Solaris 11 Express), with
Exclusive IP Zones, where the interfaces given to an Exclusive IP Zone
are not otherwise visible.  If you are running Solaris 9 (or earlier),
or Solaris 11 (or later) you do not need this option.
.\" ========================================================================

.SH OPERANDS

.TP 1i
.I interval
Specifies the number of seconds between samples.

.TP 1i
.I count
Specifies the number of times that the statistics are repeated.  If no
.I count
is specified,
.B nicstat
will repeat statistics indefinitely.
.\" ========================================================================

.SH OUTPUT

The fields of \fBnicstat\fP's display are:
.TP 1i
.B Time
The time corresponding to the end of the sample shown, in
.I HH:MM:SS
format (24-hour clock).
.TP 1i
.B Int
The interface name.
.TP 1i
.B rKB/s, InKB
Kilobytes/second read (received).
.TP 1i
.B wKB/s, OutKB
Kilobytes/second written (transmitted).
.TP 1i
.B rMbps, RdMbps
Megabits/second read (received).
.TP 1i
.B wMbps, WrMbps
Megabits/second written (transmitted).
.TP 1i
.B rPk/s, InSeg, InDG
Packets (TCP Segments, UDP Datagrams)/second read (received).
.TP 1i
.B wPk/s, OutSeg, OutDG
Packets (TCP Segments, UDP Datagrams)/second written (transmitted).
.TP 1i
.B rAvs
Average size of packets read (received).
.TP 1i
.B wAvs
Average size of packets written (transmitted).
.TP 1i
.B %Util
Percentage utilization of the interface.  For full-duplex interfaces,
this is the greater of
.I rKB/s
or
.I wKB/s
as a percentage of the interface speed.
For half-duplex interfaces,
.I rKB/s
and
.I wKB/s
are summed.
.TP 1i
.B %rUtil, %wUtil
Percentage utilization for bytes read and written, respectively.
.TP 1i
.B Sat
Saturation.  This the number of errors/second seen for the interface -
an indicator the interface may be approaching saturation.  This
statistic is combined from a number of kernel statistics.  It is
recommended to use the '-x' option to see more individual statistics
(those mentioned below) when attempting to diagnose a network issue.

.TP 1i
.B IErr
Packets received that could not be processed because they contained
errors
.TP 1i
.B OErr
Packets that were not successfully transmitted because of errors
.TP 1i
.B Coll
Ethernet collisions during transmit.
.TP 1i
.B NoCP
No-can-puts.  This is when an incoming packet can not be put to the
process reading the socket.  This suggests the local process is unable
to process incoming packets in a timely manner.
.TP 1i
.B Defer
Defer Transmits.  Packets without collisions where first transmit
attempt was delayed because the medium was busy.

.TP 1i
.B Reset
tcpEstabResets. The number of times TCP connections have made a direct
transition to the CLOSED state from either the ESTABLISHED state or
the CLOSE-WAIT state.
.TP 1i
.B AttF
tcpAttemptFails - The number of times that TCP connections have made a
direct transition to the CLOSED state from either the SYN-SENT state
or the SYN-RCVD state, plus the number of times TCP connections have
made a direct transition to the LISTEN state from the SYN-RCVD state.
.TP 1i
.B %ReTX
Percentage of TCP segments retransmitted - that is, the number of TCP
segments transmitted containing one or more previously transmitted
octets.
.TP 1i
.B InConn
tcpPassiveOpens - The number of times that TCP connections have made a
direct transition to the SYN-RCVD state from the LISTEN
state.
.TP 1i
.B OutCon
tcpActiveOpens - The number of times that TCP connections have made a
direct transition to the SYN-SENT state from the CLOSED state.
.TP 1i
.B Drops
tcpHalfOpenDrop + tcpListenDrop + tcpListenDropQ0.
.PP
\fItcpListenDrop\fR and \fItcpListenDropQ0\fR - Number of connections
dropped from the completed connection queue and incomplete connection
queue, respectively.  \fItcpHalfOpenDrops\fR - Number of connections dropped
after the initial SYN packet was received.
.PP
The first set of statistics printed are averages since system boot.
If no
.B interval
operand is specified, or a
.B count
value of "1" is specified, this will be the only sample printed.
.\" ========================================================================
.SH EXAMPLES
Print average statistics from boot time to now only:
.PP
.nf
	$ \fBnicstat
.fi
.PP
Print statistics for all interfaces, every 3 seconds:
.PP
.nf
	$ \fBnicstat 3
.fi
.PP
Print statistics for all interfaces, every 5 seconds, finishing after
10 samples:
.PP
.nf
	$ \fBnicstat 5 10
.fi
.PP
Print statistics every 3 seconds, only for interfaces "hme0" and "hme1":
.PP
.nf
	$ \fBnicstat -i hme0,hme1 3
.fi
.PP
Print statistics for non-local interfaces, setting speed of "eth0" and
"eth1" to 10mbps/half-duplex and 1000mbps/full-duplex, respectively:
.PP
.nf
	$ \fBnicstat -n -S eth0:10h,eth1:1000 5
.fi
.\" ========================================================================
.SH SEE\ ALSO
.BR netstat (1M)
.BR kstat (1M),
.BR kstat (3KSTAT),
.BR mibiisa (1M),
.BR ethtool (8)

"nicstat - the Solaris and Linux Network Monitoring Tool You Did Not Know You Needed"
.RI - http://blogs.oracle.com/timc/entry/nicstat_the_solaris_and_linux
.\" ========================================================================
.SH NOTES
.PP
On Linux, the NoCP, Defer, TCP InKB, and TCP OutKB statistics are
always reported as zero.
.PP
The way that saturation is reported is a best effort, as there is no
standardized naming to capture all errors related to an interface's
inability to receive or transmit a packet.  Monitoring %Util and
packet rates, along with an understanding of the specific NICs may be
more useful in judging whether you are nearing saturation.
.PP
The
.B \-S
option is provided for the Linux edition as nicstat requires
super-user privilege to obtain speed and duplex mode information for
interfaces.
If you are unable to set up nicstat as setuid-root, a script named
.B enicstat
is available, which uses the
.B ethtool
utility then calls nicstat with an
.B \-S
value.
.B ethtool
itself requires super-user privilege for this to work.