manpagez: man pages & more
man ProcessFailover(8)
Home | html | info | man
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
© manpagez.com 2000-2020
Individual documents may contain additional copyright information.