Monitoring IPMP Information
The following examples show how to use the ipmpstat command to monitor different aspects of the IPMP groups that are on the system. You can observe the status of an IPMP group as a whole or its underlying IP interfaces. You can also verify the configuration of data and test addresses for an IPMP group. You can also use the same command to obtain information about failure detection. For more information, see the ipmpstat(1M) man page.
When you use the ipmpstat command, by default, the most meaningful fields that fit in 80 columns are displayed. In the output, all of the fields that are specific to the option that you use with the ipmpstat command are displayed, except in the case where the ipmpstat is used with the –p option.
By default, host names are displayed in the output instead of numeric IP addresses, provided that the host names exist. To list the numeric IP addresses in the output, use the –n option with other options to display specific IPMP group information.
Note - In the following examples, use of the ipmpstat command does not require system administrator privileges, unless stated otherwise.
Use the ipmpstat command with the following options to display the desired information:
- –g
-
Displays information about the IPMP groups on the system. See Example 25, Obtaining IPMP Group Information.
- –a
-
Displays the data addresses that are configured for the IPMP groups. See Example 26, Obtaining IPMP Data Address Information.
- –i
-
Displays information about IP interfaces that are related to IPMP configuration. See Example 27, Obtaining Information About Underlying IP Interfaces of an IPMP Group.
- –t
-
Displays information about target systems that are used for detecting failure. This option also displays the test addresses that are used by the IPMP group. See Example 28, Obtaining IPMP Probe Target Information.
- –p
-
Displays information about the probes that are being used for failure detection. See Example 29, Observing IPMP Probes.
The following additional examples show how to display information about your system's IPMP configuration by using the ipmpstat command.
Example 25 Obtaining IPMP Group InformationThe –g option displays the status of the various IPMP groups that are on the system, including the status of their underlying interfaces. If probe-based failure detection is enabled for a specific group, the command also includes the failure detection time for that group.
% ipmpstat -g GROUP GROUPNAME STATE FDT INTERFACES ipmp0 ipmp0 ok 10.00s net0 net1 acctg1 acctg1 failed -- [net3 net4] field2 field2 degraded 20.00s net2 net5 (net7) [net6]
The output fields provide the following information:
- GROUP
-
Specifies the IPMP interface name. For an anonymous group, this field is empty. For more information about anonymous groups, see the in.mpathd(1M) man page.
- GROUPNAME
-
Specifies the name of the IPMP group. In the case of an anonymous group, this field is empty.
- STATE
-
Indicates an IPMP group's current status, which can be one of the following:
-
ok – Indicates that all of the underlying interfaces of the IPMP group are usable.
-
degraded – Indicates that some of the underlying interfaces in the group are unusable.
-
failed – Indicates that all of the group's interfaces are unusable.
-
- FDT
-
Specifies the failure detection time, if failure detection is enabled. If failure detection is disabled, this field is empty.
- INTERFACES
-
Specifies the underlying interfaces that belong to the IPMP group. In this field, active interfaces are displayed first, then inactive interfaces, and finally unusable interfaces. The status of an interface is indicated by the manner in which it is displayed:
-
interface (without parentheses or square brackets) – Indicates an active interface. Active interfaces are being used by the system to send or receive data traffic.
-
(interface) (with parentheses) – Indicates a functioning but inactive interface. The interface is not in use, as defined by administrative policy.
-
[interface] (with square brackets) – Indicates that the interface is unusable because it has either failed or been taken offline.
-
The –a option displays data addresses and the IPMP group to which each address belongs. The displayed information also includes those addresses that are available for use, depending on whether the addresses have been toggled by the ipadm [up-addr/down-addr] command. You can also determine on which inbound or outbound interface an address can be used.
% ipmpstat -an ADDRESS STATE GROUP INBOUND OUTBOUND 192.0.2.5/27 up ipmp0 net0 net0 net1 192.0.2.7/27 up ipmp0 net1 net0 net1 192.0.2.35/27 up acctg1 -- -- 192.0.2.37/27 up acctg1 -- -- 192.0.2.15/27 up field2 net2 net2 net7 192.0.2.20/27 up field2 net7 net2 net7 192.0.2.25/27 down field2 -- --
The output fields provide the following information:
- ADDRESS
-
Specifies the host name or the data address, if the –n option is used with the –a option.
- STATE
-
Indicates whether the address on the IPMP interface is up, and therefore usable, or down, and therefore unusable.
- GROUP
-
Specifies the IPMP interface that hosts a specific data address. Typically, in Oracle Solaris, the name of the IPMP group is the IPMP interface.
- INBOUND
-
Identifies the interface that receives packets for a given address. The field information might change depending on external events. For example, if a data address is down, or if no active IP interfaces remain in the IPMP group, this field is empty. The empty field indicates that the system is not accepting IP packets that are destined for the given address.
- OUTBOUND
-
Identifies the interface that sends packets that are using a given address as a source address. As with the INBOUND field, the OUTBOUND information might also change depending on external events. An empty field indicates that the system is not sending packets with the given source address. The field might be empty, either because the address is down or because no active IP interfaces remain in the group.
The –i option displays information about an IPMP group's underlying IP interfaces.
% ipmpstat -i INTERFACE ACTIVE GROUP FLAGS LINK PROBE STATE net0 yes ipmp0 --mb--- up ok ok net1 yes ipmp0 ------- up disabled ok net3 no acctg1 ------- unknown disabled offline net4 no acctg1 is----- down unknown failed net2 yes field2 --mb--- unknown ok ok net6 no field2 -i----- up ok ok net5 no filed2 ------- up failed failed net7 yes field2 --mb--- up ok ok
The output fields provide the following information:
- INTERFACE
-
Specifies each underlying interface in each IPMP group.
- ACTIVE
-
Indicates whether the interface is functioning and in use (yes) or not (no).
- GROUP
-
Specifies the IPMP interface name. For anonymous groups, this field is empty. For more information about anonymous groups, see the in.mpathd(1M) man page.
- FLAGS
-
Indicates the status of each underlying interface, which can be one or any combination of the following:
-
b – Indicates that the interface is designated by the system to receive broadcast traffic for the IPMP group.
-
d – Indicates that the interface is down and therefore unusable.
-
h – Indicates that the interface shares a duplicate physical hardware address with another interface and has been taken offline. The h flag indicates that the interface is unusable.
-
i – Indicates that the INACTIVE flag is set for the interface. Therefore, the interface is not used to send or receive data traffic.
-
m – Indicates that the interface is designated by the system to send and receive IPv4 multicast traffic for the IPMP group.
-
M – Indicates that the interface is designated by the system to send and receive IPv6 multicast traffic for the IPMP group.
-
s – Indicates that the interface is configured as a standby interface.
-
- LINK
-
Indicates the status of link-based failure detection, which is one of the following:
-
up or down – Indicates the availability or unavailability of a link.
-
unknown – Indicates that the driver does not support notification of whether a link is up or down and therefore does not detect changes in the state of the link.
-
- PROBE
-
Specifies the state of probe-based failure detection for interfaces that have been configured with a test address, as follows:
-
ok – Indicates that the probe is functional and active.
-
failed – Indicates that probe-based failure detection has detected that the interface is not working.
-
unknown – Indicates that no suitable probe targets could be found, Therefore, probes cannot be sent.
-
disabled – Indicates that no IPMP test address is configured on the interface. Therefore, probe-based failure detection is disabled.
-
- STATE
-
Specifies the overall state of the interface, as follows:
-
ok – Indicates that the interface is online and working normally based on the configuration of failure detection methods.
-
failed – Indicates that the interface is not working either because the interface's link is down or because the probe detection has determined that the interface cannot send or receive traffic.
-
offline – Indicates that the interface is not available for use. Typically, the interface is taken offline under the following circumstances:
-
The interface is being tested.
-
Dynamic reconfiguration is being performed.
-
The interface shares a duplicate hardware address with another interface.
-
-
unknown – Indicates that the IPMP interface's state cannot be determined because no probe targets were found for probe-based failure detection.
-
The –t option identifies the probe targets that are associated with each IP interface in an IPMP group. The output in the following example shows an IPMP configuration that uses test addresses for probe-based failure detection.
% ipmpstat -nt INTERFACE MODE TESTADDR TARGETS net0 routes 192.0.2.15/27 192.0.2.1/27 192.0.2.3/27 net1 disabled -- -- net3 disabled -- -- net4 routes 192.0.2.35/27 192.0.2.37/27 net2 multicast 192.0.2.15/27 192.0.2.1 192.0.2.2 net6 multicast 192.0.2.20/27 192.0.2.2 192.0.2.1 net5 multicast 192.0.2.25/27 192.0.2.1 192.0.2.2
The following output shows an IPMP configuration that uses transitive probing or probe-based failure detection without test addresses.
% ipmpstat -nt INTERFACE MODE TESTADDR TARGETS net3 transitive <net1> <net1> <net2> <net3> net2 transitive <net1> <net1> <net2> <net3> net1 routes 192.0.2.70/27 192.0.2.65/27
The output fields provide the following information:
- INTERFACE
-
Specifies each underlying interface of an IPMP group.
- MODE
-
Specifies the method for obtaining the probe targets.
-
routes – Indicates that the system routing table is used to find probe targets.
-
mcast – Indicates that multicast ICMP probes are used to find targets.
-
disabled – Indicates that probe-based failure detection has been disabled for the interface.
-
transitive – Indicates that transitive probing is used for failure detection, as shown in the second example. Note that you cannot implement probe-based failure detection while simultaneously using transitive probes and test addresses. If you do not want to use test addresses, then you must enable transitive probing. If you do not want to use transitive probing, then you must configure test addresses. For an overview, see Probe-Based Failure Detection.
-
- TESTADDR
-
Specifies the host name, or if the –n option is used with the –t option, the IP address that is assigned to the interface to send and receive probes.
If transitive probing is used, then the interface names refer to the underlying IP interfaces that are not actively used to receive data. The names also indicate that the transitive test probes are being sent with the source address of these specified interfaces. For active underlying IP interfaces that receive data, an IP address that is displayed indicates the source address of outgoing ICMP probes.
Note - If an IP interface is configured with both IPv4 and IPv6 test addresses, the probe target information is displayed separately for each test address. - TARGETS
-
Lists the current probe targets in a space-separated list. The probe targets are displayed either as host names or IP addresses. If the –n option is used with the –t option, the IP addresses are displayed.
The –p option enables you to observe ongoing probes. When you use this option with the ipmpstat command, information about probe activity on the system is continuously displayed until you terminate the command by pressing Control-C. You must become the root role or have appropriate privileges to run this command.
The following is an example of an IPMP configuration that uses test addresses for probe-based failure detection.
# ipmpstat -pn TIME INTERFACE PROBE NETRTT RTT RTTAVG TARGET 0.11s net0 589 0.51ms 0.76ms 0.76ms 192.0.2.1/27 0.17s net4 612 -- -- -- 192.0.2.1/27 0.25s net2 602 0.61ms 1.10ms 1.10ms 192.0.2.3/27 0.26s net6 602 -- -- -- 192.0.2.3/27 0.25s net5 601 0.62ms 1.20ms 1.00ms 192.0.2.1/27 0.26s net7 603 0.79ms 1.11ms 1.10ms 192.0.2.1/27 1.66s net4 613 -- -- -- 192.0.2.3/27 1.70s net0 603 0.63ms 1.10ms 1.10ms 192.0.2.35/27 ^C
The following is an example of an IPMP configuration that uses transitive probing or probe-based failure detection without test addresses.
# ipmpstat -pn TIME INTERFACE PROBE NETRTT RTT RTTAVG TARGET 1.39S net4 t28 1.05ms 1.06ms 1.15ms <net1> 1.39s net1 i29 1.00ms 1.42ms 1.48ms 192.0.2.1/27 ^C
The output fields provide the following information:
- TIME
-
Specifies the time a probe was sent relative to when the ipmpstat command was issued. If a probe was initiated prior to ipmpstat being started, then the time is displayed with a negative value, relative to when the command was issued.
- INTERFACE
-
Specifies the interface on which the probe is sent.
- PROBE
-
Specifies the identifier that represents the probe. If transitive probing is used for failure detection, the identifier is prefixed with either t for transitive probes or i for ICMP probes.
- NETRTT
-
Specifies the total network round-trip time of the probe, measured in milliseconds. NETRTT covers the time between the moment when the IP module sends the probe and the moment the IP module receives the ack packets from the target. If the in.mpathd daemon has determined that the probe is lost, then the field is empty.
- RTT
-
Specifies the total round-trip time for the probe, measured in milliseconds. RTT covers the time between the moment the in.mpathd daemon executes the code to send the probe and the moment the daemon completes processing of the ack packets from the target. If the daemon has determined that the probe is lost, then the field is empty. Spikes that occur in the RTT that are not present in the NETRTT might indicate that the local system is overloaded.
- RTTAVG
-
Specifies the probe's average round-trip time over the interface between the local system and the target. The average round-trip time helps identify slow targets. If data is insufficient to calculate the average, this field is empty.
- TARGET
-
Specifies the host name. Or, if the –n option is used with the –p option, specifies the target address to which the probe is sent.
Customizing the Output of the ipmpstat Command
The –o option enables you to customize the output of the ipmpstat command. You use this option with the other previously mentioned ipmpstat options to select specific fields to be displayed out of the total fields that the main option normally displays.
-
IPMP group
-
IPMP group name
-
Status of the group
-
Failure detection time
-
Underlying interfaces of the IPMP group
For example, the –g option provides the following information:
Suppose that you want to display only the status of the IPMP groups on the system. You would combine the –o and –g options and specify the groupname and state fields, as shown in the following example:
% ipmpstat -g -o groupname,state GROUPNAME STATE ipmp0 ok accgt1 failed field2 degraded
To display all of the fields of the ipmpstat command for a specific type of information, include the –o option with the all argument.
Using the ipmpstat Command in Scripts
The –o option is useful when you run the ipmpstat command from a script or by using a command alias, particularly if you also want to generate machine-parsable output.
To generate machine-parsable information, you combine the –P and –o options with one of the other main ipmpstat options, along with the specific fields that you want to display.
-
Column headers are omitted.
-
Fields are separated by colons (:).
-
Fields with empty values are empty rather than filled with the double dash (--).
-
When multiple fields are requested, if a field contains a literal colon (:) or backslash (\), you can escape or exclude these characters by prefixing them with a backslash (\).
A machine-parsable output differs from normal output in the following ways:
-
Use the –o option field option with the –P option. Separate multiple option fields with commas.
-
Never use the –o all option with the –P option.
To correctly use the ipmpstat –P command, observe the following rules:
 | Caution - Ignoring either one of these rules causes ipmpstat –P to fail. |
The following example shows the correct syntax for using the –P option:
% ipmpstat -P -o -g groupname,fdt,interfaces ipmp0:10.00s:net0 net1 acctg1::[net3 net4] field2:20.00s:net2 net7 (net5) [net6]
The group name, failure detection time, and underlying interfaces are group information fields. Thus, you use the –o and –g options along with the –P option.
The –P option is intended for use in scripts. The following example shows how you would run the ipmpstat command from a script. The script displays the failure detection time for an IPMP group.
getfdt() {
ipmpstat -gP -o group,fdt | while IFS=: read group fdt; do
[[ "$group" = "$1" ]] && { echo "$fdt"; return; }
done
}