System Administration Commands ipmpstat(1M)
NAME
ipmpstat - display IPMP subsystem status
SYNOPSIS
ipmpstat [-n] [-o field[,...] [-P] -a-g-i-p-t
DESCRIPTION
The ipmpstat command concisely displays information about
the IPMP subsystem. It supports five different output modes,
each of which provides a different view of the IPMP subsys-
tem (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 ipmpstat, with the exception of probe mode which
requires all privileges.
OPTIONS
The following options are supported:
-a
Display IPMP data address information ("address" output
mode).
-g
Display IPMP group information ("group" output mode).
-i
Display IP interface information ("interface" output
mode).
-n
Display IP addresses numerically, rather than attempting
to resolve them to hostnames. This option may be used in
any output mode.
-o field[,...]
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
SunOS 5.11 Last change: 10 Feb 2009 1
System Administration Commands ipmpstat(1M)
the selected output mode, described below. The special
field name all may be used to display all fields for a
given output mode.
-p
Display IPMP probe information ("probe" output mode).
-t
Display IPMP target information ("target" output mode).
-P
Display using a machine-parseable format, described
below. If this option is specified, an explicit list of
fields must be specified using the -o option.
OUTPUT MODES
The ipmpstat utility supports the output modes listed below.
Note that these modes map to some of the options described
above.
Address Mode
Address mode displays the state of all IPMP data
addresses on the system. The following output fields are
supported:
ADRES
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 GROUP 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.
STATE
The state of the address. Either up if the address
is IFUP (see ifconfig(1M)), or down if the address
is not IFUP.
SunOS 5.11 Last change: 10 Feb 2009 2
System Administration Commands ipmpstat(1M)
GROUP
The IPMP IP interface hosting the address.
INBOUND
The underlying IP interface that will receive pack-
ets 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).
OUTBOUND
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).
If -o is not specified, all output fields are displayed.
Group Mode
Group mode displays the state of all IPMP groups on the
system. The following output fields are supported:
GROUP
The IPMP IP interface name associated with the
information. For the anonymous group (see
in.mpathd(1M)), this field will be empty.
GROUPNAME
The IPMP group name. For the anonymous group, this
field will be empty.
STATE
The state of the group:
SunOS 5.11 Last change: 10 Feb 2009 3
System Administration Commands ipmpstat(1M)
ok All interfaces in the group are usable.
degraded Some (but not all) interfaces in the
group are usable.
failed No interfaces in the group are usable.
FDT
The probe-based failure detection time. If probe-
based failure detection is disabled, this field will
be empty.
INTERFACES
The list of underlying IP interfaces in the group.
The list is divided into three parts:
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.
2. INACTIVE interfaces are listed next and
enclosed in parenthesis. INACTIVE inter-
faces are those that are functioning, but
not being used according to administrative
policy.
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,
FAILED or OFLINE).
If -o is not specified, all output fields are displayed.
Interface Mode
Interface mode displays the state of all IP interfaces
that are tracked by in.mpathd on the system. The follow-
ing output fields are supported:
INTERFACE
The IP interface name associated with the
SunOS 5.11 Last change: 10 Feb 2009 4
System Administration Commands ipmpstat(1M)
information.
ACTIVE
Either yes or no, depending on whether the IP inter-
face is being used by the system for IP data
traffic.
GROUP
The IPMP IP interface associated with the IP inter-
face. For IP interfaces in the anonymous group (see
in.mpathd(1M)), this field will be empty.
FLAGS
Assorted information about the IP interface:
i Unusable due to being INACTIVE.
s Marked STANDBY.
m Nominated to send/receive IPv4 multicast for
its IPMP group.
b Nominated to send/receive IPv4 broadcast for
its IPMP group.
M Nominated to send/receive IPv6 multicast for
its IPMP group.
d Unusable due to being down.
h Unusable due to being brought OFLINE by
in.mpathd because of a duplicate hardware
address.
LINK
The state of link-based failure detection:
SunOS 5.11 Last change: 10 Feb 2009 5
System Administration Commands ipmpstat(1M)
up
The link is up.
down
The link is down.
unknown
The network driver does not report link state
changes.
PROBE
The state of probe-based failure detection:
ok
Probes detect no problems.
failed
Probes detect failure.
unknown
Probes cannot be sent since no suitable probe
targets are known.
disabled
Probes have been disabled because a unique IP
test address has not been configured.
STATE
The overall state of the interface:
ok
The interface is online and functioning properly
based on the configured failure detection
SunOS 5.11 Last change: 10 Feb 2009 6
System Administration Commands ipmpstat(1M)
methods.
failed
The interface is online but has a link state of
down or a probe state of failed.
offline
The interface is offline.
unknown
The interface is online but may or may not be
functioning because the configured failure
detection methods are in unknown states.
If -o is not specified, all output fields are displayed.
Probe Mode
Probe mode displays information about the probes being
sent by in.mpathd. Unlike other output modes, this mode
runs until explicitly terminated using Ctrl-C. The fol-
lowing output fields are supported:
TIME
The time the probe was sent, relative to when
ipmpstat was started. If the probe was sent prior to
starting ipmpstat, the time will be negative.
PROBE
An identifier representing the probe. The identifier
will start at zero and will monotonically increment
for each probe sent by in.mpathd over a given inter-
face. To enable more detailed analysis by packet
monitoring tools, this identifier matches the
icmpseq field of the ICMP probe packet.
INTERFACE
The IP interface the probe was sent on.
SunOS 5.11 Last change: 10 Feb 2009 7
System Administration Commands ipmpstat(1M)
TARGET
The hostname (or IP address) of the target the probe
was sent to.
NETRT
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 in.mpathd has concluded that the probe has been
lost, this field will be empty.
RT
The total round-trip-time for the probe. This is the
time between when in.mpathd starts executing the
code to send the probe, and when it completes pro-
cessing the ack. If in.mpathd 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.
RTAVG
The average round-trip-time to TARGET over INTER-
FACE. This aids identification of slow targets. If
there is insufficient data to calculate the average,
this field will be empty.
RTDEV
The standard deviation for the round-trip-time to
TARGET over INTERFACE. This aids identification of
jittery targets. If there is insufficient data to
calculate the standard deviation, this field will be
empty.
If -o is not specified, all fields except for RTAVG and
RTDEV are displayed.
Target Mode
Target mode displays IPMP probe target information. The
following output fields are supported:
SunOS 5.11 Last change: 10 Feb 2009 8
System Administration Commands ipmpstat(1M)
INTERFACE
The IP interface name associated with the informa-
tion.
MODE
The probe target discovery mode:
routes Probe targets found by means of the
routing table.
multicast Probe targets found by means of multi-
cast ICMP probes.
disabled Probe-based failure detection is dis-
abled.
TESTADR
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.
TARGETS
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.
If -o is not specified, all output fields are displayed.
OUTPUT FORMAT
By default, ipmpstat 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
-- (double hyphens), and other visual aids are used. If the
SunOS 5.11 Last change: 10 Feb 2009 9
System Administration Commands ipmpstat(1M)
value for a field cannot be determined, its value will be
displayed as "?" and a diagnostic message will be output to
standard error.
Machine-parseable format also uses a tabular format, but is
designed to be efficient to programmatically parse. Specifi-
cally, machine-parseable format differs from human-friendly
format in the following ways:
o No headers are displayed.
o Fields with empty values yield no output, rather
than showing --.
o Fields are separated by a single colon (:), rather
than variable amounts of whitespace.
o If multiple fields are requested, and a literal :
or a backslash (\) occur in a field's value, they
are escaped by prefixing them with \.
EXAMPLES
Example 1 Obtaining Failure Detection Time of a Specific
Interface
The following code uses the machine-parseable output format
to create a ksh function that outputs the failure detection
time of a given IPMP IP interface:
getfdt() {
ipmpstat -gP -o group,fdt while IFS=: read group fdt; do
[ "$group" = "$1" ] && { echo "$fdt"; return; }
done
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
/usr/sbin/ipmpstat:
SunOS 5.11 Last change: 10 Feb 2009 10
System Administration Commands ipmpstat(1M)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
Interface Stability Committed
Machine-Parseable Format Committed
Human-Friendly Format Not-an-Interface
/sbin/ipmpstat is not a Committed interface.
SEE ALSO
ifmpadm(1M), ifconfig(1M), in.mpathd(1M), attributes(5)
SunOS 5.11 Last change: 10 Feb 2009 11
|
