'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH IPMPSTAT 1M "Feb 10, 2009"
.SH NAME
ipmpstat \- display IPMP subsystem status
.SH SYNOPSIS
.LP
.nf
\fBipmpstat\fR [\fB-n\fR] [\fB-o\fR \fIfield\fR[,...] [\fB-P\fR]] \fB-a\fR|\fB-g\fR|\fB-i\fR|\fB-p\fR|\fB-t\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBipmpstat\fR command concisely displays information about the IPMP
subsystem. It supports five different output modes, each of which provides a
different view of the IPMP subsystem (address, group, interface, probe, and
target), described below. At most one output mode may be specified per
invocation, and the displayed information is guaranteed to be self-consistent.
It also provides a parseable output format which may be used by scripts to
examine the state of the IPMP subsystem. Only basic privileges are needed to
invoke \fBipmpstat\fR, with the exception of probe mode which requires all
privileges.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
Display IPMP data address information ("address" output mode).
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.sp .6
.RS 4n
Display IPMP group information ("group" output mode).
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.sp .6
.RS 4n
Display IP interface information ("interface" output mode).
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Display IP addresses numerically, rather than attempting to resolve them to
hostnames. This option may be used in any output mode.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIfield\fR[,...]\fR
.ad
.sp .6
.RS 4n
Display only the specified output fields, in order. The list of field names is
case-insensitive and comma-separated. The field names that are supported depend
on the selected output mode, described below. The special field name \fBall\fR
may be used to display all fields for a given output mode.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.sp .6
.RS 4n
Display IPMP probe information ("probe" output mode).
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.sp .6
.RS 4n
Display IPMP target information ("target" output mode).
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.sp .6
.RS 4n
Display using a machine-parseable format, described below. If this option is
specified, an explicit list of fields must be specified using the \fB-o\fR
option.
.RE

.SH OUTPUT MODES
.sp
.LP
The \fBipmpstat\fR utility supports the output modes listed below. Note that
these modes map to some of the options described above.
.sp
.ne 2
.na
\fBAddress Mode\fR
.ad
.sp .6
.RS 4n
Address mode displays the state of all IPMP data addresses on the system. The
following output fields are supported:
.sp
.ne 2
.na
\fB\fBADDRESS\fR\fR
.ad
.sp .6
.RS 4n
The hostname (or IP address) associated with the information. Note that because
duplicate down addresses may exist, the address must be taken together with the
\fBGROUP\fR to form a unique identity. For a given IPMP group, if duplicate
addresses exist, at most one will be displayed, and an up address will always
take precedence.
.RE

.sp
.ne 2
.na
\fB\fBSTATE\fR\fR
.ad
.sp .6
.RS 4n
The state of the address. Either \fBup\fR if the address is \fBIFF_UP\fR (see
\fBifconfig\fR(1M)), or \fBdown\fR if the address is not \fBIFF_UP\fR.
.RE

.sp
.ne 2
.na
\fB\fBGROUP\fR\fR
.ad
.sp .6
.RS 4n
The IPMP IP interface hosting the address.
.RE

.sp
.ne 2
.na
\fB\fBINBOUND\fR\fR
.ad
.sp .6
.RS 4n
The underlying IP interface that will receive packets for this address. This
may change in response to external events such as IP interface failure. If this
field is empty, then the system will not accept IP packets sent to this address
(for example, because the address is down or because there are no active IP
interfaces left in the IPMP group).
.RE

.sp
.ne 2
.na
\fB\fBOUTBOUND\fR\fR
.ad
.sp .6
.RS 4n
The underlying IP interfaces that will send packets using this source address.
This may change in response to external events such as IP interface failure. If
this field is empty, then the system will not send packets with this address as
a source (for example, because the address is down or because there are no
active IP interfaces left in the IPMP group).
.RE

If \fB-o\fR is not specified, all output fields are displayed.
.RE

.sp
.ne 2
.na
\fBGroup Mode\fR
.ad
.sp .6
.RS 4n
Group mode displays the state of all IPMP groups on the system. The following
output fields are supported:
.sp
.ne 2
.na
\fB\fBGROUP\fR\fR
.ad
.sp .6
.RS 4n
The IPMP IP interface name associated with the information. For the anonymous
group (see \fBin.mpathd\fR(1M)), this field will be empty.
.RE

