nicstat(1)

✨ nicstat(1) ✨

okay bestie, sit down, hydrate, because we're about to talk about nicstat — it's a general commands manual page, and it's literally the moment your NICs finally tell you what they've been up to. 🫶

It ships with a twin called enicstat too. They're a package deal. 💅

---

🌸 NAME 🌸

nicstat, enicstat — print network traffic statistics 💖

---

🎀 SYNOPSIS 🎀

nicstat [-hvnsxpztualkMU] [-iinterface] [-Sint:mbps[fd|hd]] [interval [count]]

enicstat <same options & operands>

---

🦋 DESCRIPTION 🦋

So here's the vibe: nicstat prints out network statistics for all your network cards (NICs). Packets? yes. Kilobytes per second? yes. Average packet sizes? yes. And more, because it simply cannot stop serving. 👑

---

✨ OPTIONS ✨

• -h — shows you a quick lil usage message. The help. The "what do I even type" moment. 🙈
• -v — shows the nicstat version. And when you pair it with -l, you get extra fields too. combo meal. 🍓
• -n — only shows stats for non-local interfaces, aka the non-loopback ones. bye bye loopback.
• -s — summary output mode. Just the amount of data received (read) and transmitted (written). short and sweet.
• -x — extended output. peek the OUTPUT section for the deets. 👀
• -U — shows read and write utilization statistics separately. This one affects the default format, the extended (-x) format, and the all (-a) format. Heads up: in the default format, the Sat statistic gets dropped so everything still fits in 80 columns. sacrifice made, aesthetic preserved. 💅
• -M — shows interface throughput in Mbps (megabits per second) instead of the default KB/s (kilobytes per second).

NOTE — interface statistics get reported to operating systems in bytes. nicstat genuinely does not know whether Ethernet or other hardware overheads are included in that statistic on each platform. so like, it's not being shady, it just doesn't know. 😭

• -p — parseable output format. One line per interface, in these formats (matching the default, -x, -t and -u options respectively):

time:In:rKB/s:wKB/s:rPk/s:wPk/s:%Util:Sat
time:In:rKB/s:wKB/s:rPk/s:wPk/s:%Util:Sat:IErr:OErr:Coll:NoCP:Defer
time:TCP:InKB:OutKB:InSeg:OutSeg:Reset:AttF:%ReTX:InConn:OutCon:Drops
time:UDP:InDG:OutDG:InErr:OutErr

where time is the number of seconds since midnight, Jan 1 1970 (UST), and the other fields are exactly as described in the OUTPUT section below.

NOTE — for parseable formats, throughput statistics are always in KB/s (kilobytes per second), even if you passed the -M flag. the flag does not win here. sorry bestie.

• -z — skips interfaces that had zero traffic during the sample period. if you did nothing, you get nothing. 🤷
• -t — shows TCP statistics.
• -u — shows UDP statistics.
• -a — equivalent to -x -t -u. the everything bagel. 🥯
• -l — just lists the interfaces. that's it. that's the whole job.
• -iinterface[,interface...] — shows stats for only the interface(s) you list. You can list multiple, separated by commas (,).
• -Sint:speed[fd|hd] — (Linux only 🌈) specify the speed — and optionally the duplex mode — of one or more interfaces. The speed(s) you give are in megabits/second. Duplex mode defaults to "full" unless you tack on a suffix starting with h or H. On Solaris, speed and duplex mode get obtained automatically from the ifspeed and link_duplex kstat values. no manual labour required. 💅
• -k — (Solaris only 🌞) searches for active network interfaces by looking for kstat link_state statistics with a value of 1. This is only useful on systems running Solaris 10 (or early releases of Solaris 11 Express) with Exclusive IP Zones, where the interfaces handed to an Exclusive IP Zone are not otherwise visible. If you're on Solaris 9 (or earlier), or Solaris 11 (or later), you do not need this option. skip it, it's not for you.

---

💜 OPERANDS 💜

• interval — the number of seconds between samples.
• count — how many times the statistics get repeated. If you don't specify a count, nicstat will repeat statistics indefinitely. forever. periodt. ♾️

---

👑 OUTPUT 👑

The fields of nicstat's display are:

