ProcessFailover(8) System Manager's Manual ProcessFailover(8)
NAME
ProcessFailover -- process a failover event, adding or removing IP
aliases to a given interface
SYNOPSIS
ProcessFailover {acquire | release} interface:ip_address[/mask] ...
DESCRIPTION
ProcessFailover responds to the availability or failure of failover
nodes. ProcessFailover is designed to be invoked by failoverd(8), not to
be used directly.
ProcessFailover is external to failoverd(8) so an administrator could
inspect the code and assist in debugging customized failover scripts. See
the IMPLEMENTATION NOTES section for details on their operation.
ARGUMENTS
The command-line arguments consist of an operation followed by one or
more interface / address / mask triplets.
The following operations are valid:
acquire
down These operations instruct ProcessFailover to add the IP
addresses to the current configuration, taking them over
for a failed peer.
release
up These operations instruct ProcessFailover to remove the IP
addresses from the current configuration, allowing a
recovered peer to acquire the released addresses.
The triplets are broken up and passed to ifconfig(8) to acquire or
release the given addresses. A triplet is composed of the following ele-
ments:
interface The networking interface name, as used by ifconfig(8),
e.g. "en0".
ip_address A properly formatted dotted decimal, IPv4 address.
mask An optional CIDR mask value passed to ifconfig(8). As
noted in the description for the alias parameter in
ifconfig(8), if the given ip_address is on the same
subnet as the first network address for the target
interface, the mask must be "/32" or left blank.
IMPLEMENTATION NOTES
ProcessFailover allows an administrator to customize its behavior via the
use of external executables, located in /Library/IPFailover/{ip_address}.
Controlling failover actions
If an executable named Test is present in a target directory, it is exe-
cuted to determine whether the given IP address should be acquired or
relinquished. If the tool is not present or returns an exit code of zero
(0), acquisition or release will continue. For a simple way of prevent-
ing failover (e.g., to create a monitor instead of a backup), link or
copy /usr/bin/false to Test.
Customizing failover behavior
If acquisition or release is approved, executables in the target direc-
tory will be executed according to their well-defined prefixes:
PreAcq Run before executing ifconfig(8) to acquire an IP address.
PostAcq Run after executing ifconfig(8) to acquire an IP address.
PreRel Run before executing ifconfig(8) to release an IP address.
PostRel Run after executing ifconfig(8) to release an IP address.
Multiple executables with the same prefix are allowed in each target
directory. They will run in the same order as presented by the ls(1)
command.
Invocation of executables
While processing a failover event, ProcessFailover will invoke any exe-
cutables described above with arguments describing the current operation:
Test {acquire | release} ip_address
{PreAcq* | PostAcq*} acquire ip_address
{PreRel* | PostRel*} release ip_address
ENVIRONMENT
SCRIPTSDIR The directory containing customized failover scripts. This
defaults to /Library/IPFailover.
TESTPROG The name of the failover test program. This defaults to Test.
If the executable returns with an error condition, the
acquire or release action will be aborted.
FILES & FOLDERS
/usr/libexec/ProcessFailover
/Library/IPFailover/{ip_address}/Test
/Library/IPFailover/{ip_address}/PreAcq*
/Library/IPFailover/{ip_address}/PostAcq*
/Library/IPFailover/{ip_address}/PreRel*
/Library/IPFailover/{ip_address}/PostRel*
EXAMPLES
Acquiring an address
The following invocation will add the IP address, 10.10.40.15, onto en0
(the built-in Ethernet interface) and set the netmask to 255.255.255.0.
ProcessFailover acquire en0:10.10.40.15/24
In effect, this translates to:
ifconfig en0 inet alias 10.10.40.15/24
However, the full sequence of execution is
/Library/IPFailover/10.10.40.15/Test
/Library/IPFailover/10.10.40.15/PreAcq*
ifconfig en0 inet alias 10.10.40.15/24
/Library/IPFailover/10.10.40.15/PostAcq*
Releasing an address
This example removes two IP addresses from different interfaces:
ProcessFailover release en0:10.10.40.15 fw0:10.13.40.16
This translates to:
ifconfig en0 inet -alias 10.10.40.15
ifconfig fw0 inet -alias 10.13.40.16
DIAGNOSTICS
The ProcessFailover utility exits 0 on success, and >0 if an error
occurs. ProcessFailover also writes status and error messages to syslog.
If an ip_address is unreachable after a failover has taken place, verify
that the mask argument was properly specified.
SEE ALSO
NotifyFailover(8), ifconfig(8), failoverd(8)
HISTORY
A version of ProcessFailover has been present in Mac OS X Server since
version 10.2 (Jaguar).
Mac OS X Server 10.4 March 1, 2005 Mac OS X Server 10.4
Mac OS X 10.6Server - Generated Thu Apr 15 07:12:55 CDT 2010