gratuitous-arp-0.42 README

Description
===========
When an IP address (or a set of addresses) moves from one device to
another, it is often necessary to communicate this IP migration to other
devices on the network.  Many IP stacks accept these so-called
gratuitous ARP messages and refresh their ARP cache accordingly.  Though
arguably a security problem, the behaviour is very convenient in the
following situations:

  - failover where the machines are NOT sharing a MAC address
  - swapping machines, moving an IP (or a set of IPs) from one active
    device to another machine
  - stealing multiple IPs from your friends during LAN parties

There are two major arping utilities.  Despite the rich set of options
and features offered by the newer arping by Thomas Habets, it doesn't
easily support gratuitous ARP.  Thus, this utility relies on the arping
supplied with iputils, written by Alexey Kuznetsov.  If you have both
installed, simply set the $PATH appropriately before calling this
script, or try the --arping (-a) option to specify the path to your
iputils arping.


Arguments
=========
This utility accepts an arbitrary number of <ipaddr> arguments and will
transmit a gratuitous ARP for each specified IP address.  It will loop
serially through the entire list of IP addresses specified as arguments.


Options
=======
The default delay time between ARP transmissions is 1 seconds, but
can be controlled with the --delay (-d) option.  Specifying a delay of
zero (0) causes us to send ARP frames as fast as we can, which ain't
that fast, since this whole thing is written in shell.

gratuitous-arp will loop over the arguments by default 3 times.
This can overriden by using the --count (-c) option.  Specifying a count
of zero (0) will cause the utility to loop forever.

There are two common ARP packet types used for gratuitous ARP functions.
The options --unsolicited (-U) and --answer (-A) select the desired type.

The --arping (-a) option allows the user to specify the path to the
desired arping binary, instead of relying on $PATH.


Common error
============
If you see an error message like below (one of the most common error
messages with gratuitous ARP using arping), check your <interface> to
see that it has the <ipaddr> listed.  You will not be able to issue a
gratuitous ARP unless the address is available on the specified
interface.

   E: 10.10.20.37 on eth0: bind: Cannot assign requested address


Examples
========
typical usage; advertise 3 times for 10.10.20.37 on eth0
  gratuitous-arp -i eth0 10.10.20.37

send 10 frames advertising 10.10.20.37 on eth0, and shut up!
  gratuitous-arp --count 10 --quiet --interface eth0 10.10.20.33

with no interframe delay on eth2, advertise for both .2 and .3
  gratuitous-arp --delay 0 --quiet -i eth2 192.168.1.2 192.168.1.3

Usage: gratuitous-arp [ options ] <ipaddr> [ <ipaddr> ... ]

Options (defaults marked, or in parentheses):
  -h, --help               Print out this handy help screen.
  -L, --long-usage         Provide help and some more hints.
  -q, --quiet              Reset verbosity to none.
  -v, --verbose            Increase verbosity, can be used multiple times.
  -U, --unsolicited        Use unsolicited ARP frames.
  -A, --answer             Use ARP answer frames. (default)
  -c, --count <number>     Packet count. (3)
  -i, --interface <name>   Specify an interface. (eth0)
  -d, --delay <seconds>    Inter-frame delay in seconds. (1)
  -a, --arping <path>      Full path to iputils arping. (arping in $PATH)