This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with Mac OS X Server. It is not available on standard Mac OS X (client) installations.

For more information about the manual page format, see the manual page for manpages(5).

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 opera-tion. operation.
     tion.

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 config-uration, configuration,
                    uration, 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 elements:

           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 executed 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 preventing 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 directory 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 executables 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 inter-face) interface)
     face) 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