manpagez: man pages & more
man failoverd(8)
Home | html | info | man

failoverd(8)              BSD System Manager's Manual             failoverd(8)


     failoverd -- Mac OS X Server IP failover detection daemon


     failoverd [-d | -n | -x] [-p port] master_priv_addr
               interface:pub_addr[/mask] ...
     failoverd [-h | -v]


     failoverd tracks another host's availability on the network.  Upon detec-
     tion of a failure, failoverd will take over the master host's public IP
     addresses, maintaining service availability to incoming clients.

     In typical usage, failoverd is launched during the boot process by the
     IPFailover startup item if the appropriate fields - FAILOVER_PEER_IP and
     FAILOVER_PEER_IP_PAIRS - are defined in /etc/hostconfig.

     Upon launch, failoverd checks it argument list, moves to the background,
     and listens for messages from heartbeatd(8).  When a failure is detected
     or recovered from, failoverd invokes NotifyFailover(8) to notify the
     administrator and ProcessFailover(8) to aquire or release the monitored
     IP addresses.

     The command-line arguments consist of optional arguments, the master's
     private address, and one or more interface / address / mask triplets.
     The private address, master_priv_addr, is one of the master's IP
     addresses that will not be acquired by the backup and is used to communi-
     cate the master's status to the backup.  Each triplet defines one of the
     master's publicly accessible IP addresses that the backup will assume
     upon the master's failure.  The triplets are passed to ProcessFailover(8)
     to acquire or release the given addresses in the event of a failure or
     recovery.  A triplet is composed of the following elements:

           interface  The networking interface name, as used by ifconfig(8),
                      e.g. "en0".

           pub_addr   One of the master's publicly accessible IPv4 addresses,
                      in properly formatted dotted decimal notation.

           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 pub_addr is on the same subnet
                      as the first network address for the target interface,
                      the mask must be "/32" or left blank.


     The following options are available:
     --debug            Do not move to background and print log strings to the

     --help             Print usage summary and exit.

     -L facility        Enable logging to syslog(8) using the specified
                        facility.  The following values for facility are sup-
                        ported: daemon (the default), auth, user, local[0-7].
                        (See syslog.conf(5) for their meanings.) This is
                        equivalent to --syslog.

     --no-fork          Do not move to background. This is equivalent to -x.

     --no-run           Do not move to background, print log information to
                        the terminal, and quit after reading the configuration
                        file. This validates the configuration of hardware and

     -p port
     --port=port        Listen on the specified port instead of the default,
                        1694. This must match the port used by the master
                        node's invocation of heartbeatd(8).

     --syslog=facility  Enable logging to syslog(8) using the specified
                        facility.  The following values for facility are sup-
                        ported: daemon (the default), auth, user, local[0-7].
                        (See syslog.conf(5) for their meanings.) This is
                        equivalent to -L.

     --version          Print build version and exit.

     -x                 Do not move to background. This is equivalent to


     The following environment varaibles will be converted to failoverd com-
     mand-line arguments by /System/Library/StartupItems/IPFailover when it
     invokes failoverd:

           FAILOVER_PEER_IP        A single IP address passed to failoverd as
                                   the master_priv_addr argument.

           FAILOVER_PEER_IP_PAIRS  A quoted, space-separated list of
                                   interface:pub_addr[/mask] triplets passed
                                   as command-line arguments to failoverd.
                                   (The inappropriate "PAIRS" name is histori-
                                   cal; the optional mask parameter was not
                                   previously allowed.)




     A simple invocation would be

           failoverd en0:

     In this example, the backup computer would monitor the master with the
     private IP address of and will add the master's public IP
     address,, onto the backup's en0 interface if the master fails.

     A more complicated invocation for a multi-port machine hosting multiple
     virtual IP addresses might be

           failoverd en0: en1:

     The latter invocation, along with a different email address, would typi-
     cally be defined in /etc/hostconfig as

           FAILOVER_PEER_IP_PAIRS="en0: en1:"


     The failoverd utility exits 0 on success, and >0 if an error occurs.

     Events that may be of interest to the administrator are logged via

     If a pub_addr is unreachable after a failover has taken place, verify
     that the mask argument was properly specified.

     failoverd must be executed as root.  Because failoverd controls system-
     wide resources, it must be executed by the root user.

     Invalid port.  Valid ports range from 1 to 65535 (IPV6PORT_ANONMAX).

     Invalid syslog facility.  An invalid syslog facility name was used.
     Please see the description for the -L option, above.

     CNode: invalid IP address  One of the IP address arguments
     (master_priv_addr or the pub_addr portion of one of the
     interface:pub_addr[/mask] triplets) did not resolve to an IP address.

     Invalid interface / IP address pair  One of the command-line arguments
     that should be a interface:pub_addr[/mask] triplet is not properly for-

     CNode: invalid interface name  The interface portion of one of the
     interface:pub_addr[/mask] triplets is not a valid interface for this com-


     NotifyFailover(8), ProcessFailover(8), heartbeatd(8), ifconfig(8),


     A version of failoverd has been present in Mac OS X Server since version
     10.2 (Jaguar).


     failoverd only verifies that the monitored addresses are properly formed
     IP addresses.

     The transparency of availabilty is noticeable only for short-lived proto-
     cols, such as HTTP, DNS, and possibly POP and NFS. Services which use
     persistent connections, (such as FTP, Apple File Sharing, Windows File
     Sharing, and IMAP) will notice interruptions.

     Configuring your nodes to support IP Failover is a non-trivial task and
     not to be taken lightly!  Significant data loss or corruption may result
     from poorly configured systems.

Mac OS X Server                  March 1, 2005                 Mac OS X Server

Mac OS X 10.6Server - Generated Thu Apr 15 07:13:02 CDT 2010
© 2000-2024
Individual documents may contain additional copyright information.