--- /dev/null Fri Dec 19 04:18:57 2008 +++ new/./ipmpstat.1m.txt Fri Dec 19 04:18:56 2008 @@ -0,0 +1,399 @@ +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 + 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 + + -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 print 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 + + 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 (e.g., 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 (e.g., 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 (e.g., + *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 if 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 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 + detect 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 *^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 ack. 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 via the + routing table. + + *multicast* Probe targets found via 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 + *--*, and other visual aids are used. + + 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: + + * No headers are displayed. + + * Fields with empty values yield no output, rather than + *--*. + + * Fields are separated by a single *:*, rather than + variable amounts of whitespace. + + * If multiple fields are requested, and a literal *:* or + *\* occur in a field's value, they are escaped by + prefixing them with *\*. + +EXAMPLES + + Use 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 + + See attributes(5) for descriptions of the following + attributes: + + /usr/sbin + + ____________________________________________________________ + | ATTRIBUTE TYPE | ATTRIBUTE VALUE | + |_____________________________|_____________________________| + | Availability | SUNWcsu | + |_____________________________|_____________________________| + | Interface Stability | Committed | + |_____________________________|_____________________________| + | Machine-Parsable Format | Committed | + |_____________________________|_____________________________| + | Human-Friendly Format | Not-an-Interface | + |_____________________________|_____________________________| + + +SEE ALSO + + in.mpathd(1M), ifconfig(1M), if_mpadm(1M)