ipmpstat - display IPMP subsystem status
ipmpstat [-n] [-o field[,...] [-P]] -a|-g|-i|-p|-t
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 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 parsable 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.
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 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-parsable format, described below.
If this option is specified, an explicit list of fields must be specified
using the -o option.
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:
ADDRESS
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
IFF_UP (see
ifconfig(8)), or
down if the address is
not
IFF_UP.
GROUP
The IPMP IP interface hosting the address.
INBOUND
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).
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(8)), 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:
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 interfaces 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 OFFLINE).
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 following output
fields are supported:
INTERFACE
The IP interface name associated with the
information.
ACTIVE
Either yes or no, depending on whether the
IP interface is being used by the system for IP data traffic.
GROUP
The IPMP IP interface associated with the IP interface.
For IP interfaces in the anonymous group (see
in.mpathd(8)), 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 OFFLINE by
in.mpathd because of a duplicate hardware address.
LINK
The state of link-based failure detection:
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 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 following 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 interface. To enable more detailed analysis by
packet monitoring tools, this identifier matches the icmp_seq field of
the ICMP probe packet.
INTERFACE
The IP interface the probe was sent on.
TARGET
The hostname (or IP address) of the target the probe was
sent to.
NETRTT
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.
RTT
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 processing 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.
RTTAVG
The average round-trip-time to TARGET over
INTERFACE. This aids identification of slow targets. If there is
insufficient data to calculate the average, this field will be empty.
RTTDEV
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 RTTAVG
and RTTDEV are displayed.
Target Mode
Target mode displays IPMP probe target information. The
following output fields are supported:
INTERFACE
The IP interface name associated with the
information.
MODE
The probe target discovery mode:
routes
Probe targets found by means of the routing table.
multicast
Probe targets found by means of multicast ICMP
probes.
disabled
Probe-based failure detection is disabled.
TESTADDR
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.
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 value for
a field cannot be determined, its value will be displayed as
"?" and a diagnostic message will be output to standard
error.
Machine-parsable format also uses a tabular format, but is
designed to be efficient to programmatically parse. Specifically,
machine-parsable 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 \.
Example 1 Obtaining Failure Detection Time of a Specific
Interface
The following code uses the machine-parsable 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
}
See attributes(7) for descriptions of the following
attributes:
/usr/sbin/ipmpstat:
| ATTRIBUTE
TYPE |
ATTRIBUTE VALUE |
| Interface Stability |
Committed |
| Machine-Parsable Format |
Committed |
| Human-Friendly Format |
Not-an-Interface |
/sbin/ipmpstat is not a Committed interface.