Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ipstat(8)

Name

ipstat - report statistics on IP traffic

Synopsis

ipstat [-cegkLmnrt] [-a 
address[,address...]] [-A 
address[,address...]]
[-d d|u] [-E all|event[,event...]] [-i interface[
,interface...]] [-l nlines]
	    [-p protocol[,protocol...
]] [-s key | -S key] [
-u R|K|M|G|T|P]
	    [-x opt[=val][
,opt[=val]...]] [interval [count]]

Description

The ipstat utility gathers and reports statistics on IP traffic, IP packet drops and IP related MIB events based on the selected output mode and sort order. ipstat provides options to gather and report statistics only on IP traffic or events matching specified source or destination address, interface, and higher layer protocol.

Options

The following options are supported:

–a address[,address...]

Filter on source address.

–A address[,address...]

Filter on destination address.

–c

Print new reports below previous reports instead of overprinting them.

–d d|u

Print a timestamp for each report in either standard date format (–d d) or in seconds since epoch, that is, Unix time (–d u).

–e

Display packet drop events.

–E all|event[,event...]

Display comma-separated list of IP-related MIB events or all of them. Event names are case-insensitive. For a full set of available events, run the ipstat -L command.

–g

Group by traffic flow.

–i interface[,interface...]

Filter on interface name.

–k

Display statistics in packets.

–l nlines

The number of lines of data to output per report.

–L

List all available IP-related MIB events.

–m

Produce machine-parsable output.

–n

Show network addresses as numbers. Do not resolve IP addresses to hostnames.

–p protocol[,protocol...]

Filter on protocol name.

–r

Only display data for packets being received.

–s key | –S key

Sort in ascending (–S) or descending (–s) order by key, where the keys are as follows:

  • source - source IP address

  • dest - destination IP address

  • proto - higher-level protocol

  • int - interface name

  • bytes - amount of data

By default, the data of IP traffic is sorted in descending order by bytes. The data of events/drops is grouped by flow tuples in descending order.

–t

Only display data for packets being transmitted.

–u R|K|M|G|T|P

If used, allows choosing the unit in which to display all statistics, for example, R: raw count, K: Kilobits, M:Megabits, T: Terabits, P: Petabits. If not used, then different units, as appropriate, are used to display the statistics, using the format xy.zU, where x, y, and z are numbers and U is the appropriate unit.

–x opt=val[,opt=val]

Enable or modify a DTrace runtime option or D compiler option. The full list of options is found in dtrace(8). For this utility, the aggsize and aggrate options will be most useful. The utility will display an error message similar to the following if you need to modify one of these options:

Data dropped.  Consider using '-x aggsize=8k' option.

The default for aggsize is 512k. The default for aggrate is 1Hz.

Output

The following list defines the column headings and the meanings of an ipstat report:

SOURCE

The source IP address or hostname associated with this traffic.

DEST

The destination IP address or hostname associated with this traffic.

PROTO

The higher layer protocol associated with this traffic (TCP, UDP, SCTP,).

IFNAME

The name of the interface associated with this traffic.

RATE

The rate of IP traffic or IP packet drops over the sampling interval. The rate is shown in bytes, but may be changed to packets with –k. In non-parsable mode, the rate will be scaled as necessary (optionally adjusted per –u option) and shown with K, M, G, T, or P suffixes. In parsable mode, an unscaled rate is always shown.

EVENT

The name of IP-related events.

ERR-BYTES

The rate of IP packet drops over the sampling interval. In regular output, the rate is reported in bytes (no suffix), kilobytes (K), megabytes (M), gigabytes (G), terabytes (T), or petabytes (P) per second. In machine-parsable output, the rate is given in bytes per second. The –u option can be used to specify a fixed unit for this number.

PKTS

The packet rate of IP traffic over the sampling interval. In regular output, the rate is reported in packets per second (no suffix), kilo packets per second (K), mega packets per second(M), giga packets per second (G), tera packets per second (T), or peta packets per second (P). In machine-parsable output, the rate is given in packets per second. The –u option can be used to specify a fixed unit for this number.

ERR-PKTS

The rate of IP packet drops over the sampling interval. In regular output, the rate is reported in packets per second (no suffix), kilo packets per second (K), mega packets per second (M), giga packets per second (G), tera packets per second (T), or peta packets per second (P). In machine-parsable output, the rate is given in packets per second. The –u option can be used to specify a fixed unit for this number.

EVENT

The name of IP-related events.

Operands

The following operands are supported:

count

Specifies the number of times that the statistics are to be repeated. By default, ipstat reports statistics until a termination signal is received.

interval

Specifies the sampling interval in seconds; the default interval is 5 seconds.

Exit Status

The following exit values are returned:

0

Successful completion.

1

An error occurred.

Examples

Example 1 Reporting the Five Most Active IP Traffic Flows

The following command reports the five most active IP traffic flows.

$ ./ipstat -l 5
SOURCE                     DEST                       PROTO    IFNAME     BYTES
adc-twvpn-2.oraclevpn.com  duff.cs.uni.edu            UDP      net0        6.6K
inet-bip2v-10.oracle.com   bud.bang.uni.edu           TCP      tun0        6.1K
duff.cs.uni.edu            adc-twvpn-2.oraclevpn.com  UDP      net0      964.0 
bud.bang.uni.edu           inet-bip2v-10.oracle.com   TCP      tun0      563.0 
coors.foo.uni.edu          255.255.255.255            UDP      net0       66.0 
Total: bytes in: 12.6K bytes out:  2.2K
Example 2 Displaying a Timestamp

