Merge commit 'c5bab7026b8e0ac44b25ee08507ea360f177d844' into merges

[unleashed.git] / share / man / man8 / in.mpathd.8

'\" te
.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH IN.MPATHD 8 "May 13, 2009"
.SH NAME
in.mpathd \- IP multipathing daemon
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/inet/in.mpathd\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBin.mpathd\fR daemon performs failure and repair detection for IP
interfaces that have been placed into an IPMP group (or optionally, for all IP
interfaces on the system). It also controls which IP interfaces in an IPMP
group are "active" (being used by the system to send or receive IP data
traffic) in a manner that is consistent with the administrator's configured
policy.
.sp
.LP
The \fBin.mpathd\fR daemon can detect IP interface failure and repair through
two methods: by monitoring the \fBIFF_RUNNING\fR flag for each IP interface
(link-based failure detection), and by sending and receiving ICMP probes on
each IP interface (probe-based failure detection). Link-based failure detection
is instantaneous and is always enabled (provided the network driver supports
the feature); probe-based failure detection must be enabled through the
configuration of one or more test addresses (described below), but tests the
entire IP interface send and receive path. The \fBipmpstat\fR(8) utility can
be used to check which failure detection methods are enabled.
.sp
.LP
If only link-based failure detection is enabled, then the health of the
interface is determined solely from the state of the \fBIFF_RUNNING\fR flag.
Otherwise, the interface is considered failed if either of the two methods
indicate a failure, and repaired once both methods indicate the failure has
been corrected. Not all interfaces in a group need to be configured with the
same failure detection methods.
.sp
.LP
As mentioned above, to perform probe-based failure detection \fBin.mpathd\fR
requires a test address on each IP interface for the purpose of sending and
receiving probes. Each address must be marked \fBNOFAILOVER\fR (see
\fBifconfig\fR(8)) and \fBin.mpathd\fR will be limited to probing targets on
the same subnet. Each address may be configured statically or acquired by means
of DHCP. To find targets, \fBin.mpathd\fR first consults the routing table for
routes on the same subnet, and uses the specified next-hop. If no routes match,
it sends all-hosts ICMP probes and selects a subset of the systems that
respond. Thus, for probe-based failure detection to operate, there must be at
least one neighbor on each subnet that responds to ICMP echo request probes.
The \fBipmpstat\fR(8) utility can be used to display both the current probe
target information and the status of sent probes.
.sp
.LP
Both IPv4 and IPv6 are supported. If an IP interface is plumbed for IPv4 and an
IPv4 test address is configured then \fBin.mpathd\fR will start sending ICMPv4
probes over that IP interface. Similarly, if an IP interface is plumbed for
IPv6 and an IPv6 test address is configured, then \fBin.mpathd\fR will start
sending ICMPv6 probes over that IP interface. However, note that
\fBin.mpathd\fR will ignore IPv6 test addresses that are not link-local. If
both IPv4 and IPv6 are plumbed, it is sufficient to configure only one of the
two, that is, either an IPv4 test address or an IPv6 test address. If both IPv4
and IPv6 test addresses are configured, \fBin.mpathd\fR probes using both
ICMPv4 and ICMPv6.
.sp
.LP
As mentioned above, \fBin.mpathd\fR also controls which IP interfaces in an
IPMP group are "active" (used by the system to send and receive IP data
traffic). Specifically, \fBin.mpathd\fR tracks the administrative configuration
of each IPMP group and attempts to keep the number of active IP interfaces in
each group consistent with that configuration. Therefore, if an active IP
interface fails, \fBin.mpathd\fR will activate an \fBINACTIVE\fR interface in
the group, provided one exists (it will prefer \fBINACTIVE\fR interfaces that
are also marked \fBSTANDBY\fR). Likewise, if an IP interface repairs and the
resulting repair leaves the IPMP group with more active interfaces than the
administrative configuration specifies, \fBin.mpathd\fR will deactivate one of
the interfaces (preferably one marked \fBSTANDBY\fR), except when the
\fBFAILBACK\fR variable is used, as described below. Similar adjustments will
be made by \fBin.mpathd\fR when offlining IP interfaces (for instance, in
response to \fBif_mpadm\fR(8)).
.sp
.LP
The \fBin.mpathd\fR daemon accesses three variable values in
\fB/etc/default/mpathd\fR: \fBFAILURE_DETECTION_TIME\fR, \fBFAILBACK\fR and
\fBTRACK_INTERFACES_ONLY_WITH_GROUPS\fR.
.sp
.LP
The \fBFAILURE_DETECTION_TIME\fR variable specifies the probe-based failure
detection time. The shorter the failure detection time, the more probe traffic.
The default value of \fBFAILURE_DETECTION_TIME\fR is 10 seconds. This means
that IP interface failure will be detected by \fBin.mpathd\fR within 10
seconds. The IP interface repair detection time is always twice the value of
\fBFAILURE_DETECTION_TIME\fR. Note that failures and repairs detected by
link-based failure detection are acted on immediately, though \fBin.mpathd\fR
may ignore link state changes if it suspects that the link state is flapping
due to defective hardware; see \fBDIAGNOSTICS\fR.
.sp
.LP
By default, \fBin.mpathd\fR limits failure and repair detection to IP
interfaces that are configured as part of a named IPMP group. Setting
\fBTRACK_INTERFACES_ONLY_WITH_GROUPS\fR to \fBno\fR enables failure and repair
detection on all IP interfaces, even if they are not part of a named IPMP
group. IP interfaces that are tracked but not part of a named IPMP group are
considered to be part of the "anonymous" IPMP group. In addition to having no
name, this IPMP group is special in that its IP interfaces are not equivalent
and thus cannot take over for one another in the event of an IP interface
failure. That is, the anonymous IPMP group can only be used for failure and
repair detection, and provides no high-availability or load-spreading.
.sp
.LP
As described above, when \fBin.mpathd\fR detects that an IP interface has
repaired, it activates it so that it will again be used to send and receive IP
data traffic. However, if \fBFAILBACK\fR is set to \fBno\fR, then the IP
interface will only be activated if no other active IP interfaces in the group
remain. However, the interface may subsequently be activated if another IP
interface in the group fails.
.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/default/mpathd\fR\fR
.ad
.RS 23n
Contains default values used by the \fBin.mpathd\fR daemon.
.RE

