Return to ipguard.8 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ipguard / doc

ipguard

    1: .\"
    2: .\"  ipguard.8
    3: .\"
    4: .\" Copyright (c) 2010 SeaD <sead at deep.perm.ru>
    5: .\"
    6: .\" Redistribution and use in source and binary forms, with or without
    7: .\" modification, are permitted provided that the following conditions
    8: .\" are met:
    9: .\" 1. Redistributions of source code must retain the above copyright
   10: .\"    notice, this list of conditions and the following disclaimer.
   11: .\" 2. Redistributions in binary form must reproduce the above copyright
   12: .\"    notice, this list of conditions and the following disclaimer in the
   13: .\"    documentation and/or other materials provided with the distribution.
   14: .\"
   15: .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
   16: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   17: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   18: .\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
   19: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   20: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   21: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   22: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   23: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   24: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   25: .\" SUCH DAMAGE.
   26: .\"
   27: .\"##  $Id: ipguard.8,v 1.1.1.1 2012/02/21 21:59:41 misho Exp $
   28: .\"
   29: .TH ipguard 8
   30: 
   31: .SH NAME
   32: .PP
   33: ipguard \- tool designed to protect Ethernet LAN IP address space by ARP spoofing.
   34: 
   35: .SH SYNOPSIS
   36: .PP
   37: .B ipguard
   38: [\-h] [\-ajgrxziovd]
   39: [\-f \fIethers\fP]
   40: [\-l \fIlog\fP]
   41: [\-p \fIpid\fP]
   42: [\-m \fImac\fP]
   43: [\-c \fIfilter\fP]
   44: [\-u \fIseconds\fP]
   45: [\-k \fIseconds\fP]
   46: [\-n \fIfakes\fP]
   47: [\-t \fImseconds\fP]
   48: [\-b \fIbuf\fP]
   49: [\-s \fIuser\fP]
   50: <\iface>
   51: 
   52: .SH DESCRIPTION
   53: .PP
   54: ipguard listens network for ARP packets. All permitted MAC-IP pairs
   55: listed in 'ethers' file. If it receives one with MAC-IP pair, which is
   56: not listed in 'ethers' file, it will send ARP reply with configured
   57: fake address. This will prevent not permitted host to work properly
   58: in local ethernet segment.
   59: 
   60: 
   61: .SH OPTIONS
   62: .TP
   63: .B \-f | -e " \fIethers\fP"
   64: Ethers file. Format of `ethers' file described in `ethers.sample' and ethers(5). Default `/etc/ethers'.
   65: .TP
   66: .B \-l " \fIlog\fP"
   67: Log file. Default `/var/log/ipguard_<iface>.log'.
   68: .TP
   69: .B \-p " \fIpid\fP"
   70: Pid file. Default `/var/run/ipguard_<iface>.pid'.
   71: .TP
   72: .B \-m " \fImac\fP"
   73: Fake MAC address. Will be sent in ARP reply as MAC of unlisted computer. Default `de:ad:xx:xx:xx:xx', `x' == random hex number.
   74: .TP
   75: .B \-c " \fIfilter\fP"
   76: PCAP filter expression. Default no filter.
   77: .TP
   78: .B \-u " \fIseconds\fP"
   79: Update ethers interval. Time between checks `ethers' file for changes and rescan if any. Default 0 == no autoupdate.
   80: .TP
   81: .B \-k " \fIseconds\fP"
   82: Periodic regenerate fake MAC address. Default 0 == no regenerate.
   83: .TP
   84: .B \-n " \fIfakes\fP"
   85: Fake replies number. Default 2 replies.
   86: .TP
   87: .B \-t " \fImseconds\fP"
   88: Time between fakes. Default 50 milliseconds.
   89: .TP
   90: .B \-b " \fIbuf\fP"
   91: MAC buffer size. Number of last bad MAC-IP pairs stored in buffer. Default 0 == no buffer.
   92: .TP
   93: .B \-s " \fIuser\fP"
   94: Drop root privileges to user. Default do not drop.
   95: .TP
   96: .B \-a
   97: No address substitution. Like 0.0.0.0 or 00:00:00:00:00:00.
   98: .TP
   99: .B \-j
  100: Disable first MAC-IP pair autodetect from interface.
  101: .TP
  102: .B \-g
  103: Default to grant. Do not block MAC or IP if both not in list.
  104: .TP
  105: .B \-r
  106: Read only. Do not send anything to net. Only listen.
  107: .TP
  108: .B \-x
  109: Duplex mode. Send fake packets not only to pirate but to request for pirate's address too.
  110: .TP
  111: .B \-z
  112: Send broadcast who-has to fix all client ARP tables broked by pirate.
  113: .TP
  114: .B \-i
  115: Hidden mode. Do not block gratuitous ARP packets.
  116: .TP
  117: .B \-o
  118: Promiscuous mode. Enable promiscuous mode. Usually useless.
  119: .TP
  120: .B \-v
  121: Verbose. Some more messages.
  122: .TP
  123: .B \-d
  124: Don't fork. Do not go to background and write all events to STDERR.
  125: .TP
  126: .B \-dd
  127: Debug
  128: .TP
  129: .B \-ddd
  130: Debug more
  131: .TP
  132: .B \-h
  133: Help. Short command line parameters description.
  134: 
  135: .SH EXAMPLES
  136: .TP
  137: Normal recommended mode, duplex, broadcast fix, autoupdate /etc/ethers every 5 min:
  138: .B ipguard -xz -u 300 fxp0
  139: .TP
  140: Same but with PCAP filter for only 192.168.1.0/24 network:
  141: .B ipguard -xz -u 300 -c 'net 192.168.0.0/24' fxp0
  142: .TP
  143: Read-only mode and remember last 100 not listed in `ethers' MACs. Useful for initial MAC-IP pairs collection:
  144: .B ipguard -r -b 100 -f /dev/null rl0
  145: .TP
  146: Run ipguard for a while then `killall -USR2 ipguard' and you'll get dump of 100 most recent MAC-IP pairs.
  147: .TP
  148: Do not go to background and be more verbose, with test ethers file:
  149: .B ipguard -vd -f /tmp/ethers my1
  150: .br
  151: 
  152: .SH TIPS
  153: .PP
  154: First MAC-IP pair in `ethers' always must be self MAC/IP addresses.
  155: Normally them automatically taken from listening interface.
  156: But if `-j' option specified then make sure that first pair
  157: is a source MAC/IP.
  158: .PP
  159: If you want to start more than one ipguard on segment for
  160: redundancy, you must specify same fake MAC address for every
  161: ipguard and find method to synchronize `ethers' files.
  162: 
  163: .SH SIGNALS
  164: .TP
  165: .B SIGHUP 
  166: rescan `ethers' and reopen log file
  167: .TP
  168: .B SIGUSR1
  169: dump some tables and statistics
  170: .TP
  171: .B SIGUSR2
  172: dump new MAC-IP table in ethers(5) format
  173: 
  174: .SH FILES
  175: .TP
  176: .B /etc/ethers
  177: MAC-IP pairs list
  178: .TP
  179: .B /var/log/ipguard_<iface>.log
  180: log file
  181: .TP
  182: .B /var/run/ipguard_<iface>.pid
  183: pid file
  184: 
  185: .SH SEE ALSO
  186: .PP
  187: RFC 826, ethers(5), tcpdump(1), pcap(3), libnet
  188: 
  189: .SH BUGS
  190: .PP
  191: Do not use wildcard IP 0.0.0.0 in `ethers' with -x option. Legal clients will be banned. Discovered by irix.
  192: .PP
  193: Strange bug with libnet_get_hwaddr() isn't working on OpenBSD 4.0 discovered by irix. Use -j option.
  194: .PP
  195: ipguard will not prevent changing MAC address along with IP by pirate.
  196: .PP
  197: Signals HUP, USR1 or USR2 works only when received new ARP packet. It's not a bug, it's a feature.
  198: .PP
  199: When using -s <user> option ipguard will drop root privileges after creating log and pid files. So it will not delete or reopen these files.
  200: .PP
  201: Probably too many command line options. Another one or two and i'll put them all into /etc/ethers as comments.
  202: .PP
  203: ipguard was written as simple small tool and i haven't any plans for support of external databases SQL/LDAP/Whatever. Use scripts.
  204: 
  205: .SH AUTHOR
  206: .PP
  207: SeaD <sead at deep.perm.ru>