• Time — the time corresponding to the end of the sample shown, in HH:MM:SS format (24-hour clock).
• Int — the interface name.
• rKB/s, InKB — kilobytes/second read (received).
• wKB/s, OutKB — kilobytes/second written (transmitted).
• rMbps, RdMbps — megabits/second read (received).
• wMbps, WrMbps — megabits/second written (transmitted).
• rPk/s, InSeg, InDG — packets (TCP segments, UDP datagrams)/second read (received).
• wPk/s, OutSeg, OutDG — packets (TCP segments, UDP datagrams)/second written (transmitted).
• rAvs — average size of packets read (received).
• wAvs — average size of packets written (transmitted).
• %Util — percentage utilization of the interface. For full-duplex interfaces, this is the greater of rKB/s or wKB/s as a percentage of the interface speed. For half-duplex interfaces, rKB/s and wKB/s get summed. math! 🔥
• %rUtil, %wUtil — percentage utilization for bytes read and written, respectively.
• Sat — saturation. This is 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's recommended to use the -x option to see more individual statistics (the ones mentioned below) when you're trying to diagnose a network issue.
• IErr — packets received that could not be processed because they contained errors.
• OErr — packets that were not successfully transmitted because of errors.
• Coll — Ethernet collisions during transmit.
• 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. 💀
• Defer — Defer Transmits. Packets without collisions where the first transmit attempt was delayed because the medium was busy.
• 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.
• 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.
• %ReTX — percentage of TCP segments retransmitted — that is, the number of TCP segments transmitted containing one or more previously transmitted octets.
• InConn — tcpPassiveOpens — the number of times that TCP connections have made a direct transition to the SYN-RCVD state from the LISTEN state.
• OutCon — tcpActiveOpens — the number of times that TCP connections have made a direct transition to the SYN-SENT state from the CLOSED state.
• Drops — tcpHalfOpenDrop + tcpListenDrop + tcpListenDropQ0.

tcpListenDrop and tcpListenDropQ0 — number of connections dropped from the completed connection queue and incomplete connection queue, respectively. tcpHalfOpenDrops — number of connections dropped after the initial SYN packet was received.

The first set of statistics printed are averages since system boot. If no interval operand is specified, or a count value of 1 is specified, this will be the only sample printed. one and done. ✨

---

💖 EXAMPLES 💖

Print average statistics from boot time to now only:

$ nicstat

Print statistics for all interfaces, every 3 seconds:

$ nicstat 3

Print statistics for all interfaces, every 5 seconds, finishing after 10 samples:

$ nicstat 5 10

Print statistics every 3 seconds, only for interfaces "hme0" and "hme1":

$ nicstat -i hme0,hme1 3

Print statistics for non-local interfaces, setting speed of "eth0" and "eth1" to 10mbps/half-duplex and 1000mbps/full-duplex, respectively:

$ nicstat -n -S eth0:10h,eth1:1000 5

---

🌈 SEE ALSO 🌈

netstat(1M) kstat(1M), kstat(3KSTAT), mibiisa(1M), ethtool(8)

"nicstat - the Solaris and Linux Network Monitoring Tool You Did Not Know You Needed" -http://blogs.oracle.com/timc/entry/nicstat_the_solaris_and_linux

---

🧚 NOTES 🧚

On Linux, the NoCP, Defer, TCP InKB, and TCP OutKB statistics are always reported as zero. don't come for them, they're just built different.

The way that saturation is reported is a best effort, because there's no standardized naming to capture all errors related to an interface's inability to receive or transmit a packet. Monitoring %Util and packet rates, plus actually understanding the specific NICs, may be more useful in judging whether you're nearing saturation. ngl, vibes + context > one number. 🫶

The -S option is provided for the Linux edition because nicstat requires super-user privilege to obtain speed and duplex mode information for interfaces. If you can't set up nicstat as setuid-root, there's a script named enicstat available — it uses the ethtool utility and then calls nicstat with an -S value. ethtool itself requires super-user privilege for this to work, so like, root or nothing, bestie. 🔐

---

and that's the whole page!! from the 4th Berkeley Distribution, dated 27 Jan 2014, and yeah the manual section is nicstat(1). go watch your NICs thrive. you're welcome. 💅💖✨