.sp
.ne 2
.na
\fB\fBGROUPNAME\fR\fR
.ad
.sp .6
.RS 4n
The IPMP group name. For the anonymous group, this field will be empty.
.RE

.sp
.ne 2
.na
\fB\fBSTATE\fR\fR
.ad
.sp .6
.RS 4n
The state of the group:
.sp
.ne 2
.na
\fB\fBok\fR\fR
.ad
.RS 12n
All interfaces in the group are usable.
.RE

.sp
.ne 2
.na
\fB\fBdegraded\fR\fR
.ad
.RS 12n
Some (but not all) interfaces in the group are usable.
.RE

.sp
.ne 2
.na
\fB\fBfailed\fR\fR
.ad
.RS 12n
No interfaces in the group are usable.
.RE

.RE

.sp
.ne 2
.na
\fB\fBFDT\fR\fR
.ad
.sp .6
.RS 4n
The probe-based failure detection time. If probe-based failure detection is
disabled, this field will be empty.
.RE

.sp
.ne 2
.na
\fB\fBINTERFACES\fR\fR
.ad
.sp .6
.RS 4n
The list of underlying IP interfaces in the group. The list is divided into
three parts:
.RS +4
.TP
1.
Active interfaces are listed first and not enclosed in any brackets or
parenthesis. Active interfaces are those being used by the system to send or
receive data traffic.
.RE
.RS +4
.TP
2.
\fBINACTIVE\fR interfaces are listed next and enclosed in parenthesis.
\fBINACTIVE\fR interfaces are those that are functioning, but not being used
according to administrative policy.
.RE
.RS +4
.TP
3.
Unusable interfaces are listed last and enclosed in brackets. Unusable
interfaces are those that cannot be used at all in their present configuration
(for example, \fBFAILED\fR or \fBOFFLINE\fR).
.RE
.RE

If \fB-o\fR is not specified, all output fields are displayed.
.RE

.sp
.ne 2
.na
\fBInterface Mode\fR
.ad
.sp .6
.RS 4n
Interface mode displays the state of all IP interfaces that are tracked by
\fBin.mpathd\fR on the system. The following output fields are supported:
.sp
.ne 2
.na
\fB\fBINTERFACE\fR\fR
.ad
.sp .6
.RS 4n
The IP interface name associated with the information.
.RE

.sp
.ne 2
.na
\fB\fBACTIVE\fR\fR
.ad
.sp .6
.RS 4n
Either \fByes\fR or \fBno\fR, depending on whether the IP interface is being
used by the system for IP data traffic.
.RE

.sp
.ne 2
.na
\fB\fBGROUP\fR\fR
.ad
.sp .6
.RS 4n
The IPMP IP interface associated with the IP interface. For IP interfaces in
the anonymous group (see \fBin.mpathd\fR(1M)), this field will be empty.
.RE

.sp
.ne 2
.na
\fB\fBFLAGS\fR\fR
.ad
.sp .6
.RS 4n
Assorted information about the IP interface:
.sp
.ne 2
.na
\fB\fBi\fR\fR
.ad
.RS 5n
Unusable due to being \fBINACTIVE\fR.
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
Marked \fBSTANDBY\fR.
.RE

.sp
.ne 2
.na
\fB\fBm\fR\fR
.ad
.RS 5n
Nominated to send/receive IPv4 multicast for its IPMP group.
.RE

.sp
.ne 2
.na
\fB\fBb\fR\fR
.ad
.RS 5n
Nominated to send/receive IPv4 broadcast for its IPMP group.
.RE

.sp
.ne 2
.na
\fB\fBM\fR\fR
.ad
.RS 5n
Nominated to send/receive IPv6 multicast for its IPMP group.
.RE

.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
Unusable due to being \fBdown\fR.
.RE

.sp
.ne 2
.na
\fB\fBh\fR\fR
.ad
.RS 5n
Unusable due to being brought \fBOFFLINE\fR by \fBin.mpathd\fR because of a
duplicate hardware address.
.RE

.RE

.sp
.ne 2
.na
\fB\fBLINK\fR\fR
.ad
.sp .6
.RS 4n
The state of link-based failure detection:
.sp
.ne 2
.na
\fB\fBup\fR\fR
.ad
.sp .6
.RS 4n
The link is up.
.RE

