Tribblix: manual page: ipmpstat.8

IPMPSTAT(8) Maintenance Commands and Procedures IPMPSTAT(8)

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 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.

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 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.

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:

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.

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 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 \.

EXAMPLES

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
}

ATTRIBUTES