.SH SEE ALSO
.sp
.LP
\fBif_mpadm\fR(8), \fBifconfig\fR(8), \fBipmpstat\fR(8),
\fBattributes\fR(5), \fBicmp\fR(7P), \fBicmp6\fR(7P),
.sp
.LP
\fISystem Administration Guide: IP Services\fR
.SH DIAGNOSTICS
.sp
.LP
IP interface \fIinterface_name\fR has a hardware address which is not unique in
group \fIgroup_name\fR; offlining
.RS +4
\fBDescription: \fR
.sp
.LP
For probe-based failure detection, load-spreading, and other code IPMP features
to work properly, each IP interface in an IPMP group must have a unique
hardware address. If this requirement is not met, \fBin.mpathd\fR will
automatically offline all but one of the IP interfaces with duplicate hardware
addresses.
.RE

.sp
.LP
IP interface \fIinterface_name\fR now has a unique hardware address in group
\fIgroup_name\fR; onlining
.RS +4
\fBDescription: \fR
.sp
.LP
The previously-detected duplicate hardware address is now unique, and therefore
\fBin.mpathd\fR has brought \fIinterface_name\fR back online.
.RE

.sp
.LP
Test address \fIaddress\fR is not unique in group; disabling probe-based
failure detection on \fIinterface_name\fR
.RS +4
\fBDescription: \fR
.sp
.LP
For \fBin.mpathd\fR to perform probe-based failure detection, each test address
in the group must be unique.
.RE

.sp
.LP
No test address configured on interface \fIinterface_name\fR disabling
probe-based failure detection on it
.RS +4
\fBDescription: \fR
.sp
.LP
For \fBin.mpathd\fR to perform probe-based failure detection on an IP
interface, it must be configured with a test address: IPv4, IPv6, or both.
.RE

.sp
.LP
IP \fIinterface_name\fR in group \fIgroup_name\fR is not plumbed for IPv[4|6],
affecting IPv[4|6] connectivity
.RS +4
\fBDescription: \fR
.sp
.LP
All IP interfaces in a multipathing group must be homogeneously plumbed. For
example, if one IP interface is plumbed for IPv4, then all IP interfaces in the
group must be plumbed for IPv4, or IPv4 packets will not be able to be reliably
sent and received. The STREAMS modules pushed on all IP interfaces must also be
identical.
.RE