.sp
.ne 2
.na
\fB\fBdown\fR\fR
.ad
.sp .6
.RS 4n
The link is down.
.RE

.sp
.ne 2
.na
\fB\fBunknown\fR\fR
.ad
.sp .6
.RS 4n
The network driver does not report link state changes.
.RE

.RE

.sp
.ne 2
.na
\fB\fBPROBE\fR\fR
.ad
.sp .6
.RS 4n
The state of probe-based failure detection:
.sp
.ne 2
.na
\fB\fBok\fR\fR
.ad
.sp .6
.RS 4n
Probes detect no problems.
.RE

.sp
.ne 2
.na
\fB\fBfailed\fR\fR
.ad
.sp .6
.RS 4n
Probes detect failure.
.RE

.sp
.ne 2
.na
\fB\fBunknown\fR\fR
.ad
.sp .6
.RS 4n
Probes cannot be sent since no suitable probe targets are known.
.RE

.sp
.ne 2
.na
\fB\fBdisabled\fR\fR
.ad
.sp .6
.RS 4n
Probes have been disabled because a unique IP test address has not been
configured.
.RE

.RE

.sp
.ne 2
.na
\fB\fBSTATE\fR\fR
.ad
.sp .6
.RS 4n
The overall state of the interface:
.sp
.ne 2
.na
\fB\fBok\fR\fR
.ad
.sp .6
.RS 4n
The interface is online and functioning properly based on the configured
failure detection methods.
.RE

.sp
.ne 2
.na
\fB\fBfailed\fR\fR
.ad
.sp .6
.RS 4n
The interface is online but has a link state of \fBdown\fR or a probe state of
\fBfailed\fR.
.RE

.sp
.ne 2
.na
\fB\fBoffline\fR\fR
.ad
.sp .6
.RS 4n
The interface is offline.
.RE

.sp
.ne 2
.na
\fB\fBunknown\fR\fR
.ad
.sp .6
.RS 4n
The interface is online but may or may not be functioning because the
configured failure detection methods are in \fBunknown\fR states.
.RE

.RE

If \fB-o\fR is not specified, all output fields are displayed.
.RE

.sp
.ne 2
.na
\fBProbe Mode\fR
.ad
.sp .6
.RS 4n
Probe mode displays information about the probes being sent by \fBin.mpathd\fR.
Unlike other output modes, this mode runs until explicitly terminated using
\fBCtrl-C\fR. The following output fields are supported:
.sp
.ne 2
.na
\fB\fBTIME\fR\fR
.ad
.sp .6
.RS 4n
The time the probe was sent, relative to when \fBipmpstat\fR was started. If
the probe was sent prior to starting \fBipmpstat\fR, the time will be negative.
.RE

.sp
.ne 2
.na
\fB\fBPROBE\fR\fR
.ad
.sp .6
.RS 4n
An identifier representing the probe. The identifier will start at zero and
will monotonically increment for each probe sent by \fBin.mpathd\fR over a
given interface. To enable more detailed analysis by packet monitoring tools,
this identifier matches the \fBicmp_seq\fR field of the ICMP probe packet.
.RE

.sp
.ne 2
.na
\fB\fBINTERFACE\fR\fR
.ad
.sp .6
.RS 4n
The IP interface the probe was sent on.
.RE

.sp
.ne 2
.na
\fB\fBTARGET\fR\fR
.ad
.sp .6
.RS 4n
The hostname (or IP address) of the target the probe was sent to.
.RE

.sp
.ne 2
.na
\fB\fBNETRTT\fR\fR
.ad
.sp .6
.RS 4n
The network round-trip-time for the probe. This is the time between when the IP
module sends the probe and when the IP module receives the acknowledgment. If
\fBin.mpathd\fR has concluded that the probe has been lost, this field will be
empty.
.RE

.sp
.ne 2
.na
\fB\fBRTT\fR\fR
.ad
.sp .6
.RS 4n
The total round-trip-time for the probe. This is the time between when
\fBin.mpathd\fR starts executing the code to send the probe, and when it
completes processing the \fBack\fR. If \fBin.mpathd\fR has concluded that the
probe has been lost, this field will be empty. Spikes in the total round-trip
time that are not present in the network round-trip time indicate that the
local system itself is overloaded.
.RE

