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 detection 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 communicate 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 ele-ments: elements:
ments:
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 supported: 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 supported: 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 command-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 historical; the optional mask parameter was not previ-ously previously
ously 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 typically 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 prop-erly properly
erly specified.
failoverd must be executed as root. Because failoverd controls system-wide resources, it must be exe-cuted executed
cuted 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 formatted.
CNode: invalid interface name The interface portion of one of the interface:pub_addr[/mask] triplets
is not a valid interface for this computer.
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 protocols, such as HTTP, DNS, and
possibly POP and NFS. Services which use persistent connections, (such as FTP, Apple File Sharing, Win-dows Windows
dows 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
|