Annotation of embedaddon/ipguard/doc/ipguard.8, revision 1.1
1.1 ! misho 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.15 2010/07/12 03:46:52 sead 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>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ipguard.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ipguard / doc