.sp
.ne 2
.na
\fB\fBRTTAVG\fR\fR
.ad
.sp .6
.RS 4n
The average round-trip-time to \fBTARGET\fR over \fBINTERFACE\fR. This aids
identification of slow targets. If there is insufficient data to calculate the
average, this field will be empty.
.RE

.sp
.ne 2
.na
\fB\fBRTTDEV\fR\fR
.ad
.sp .6
.RS 4n
The standard deviation for the round-trip-time to \fBTARGET\fR over
\fBINTERFACE\fR. This aids identification of jittery targets. If there is
insufficient data to calculate the standard deviation, this field will be
empty.
.RE

If \fB-o\fR is not specified, all fields except for \fBRTTAVG\fR and
\fBRTTDEV\fR are displayed.
.RE

.sp
.ne 2
.na
\fBTarget Mode\fR
.ad
.sp .6
.RS 4n
Target mode displays IPMP probe target information. The following output fields
are supported:
.sp
.ne 2
.na
\fB\fBINTERFACE\fR\fR
.ad
.sp .6
.RS 4n
The IP interface name associated with the information.
.RE

.sp
.ne 2
.na
\fB\fBMODE\fR\fR
.ad
.sp .6
.RS 4n
The probe target discovery mode:
.sp
.ne 2
.na
\fB\fBroutes\fR\fR
.ad
.RS 13n
Probe targets found by means of the routing table.
.RE

.sp
.ne 2
.na
\fB\fBmulticast\fR\fR
.ad
.RS 13n
Probe targets found by means of multicast ICMP probes.
.RE

.sp
.ne 2
.na
\fB\fBdisabled\fR\fR
.ad
.RS 13n
Probe-based failure detection is disabled.
.RE

.RE

.sp
.ne 2
.na
\fB\fBTESTADDR\fR\fR
.ad
.sp .6
.RS 4n
The hostname (or IP address) that will be used for sending and receiving
probes. If a unique test address has not been configured, this field will be
empty. Note that if an IP interface is configured with both IPv4 and IPv6 test
addresses, probe target information will be displayed separately for each test
address.
.RE

.sp
.ne 2
.na
\fB\fBTARGETS\fR\fR
.ad
.sp .6
.RS 4n
A space-separated list of probe target hostnames (or IP addresses), in firing
order. If no probe targets could be found, this field will be empty.
.RE

If \fB-o\fR is not specified, all output fields are displayed.
.RE

.SH OUTPUT FORMAT
.sp
.LP
By default, \fBipmpstat\fR uses a human-friendly tabular format for its output
modes, where each row contains one or more fields of information about a given
object, which is in turn uniquely identified by one or more of those fields. In
this format, a header identifying the fields is displayed above the table (and
after each screenful of information), fields are separated by whitespace, empty
fields are represented by \fB--\fR (double hyphens), and other visual aids are
used. If the value for a field cannot be determined, its value will be
displayed as "\fB?\fR" and a diagnostic message will be output to standard
error.
.sp
.LP
Machine-parseable format also uses a tabular format, but is designed to be
efficient to programmatically parse. Specifically, machine-parseable format
differs from human-friendly format in the following ways:
.RS +4
.TP
.ie t \(bu
.el o
No headers are displayed.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Fields with empty values yield no output, rather than showing \fB--\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Fields are separated by a single colon (\fB:\fR), rather than variable amounts
of whitespace.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If multiple fields are requested, and a literal \fB:\fR or a backslash
(\fB\e\fR) occur in a field's value, they are escaped by prefixing them with
\fB\e\fR\&.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRObtaining Failure Detection Time of a Specific Interface
.sp
.LP
The following code uses the machine-parseable output format to create a
\fBksh\fR function that outputs the failure detection time of a given IPMP IP
interface:

.sp
.in +2
.nf
     getfdt() {
         ipmpstat -gP -o group,fdt | while IFS=: read group fdt; do
             [[ "$group" = "$1" ]] && { echo "$fdt"; return; }
         done
     }
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.LP
\fB/usr/sbin/ipmpstat\fR:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
Machine-Parseable Format	Committed
_
Human-Friendly Format	Not-an-Interface
.TE

.sp
.LP
\fB/sbin/ipmpstat\fR is not a Committed interface.
.SH SEE ALSO
.sp
.LP
\fBif_mpadm\fR(1M), \fBifconfig\fR(1M), \fBin.mpathd\fR(1M),
\fBattributes\fR(5)