.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\" fake.8
.\" Horms                                             horms@verge.net.au
.\"
.\" Fake
.\" Script to spoof an ip
.\" Designed to create redundant servers
.\" Copyright (C) 1998  Horms <horms@verge.net.au>
.\" 
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of the
.\" License, or (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
.\" 02111-1307  USA
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TH FAKE 8 "9 June 2004"
.SH NAME
fake \- IP address takeover tool
.SH SYNOPSIS
\fBfake\fP [\fBremove\fP] \fIIP_ADDRESS\fP
.SH DESCRIPTION
The \fBfake\fP utility enables the switching in of a backup server
by bringing up an additional interface and using ARP spoofing to
take over \fIIP_ADDRESS\fP.
.PP
Variants of the script have been used extensively at Zip World
(http://www.zipworld.com.au/) for backing up 
mail, web and proxy servers.
Although this system has been shown to work you are well advised to
test the system thoroughly before putting it into production.
.PP
Please read the documents in \fI/usr/share/doc/fake/\fP
for an explanation of how \fBfake\fP works
and for a discussion of issues surrounding its use.
.SH OPTIONS
.TP
.B remove
Stop the takeover of an IP address.
Without this option, fake starts the takeover of an IP address.
.SH "GLOBAL CONFIGURATION FILE"
The global configuration file is in \fI/etc/fake/.fakerc\fP.
The settings there are overridden by those in \fI${HOME}/.fakerc\fP.
Here is a sample configuration file.
.nf

############################################################
# Set up basic environment for fake
# Variables are set as bash variables
# i.e. <VARIABLE>=<value>
#
# Must set:
#  ARP_DELAY: Delay in seconds between gratuitous ARP
#  PID_DIR: Directory where PID files are kept
#  INSTANCE_CONFIG_DIR: Directory where specific
#   configuration files for an IP address takeover are kept
#  CLEAR_ROUTERS_FILE: New line delimited list of routers to rsh
#    to and execute "clear arp-cache"
#  FAKE_RSH: Programme to use to "rsh" to another machine
#    to obtain macaddress by running ifconfig
#
# PATH can be set here to ensure that send_arp is in the
#  path
############################################################

FAKE_HOME="/etc/fake"

#PATH=/sbin:/usr/sbin:/bin:/usr/bin

ARP_DELAY=1
CLEAR_ROUTERS_FILE="$FAKE_HOME/clear_routers"
PID_DIR="/var/run"
INSTANCE_CONFIG_DIR="$FAKE_HOME/instance_config"

#Only needed if you wish to send gratuitous ARP
#advertising the "real" mac address when turning fake off
#FAKE_RSH=ssh

.fi
.SH "INSTANCE CONFIGURATION"
To configure an instance of \fBfake\fP,
create \fI/etc/fake/instance_config/<IP-address-to-take-over>.cfg\fP
with the following format:
.nf

SPOOF_IP=<IP-address-to-take-over>

.fi
The SPOOF_IP variable must contain the same IP address as appears
in the name of the file.
This is checked at run time.
.nf

IFCONFIG=TRUE|FALSE
SPOOF_NETMASK=<netmask-of-network-that-IP-address-to-take-over-is-on>
TARGET_INTERFACE=<interface-to-bring-up>

.fi
If the IFCONFIG variable is set to \fBTRUE\fP, the address specified by SPOOF_IP
will be brought up on the interface specified by TARGET_INTERFACE;
SPOOF_NETMASK and TARGET_INTERFACE must also be defined.
.PP
For obvious reasons it is very important that the TARGET_INTERFACEs
of running instances of \fBfake\fP all be different from one another.
.PP
Optionally if you wish to \fBrsh\fP to the main server and
advertise the "real" MAC address when turning \fBfake\fP off then
set the following;
.nf

FOREIGN_INTERFACE=<interface-on-foreign-host-with-MAC-address-to-use>
FOREIGN_ARP=<number-of-ARPs-to-send-with-real-MAC-address>

.fi
To use this last feature in an automated fashion you will
need to be able to $FAKE_RSH to $SPOOF_IP from the host that
\fBfake\fP runs on without manual authentication.
With \fBrsh\fP this is typically achived using \fI.rhosts\fP;
with \fBssh\fP an RSH key with an empty passphrase can be employed.
.PP
Here is an example of \fI/etc/fake/instance_config/203.12.97.7.cfg\fP:
.nf

SPOOF_IP=203.12.97.7
IFCONFIG=TRUE
SPOOF_NETMASK=255.255.255.0
TARGET_INTERFACE=eth0:2
FOREIGN_INTERFACE=eth0
FOREIGN_ARP=5

.fi
.SH ACTIVATION
To activate \fBfake\fP, run:
.nf

fake <IP-address-to-take-over> &

.fi
Logs will be made to the local0.notice syslog facility.
.PP
On startup you should see messages in the syslog;
running \fBifconfig\fP should show the new interface;
running \fBroute\fP should show a route for the spoofed IP address
on the new interface (which is needed so the machine that \fBfake\fP
is running on can communicate correctly to this IP address);
and
running \fBtcpdump -i <interface> arp\fP should show the
gratuitous ARP packets.
.SH DEACTIVATION
To deactivate, run:
.nf

fake remove <IP-address-to-take-over>

.fi
.PP
As of version 1.1.2 the \fBfake\fP process can be sent a SIGTERM or
SIGHUP to effect the removal.
.PP
On removal you should see a message in the syslog;
\fBifconfig\fP should show that the new interface has been removed;
\fBroute\fP should show that the new route has been removed;
and
\fBtcpdump\fP should show that the gratuitous ARP has stopped.
.PP
.B Note: 
Activating \fBfake\fP multiple times with the same
arguments has the same effect as activating it once.
Similarly, deactivating fake multiple times with the same arguments
has the same effect as deactivating it once.
.SH FILES
.TP
.I /etc/fake/.fakerc
.TP
.I /etc/fake/clear_routers
.TP
.I /etc/fake/instance_config/<IP-address>.cfg
.TP
.I /var/run/fake.<IP-address>.pid
.SH AUTHOR
Horms <horms@verge.net.au>