failoverd(8) BSD System Manager's Manual failoverd(8)
NAME
failoverd -- Mac OS X Server IP failover detection daemon
SYNOPSIS
failoverd [-d | -n | -x] [-p port] master_priv_addr
interface:pub_addr[/mask] ...
failoverd [-h | -v]
DESCRIPTION
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.
OPTIONS
The following options are available:
-d
--debug Do not move to background and print log strings to the
terminal.
-h
--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.
-n
--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
software.
-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.
-v
--version Print build version and exit.
-x Do not move to background. This is equivalent to
--no-fork.
ENVIRONMENT
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.)
FILES & FOLDERS
/usr/sbin/failoverd
/etc/hostconfig
/System/Library/StartupItems/IPFailover
/Library/IPFailover
EXAMPLES
A simple invocation would be
failoverd 10.100.0.100 en0:192.13.2.2
In this example, the backup computer would monitor the master with the
private IP address of 10.100.0.100 and will add the master's public IP
address, 192.13.2.2, 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 10.100.0.10 en0:192.13.2.2/16 en1:1.2.3.4/24
The latter invocation, along with a different email address, would typi-
cally be defined in /etc/hostconfig as
FAILOVER_PEER_IP=10.100.0.10
FAILOVER_PEER_IP_PAIRS="en0:192.13.2.2/16 en1:1.2.3.4/24"
FAILOVER_EMAIL_RECIPIENT=failure_notifications@groups.example.com
DIAGNOSTICS
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
syslogd(8).
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-
matted.
CNode: invalid interface name The interface portion of one of the
interface:pub_addr[/mask] triplets is not a valid interface for this com-
puter.
SEE ALSO
NotifyFailover(8), ProcessFailover(8), heartbeatd(8), ifconfig(8),
syslogd(8)
HISTORY
A version of failoverd has been present in Mac OS X Server since version
10.2 (Jaguar).
KNOWN ISSUES
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