| Current File : //usr/man/man1m/ipstat.1m |
'\" te
.\" Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
.TH ipstat 1M "26 Nov 2012" "SunOS 5.11" "System Administration Commands"
.SH NAME
ipstat \- report statistics on IP traffic
.SH SYNOPSIS
.LP
.nf
\fBipstat\fR [\fB-cmnrt\fR] [\fB-a\fR \fIaddress\fR[\fI,address...\fR]] [\fB-A\fR \fIaddress\fR[\fI,address...\fR]]
[\fB-d d|u\fR] [\fB-i\fR \fIinterface\fR[\fI,interface...\fR]] [\fB-l\fR \fInlines\fR]
[\fB-p\fR \fIprotocol\fR[\fI,protocol...\fR]] [\fB-s\fR \fBkey\fR | \fB-S key\fR] [\fB-u R|K|M|G|T|P\fR]
[\fB-x\fR \fIopt\fR[\fI=val\fR][\fI,opt[=val]...\fR]] [\fBinterval\fR [\fIcount\fR]]
.fi
.SH DESCRIPTION
.sp
.LP
The \fBipstat\fR utility gathers and reports statistics on IP traffic based on the selected output mode and sort order. \fBipstat\fR provides options to gather and report statistics only on IP traffic matching specified source or destination address, interface, and higher layer protocol.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-a\fR \fIaddress[,address...]\fR\fR
.ad
.sp .6
.RS 4n
Filter on source address.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-A\fR \fIaddress[,address...]\fR\fR
.ad
.sp .6
.RS 4n
Filter on destination address.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-c\fR\fR
.ad
.sp .6
.RS 4n
Print new reports below previous reports instead of overprinting them.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-d\fR \fBd|u\fR\fR
.ad
.sp .6
.RS 4n
Print a timestamp for each report in either standard date format (-d d) or in seconds since epoch, that is, Unix time (-d u).
.RE
.sp
.ne 2
.mk
.na
\fB\fB-i\fR \fIinterface[,interface...]\fR\fR
.ad
.sp .6
.RS 4n
Filter on interface name.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-l\fR \fInlines\fR\fR
.ad
.sp .6
.RS 4n
The number of lines of data to output per report.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-m\fR\fR
.ad
.sp .6
.RS 4n
Produce machine-parsable output.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Show network addresses as numbers. Do not resolve IP addresses to hostnames.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-p\fR \fIprotocol[,protocol...]\fR\fR
.ad
.sp .6
.RS 4n
Filter on protocol name.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-r\fR\fR
.ad
.sp .6
.RS 4n
Only display data for packets being received.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-s\fR \fIkey\fR | \fB-S\fR \fIkey\fR\fR
.ad
.sp .6
.RS 4n
Sort in ascending (\fB-S\fR) or descending (\fB-s\fR) order by key, where the keys are as follows:
.RS +4
.TP
.ie t \(bu
.el o
source - source IP address
.RE
.RS +4
.TP
.ie t \(bu
.el o
dest - destination IP address
.RE
.RS +4
.TP
.ie t \(bu
.el o
proto - higher-level protocol
.RE
.RS +4
.TP
.ie t \(bu
.el o
int - interface name
.RE
.RS +4
.TP
.ie t \(bu
.el o
bytes - amount of data
.RE
By default, the data is sorted in descending order by bytes.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-t\fR\fR
.ad
.sp .6
.RS 4n
Only display data for packets being transmitted.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-u\fR \fBR|K|M|G|T|P\fR\fR
.ad
.sp .6
.RS 4n
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 \fIxy.zU\fR, where x, y, and z are numbers and U is the appropriate unit.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-x\fR \fIopt=val[,opt=val]\fR\fR
.ad
.sp .6
.RS 4n
Enable or modify a DTrace runtime option or D compiler option. The full list of options is found in \fBdtrace\fR(1M). For this utility, the \fBaggsize\fR and \fBaggrate\fR 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:
.sp
.in +2
.nf
Data dropped. Consider using '-x aggsize=8k' option.
.fi
.in -2
.sp
The default for \fBaggsize\fR is 512k. The default for \fBaggrate\fR is 1Hz.
.RE
.SH OUTPUT
.sp
.LP
The following list defines the column headings and the meanings of an \fBipstat\fR report:
.sp
.ne 2
.mk
.na
\fBSOURCE\fR
.ad
.RS 10n
.rt
The source IP address or hostname associated with this traffic.
.RE
.sp
.ne 2
.mk
.na
\fBDEST\fR
.ad
.RS 10n
.rt
The destination IP address or hostname associated with this traffic.
.RE
.sp
.ne 2
.mk
.na
\fBPROTO\fR
.ad
.RS 10n
.rt
The higher layer protocol associated with this traffic (TCP, UDP, SCTP,).
.RE
.sp
.ne 2
.mk
.na
\fBIFNAME\fR
.ad
.RS 10n
.rt
The name of the interface associated with this traffic.
.RE
.sp
.ne 2
.mk
.na
\fBBYTES\fR
.ad
.RS 10n
.rt
The rate of IP traffic 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 \fB-u\fR option can be used to specify a fixed unit for this number.
.RE
.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fIcount\fR\fR
.ad
.RS 12n
.rt
Specifies the number of times that the statistics are to be repeated. By default, \fBipstat\fR reports statistics until a termination signal is received.
.RE
.sp
.ne 2
.mk
.na
\fB\fIinterval\fR\fR
.ad
.RS 12n
.rt
Specifies the sampling interval in seconds; the default interval is 5 seconds.
.RE
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 5n
.rt
Successful completion.
.RE
.sp
.ne 2
.mk
.na
\fB\fB1\fR\fR
.ad
.RS 5n
.rt
An error occurred.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRReporting the Five Most Active IP Traffic Flows
.sp
.LP
The following command reports the five most active IP traffic flows.
.sp
.in +2
.nf
$ \fB\&./ipstat -l 5\fR
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
.fi
.in -2
.sp
.LP
\fBExample 2 \fRDisplaying a Timestamp
.sp
.LP
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.
.sp
.in +2
.nf
$ \fB\&./ipstat -d d -c 10\fR
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
.fi
.in -2
.sp
.LP
\fBExample 3 \fRSpecifying a DTrace Runtime Option
.sp
.LP
The following command sets the DTrace runtime option \fBaggsize\fR to 4K. As this is too small for the collected data, an error is displayed to indicate that data has been dropped.
.sp
.in +2
.nf
$ \fB\&./ipstat -c -x aggsize=4k 10\fR
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
.fi
.in -2
.sp
.LP
\fBExample 4 \fRGenerating Machine-Parsable Output
.sp
.LP
The following command displays the data in one-second intervals in a machine-parsable format with a Unix-format timestamp.
.sp
.in +2
.nf
$ \fB\&./ipstat -d u -m 1\fR
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
.fi
.in -2
.sp
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/core-os
.TE
.SH SEE ALSO
.sp
.LP
\fBdtrace\fR(1M), \fBtcpstat\fR(1M)
.SH NOTES
.sp
.LP
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.