The following command reports the top IP traffic with a timestamp in standard date format. New reports are printed below previous reports, and the interval is set to ten seconds.

$ ./ipstat -d d -c 10
Monday, March 26, 2012 08:34:07 PM EDT
SOURCE                     DEST                       PROTO    IFNAME     BYTES
adc-twvpn-2.oraclevpn.com  duff.cs.uni.edu            UDP      net0       15.1K
inet-bip2v-10.oracle.com   bud.bang.uni.edu           TCP      tun0       13.9K
duff.cs.uni.edu            adc-twvpn-2.oraclevpn.com  UDP      net0        2.4K
bud.bang.uni.edu           inet-bip2v-10.oracle.com   TCP      tun0        1.5K
coors.foo.uni.edu          255.255.255.255            UDP      net0       66.0 
bigip-stbeehive-adc.oracle bud.bang.uni.edu           TCP      tun0       29.0 
bud.bang.uni.edu           bigip-stbeehive-adc.oracle TCP      tun0       20.0 
Total: bytes in: 29.1K bytes out:  3.8K

Example 3 Specifying a DTrace Runtime Option

The following command sets the DTrace runtime option aggsize to 4K. As this is too small for the collected data, an error is displayed to indicate that data has been dropped.

$ ./ipstat -c -x aggsize=4k 10
SOURCE                     DEST                       PROTO    IFNAME     BYTES
adc-twvpn-3.oraclevpn.com  duff.cs.uni.edu            UDP      net0       11.1K
adc-proxy.oracle.com       stella.baz.uni.edu         TCP      tun0       10.3K
duff.cs.uni.edu            adc-twvpn-3.oraclevpn.com  UDP      net0      907.0 
stella.baz.uni.edu         adc-proxy.oracle.com       TCP      tun0      505.0 
coors.foo.uni.edu          255.255.255.255            UDP      net0       66.0 
duff-lite.cs.uni.edu       182.168.1.255              UDP      net0       22.0 
duff.cs.uni.edu            adc-twvpn-3.oraclevpn.com  TCP      net0        7.0 
adc-twvpn-3.oraclevpn.com  duff.cs.uni.edu            TCP      net0        7.0 
coors.foo.uni.edu          169.254.1.255              UDP      net0        2.0 
Data dropped.  Consider using '-x aggsize=8k' option.
Total: bytes in: 21.5K bytes out:  2.1K
Example 4 Generating Machine-Parsable Output

The following command displays the data in one-second intervals in a machine-parsable format with a Unix-format timestamp.

$ ./ipstat -d u -m 1
timestamp:1333141886
duff.cs.uni.edu:duff-dry.cs.uni.edu:TCP:net0:144
duff-dry.cs.uni.edu:duff.cs.uni.edu:SCTP:net0:128
duff.cs.uni.edu:duff-dry.cs.uni.edu:SCTP:net0:128
duff-dry.cs.uni.edu:duff.cs.uni.edu:TCP:net0:80
coors.foo.uni.edu:169.254.1.255:UDP:net0:40
total:280:240
timestamp:1333141887
duff.cs.uni.edu:duff-dry.cs.uni.edu:TCP:net0:144
duff.cs.uni.edu:duff-dry.cs.uni.edu:SCTP:net0:128
duff-dry.cs.uni.edu:duff.cs.uni.edu:SCTP:net0:104
duff-dry.cs.uni.edu:duff.cs.uni.edu:TCP:net0:80
total:228:228
Example 5 Reporting all IP Packet Drops

The following command reports all IP packet drops. New reports are printed below previous reports, and the interval is set to ten seconds.

$ ./ipstat -e -k -c 10
SOURCE                     DEST                    PROTO    IFNAME      ERR-PKTS    EVENT
fe80::214:4fff:fe40:d0c8   ff02::202               IP        net0       6           drop-in
impel                      example.net             IGMP      net0       1           drop-in
www.oracle.com             example.net             IGMP      net0       1           drop-in
Total: packets in:  8 packets out:  0
Example 6 Reporting Statistics for Some IP Events

The following command reports the traffic flow for events including ipInMcastPkts, ipOutRequest, and ipFragOKs.

$ ./ipstat -E ipInMcastPkts,ipoutRequests,ipfragoks
SOURCE                     DEST                       PROTO    IFNAME  PKTS          EVENT
impel                      dhcp-santaclara18-3fl-west TCP      net0       2  ipOutRequests
fe80::a00:20ff:fec8:ca69   ff02::1                    ICMPv6   net0       1  ipInMcastPkts
www.oracle.com             example.net                UDP      net0       1  ipInMcastPkts
impel                      www.oracle.com             UDP      net0       1  ipOutRequests
Total packets: 5
Example 7 Reporting all IP Events
$ ./ipstat -E all
SOURCE                     DEST                       PROTO    IFNAME  PKTS          EVENT
impel                      www.oracle.com             TCP      net0       5   ipOutRequests
www.oracle.com             impel                      TCP      net0       5   ipInReceives
www.oracle.com             impel                      TCP      net0       4   ipInDelivers
www.oracle.com             impel                      TCP      net0       1   ipInDiscards
10.5.238.52                10.255.255.255             UDP      net0       2   ipInReceives
10.5.238.52                10.255.255.255             UDP      net0       2   ipInDelivers
10.5.238.52                10.255.255.255             UDP      net0       2   ipInBcastPkts
Total packets: 21

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os

See Also

dtrace(8), netstat(8), tcpstat(8)

Notes

The data presented are not sampled data. The values represent an accurate count of the IP traffic. In the event that data are dropped, an error message will be displayed to indicate this.