#############################################################################
##  |\   ======   /|  ##           noarp - MasarLabs ARP Filter            ##
##  |__\========/__|  ##      filters and drops unwanted ARP requests      ##
##  |\            /|  ##  ===============================================  ##
##  |  \        /  |  ##           Maurizio Sartori (c) 2002-2004          ##
##  |    \    /    |  ##  ===============================================  ##
##  |    /=\/=\    |  ##                    Written  by                    ##
##  |  /========\  |  ##              Maurizio Sartori 'masar'             ##
##  |/   ======   \|  ##            e-mail:  masar@MasarLabs.com           ##
#############################################################################
## $Id: README 24 2004-03-05 12:26:34Z svn $
#############################################################################
##
## 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
##
#############################################################################

1 - What is it ?
  MasarLabs NoArp is a Linux kernel module that filters and drops
  unwanted ARP requests.

  It is useful when you need to add an alias to the loopback interface
  to use a load balancer.

  For more details about this problem see:
    http://www.austintek.com/LVS/LVS-HOWTO/HOWTO/LVS-HOWTO.arp_problem.html
    http://www.linuxvirtualserver.org/docs/arp.html

2 - Requisites
  You need 'noarp 2.x' for kernel 2.6.x.
  You need 'noarp 1.x' for kernel 2.4.x.

  You must have the kernel build directory tree yet configured
  and ready for compilation.

  You need to have write permissions to the kernel build directory,
  if you do not have it, you can use the '--with-kcopy' option that
  will make a local copy of that directory; note that the copy
  could be very space consuming (420 MB for a full compiled kernel tree,
  20 MB for only the headers tree).

  NOTE: if in the kernel build directory 'vmlinux' or 'vmlinux.syms'
        are not present, the 'noarp.ko' module will 'taint' your
        kernel but no funtionality is lost.
        See "What does it mean for a module to be tainted?"
           <http://www.tux.org/lkml/>

3 - Install
  To install:

    ./configure
    make
    make install-strip
    depmod -a
    modprobe noarp

  By default the programs are installed in

    /usr/local/lib/modules/$(uname -r)/local/noarp.o
    /usr/local/sbin/noarpctl
    /usr/local/man/man4/noarp.4
    /usr/local/man/man8/noarpctl.8

  NOTE: if you install the noarp.o module in a directory that
        is not below '/lib/modules/$(uname -r)', you should add a
        path line into '/etc/modules.conf' like this:

                path=/usr/local/lib/modules/`/bin/uname -r`

        Read the 'modules.conf' man page for the security implications
        that this line can generate.

        If you don't want to add the line you could copy the module
        into '/lib/modules/$(uname -r)/local' or run the configure
        script with the options:

                --prefix=/ --sbindir=/usr/sbin --mandir=/usr/share/man

  If you want to customize the compilation and the installation, you can call
  configure with the following options (defaults are in []):

    --prefix=PREFIX         install architecture-independent files in PREFIX
                               [/usr/local]
    --with-kversion=VERSION specify the kernel version to compile for
                               [$(uname -a)]
    --with-kbuild=DIR       specify the location of the kernel build directory
                               [/lib/modules/$kversion/build]
    --with-maxvip=NUM       specify the maximum number of VIP allowed [16]
    --with-moduledir=DIR    specify where to install the kernel module
    --with-kcopy            copy the kernel build directory instead of linking

  For example:
    configure --prefix=/ \
              --sbindir=/usr/sbin \
              --mandir=/usr/share/man \
              --with-kversion=2.6.2-1-686 \
              --with-kbuild=/usr/src/kernel-source-2.6.2-1-686 \
              --with-maxvip=32 \
              --with-kcopy

4 - Use
  To use correctly you must load the 'noarp.o' module before you
  configure your loopback alias.

  Suppose we want this configuration:

  eth0  10.20.41.89             Real IP of Server (RIP)
  lo:1  10.20.41.90             Virtual IP for WEB1 (VIP)
  lo:2  10.20.41.91             Virtual IP for WEB2 (VIP)

  The basic syntax of 'noarpctl' is:
    noarpctl add VIP RIP

  That means hide the VIP address and use RIP in outgoing ARP
  requests that would use VIP.

  So in a Debian '/etc/network/interfaces' I'll put theese lines:

    # The loopback configuration
    auto lo
    iface lo inet loopback
    pre-up /sbin/modprobe noarp
    pre-up /usr/local/sbin/noarpctl add 10.20.41.90 10.20.41.89
    pre-up /sbin/ifconfig lo:1 10.20.41.90 netmask 255.255.255.255
    pre-up /usr/local/sbin/noarpctl add 10.20.41.91 10.20.41.89
    pre-up /sbin/ifconfig lo:2 10.20.41.91 netmask 255.255.255.255
    post-down /sbin/rmmod noarp
    # End of loopback configuration

5 - Thanks

  My thanks to who helped me for this project, in particular to:

    - Sbastien Bonnet for his suggestions and spelling check.
    - Harley A. Stenzel for finding the "observer" problem

6 - Copyright

  Copyright MasarLabs.com (c) 2002-2004
  Written by Maurizio Sartori <masar@MasarLabs.com>

  This program is free software; you may redistribute it
  under the terms of the GNU General Public License.
  This program has absolutely no warranty.