.sp
.LP
The link has come up on \fIinterface_name\fR more than 2 times in the last
minute; disabling repair until it stabilizes.
.RS +4
\fBDescription: \fR
.sp
.LP
To limit the impact of interfaces with intermittent hardware (such as a bad
cable), \fBin.mpathd\fR will not consider an IP interface with a frequently
changing link state as repaired until the link state stabilizes.
.RE

.sp
.LP
Invalid failure detection time of \fItime\fR, assuming default 10000 ms
.RS +4
\fBDescription: \fR
.sp
.LP
An invalid value was encountered for \fBFAILURE_DETECTION_TIME\fR in the
\fB/etc/default/mpathd\fR file.
.RE

.sp
.LP
Too small failure detection time of \fItime\fR, assuming minimum of 100 ms
.RS +4
\fBDescription: \fR
.sp
.LP
The minimum value that can be specified for \fBFAILURE_DETECTION_TIME\fR is
currently 100 milliseconds.
.RE

.sp
.LP
Invalid value for FAILBACK \fIvalue\fR
.RS +4
\fBDescription: \fR
.sp
.LP
Valid values for the boolean variable \fBFAILBACK\fR are \fByes\fR or \fBno\fR.
.RE

.sp
.LP
Invalid value for TRACK_INTERFACES_ONLY_WITH_GROUPS \fIvalue\fR
.RS +4
\fBDescription: \fR
.sp
.LP
Valid values for the boolean variable \fBTRACK_INTERFACES_ONLY_WITH_GROUPS\fR
are \fByes\fR or \fBno\fR.
.RE

.sp
.LP
Cannot meet requested failure detection time of \fItime\fR ms on (inet[6]
\fIinterface_name\fR) new failure detection time for group \fIgroup_name\fR is
\fItime\fR ms
.RS +4
\fBDescription: \fR
.sp
.LP
The round trip time for \fBICMP\fR probes is higher than necessary to maintain
the current failure detection time. The network is probably congested or the
probe targets are loaded. \fBin.mpathd\fR automatically increases the failure
detection time to whatever it can achieve under these conditions.
.RE

.sp
.LP
Improved failure detection time \fItime\fR ms on (inet[6] \fIinterface_name\fR)
for group \fIgroup_name\fR
.RS +4
\fBDescription: \fR
.sp
.LP
The round trip time for \fBICMP\fR probes has now decreased and \fBin.mpathd\fR
has lowered the failure detection time correspondingly.
.RE

.sp
.LP
IP interface failure detected on \fIinterface_name\fR
.RS +4
\fBDescription: \fR
.sp
.LP
\fBin.mpathd\fR has detected a failure on \fIinterface_name\fR, and has set the
\fBIFF_FAILED\fR flag on \fIinterface_name\fR, ensuring that it will not be
used for IP data traffic.
.RE

.sp
.LP
IP interface repair detected on \fIinterface_name\fR
.RS +4
\fBDescription: \fR
.sp
.LP
\fBin.mpathd\fR has detected a repair on \fIinterface_name\fR, and has cleared
the \fBIFF_FAILED\fR flag. Depending on the administrative configuration, the
\fIinterface_name\fR may again be used for IP data traffic.
.RE

.sp
.LP
All IP interfaces in group \fIgroup\fR are now unusable
.RS +4
\fBDescription: \fR
.sp
.LP
\fBin.mpathd\fR has determined that none of the IP interfaces in \fIgroup\fR
can be used for IP data traffic, breaking network connectivity for the group.
.RE

.sp
.LP
At least 1 IP interface (\fIinterface_name\fR) in group \fIgroup\fR is now
usable
.RS +4
\fBDescription: \fR
.sp
.LP
\fBin.mpathd\fR has determined that at least one of the IP interfaces in
\fIgroup\fR can again be used for IP data traffic, restoring network
connectivity for the group.
.RE

.sp
.LP
The link has gone down on \fIinterface_name\fR
.RS +4
\fBDescription: \fR
.sp
.LP
\fBin.mpathd\fR has detected that the \fBIFF_RUNNING\fR flag for
\fIinterface_name\fR has been cleared, indicating that the link has gone down.
.RE

.sp
.LP
The link has come up on \fIinterface_name\fR
.RS +4
\fBDescription: \fR
.sp
.LP
\fBin.mpathd\fR has detected that the \fBIFF_RUNNING\fR flag for
\fIinterface_name\fR has been set, indicating that the link has come up.
.RE