ipmpstat(1M)						  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 pro-
       vides 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  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-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:

	   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(1M)), 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(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:

	       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(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 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  informa-
	       tion 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-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:

	   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
	      }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       /usr/sbin/ipmpstat:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE 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

       if_mpadm(1M), ifconfig(1M), in.mpathd(1M), attributes(5)

SunOS 5.11							    10 Feb 2009 						      ipmpstat(1M)