ipguard(8)

📦 version 1.04, in arch rolling

💖 ipguard(8): the ARP-protecting bestie you didn't know you needed 💖

okay so real talk, ipguard is from the System Manager's Manual and honestly? it's giving protective bouncer energy for your Ethernet LAN. no cap.

🌸 NAME 🌸

ipguard — a whole tool designed to protect Ethernet LAN IP address space by ARP spoofing. literally what it says on the tin, bestie.

✨ SYNOPSIS ✨

ipguard [-h] [-ajgrxziovd] [-f ethers] [-l log] [-p pid] [-m mac] [-c
filter] [-u seconds] [-k seconds] [-n fakes] [-t mseconds] [-b buf] [-s
user] <iface>

yeah it's a lot of letters. we'll get through it together, don't worry 🫶

🦋 DESCRIPTION 🦋

so here's the vibe: ipguard listens on the network for ARP packets. all the permitted MAC-IP pairs are listed in the ethers file. (that's the guest list, basically.)

if it receives a packet with a MAC-IP pair that is not in the ethers file? it sends an ARP reply with a configured fake address. and that will prevent the not-permitted host from working properly in the local ethernet segment. it's not mean, it's just... setting boundaries. 💅

🎀 OPTIONS 🎀

  • -f | -e ethers — the ethers file. the format of the ethers file is described in ethers.sample and in ethers(5). default is /etc/ethers.
  • -l log — the log file. default is /var/log/ipguard_<iface>.log.
  • -p pid — the pid file. default is /var/run/ipguard_<iface>.pid.
  • -m mac — the fake MAC address. this gets sent in the ARP reply as the MAC of an unlisted computer. default is de:ad:xx:xx:xx:xx, where x is a random hex number. iconic honestly.
  • -c filter — a PCAP filter expression. default is no filter.
  • -u seconds — the update ethers interval. this is the time between checks of the ethers file for changes, and it rescans if there are any. default 0 means no autoupdate.
  • -k seconds — periodically regenerate the fake MAC address. default 0 means no regenerate.
  • -n fakes — the fake replies number. default is 2 replies.
  • -t mseconds — time between fakes. default is 50 milliseconds.
  • -b buf — the MAC buffer size. that's the number of last bad MAC-IP pairs stored in the buffer. default 0 means no buffer.
  • -s user — drop root privileges to user. default is do not drop.
  • -a — no address substitution. like 0.0.0.0 or 00:00:00:00:00:00.
  • -j — disable first MAC-IP pair autodetect from the interface.
  • -g — default to grant. do not block a MAC or IP if both are not in the list.
  • -r — read only. do not send anything to the net, only listen. it's giving observer mode 👀
  • -x — duplex mode. send fake packets not only to the pirate but to the request for the pirate's address too.
  • -z — send broadcast who-has to fix all client ARP tables that got broked by the pirate. we're healing the group chat 🫶
  • -i — hidden mode. do not block gratuitous ARP packets.
  • -o — promiscuous mode. enable promiscuous mode. usually useless (their words, not mine).
  • -v — verbose. some more messages.
  • -d — don't fork. do not go to background and write all events to STDERR.
  • -dd — debug.
  • -ddd — debug more. the triple d, the final form.
  • -h — help. short command line parameters description.

🌈 EXAMPLES 🌈

normal recommended mode, duplex, broadcast fix, autoupdate /etc/ethers every 5 min:

ipguard -xz -u 300 fxp0

same but with a PCAP filter for only the 192.168.1.0/24 network:

ipguard -xz -u 300 -c 'net 192.168.0.0/24' fxp0

read-only mode and remember the last 100 MACs not listed in ethers. useful for initial MAC-IP pairs collection:

ipguard -r -b 100 -f /dev/null rl0

run ipguard for a while then killall -USR2 ipguard and you'll get a dump of the 100 most recent MAC-IP pairs. slay.

do not go to background and be more verbose, with a test ethers file:

ipguard -vd -f /tmp/ethers my1

💜 TIPS 💜

the first MAC-IP pair in ethers always must be self MAC/IP addresses. normally they're automatically taken from the listening interface. but if the -j option is specified, then make sure that the first pair is a source MAC/IP. iykyk.

if you want to start more than one ipguard on the segment for redundancy, you must specify the same fake MAC address for every ipguard and find a method to synchronize the ethers files. teamwork makes the dream work fr.

⭐ SIGNALS ⭐

  • SIGHUP — rescan ethers and reopen the log file.
  • SIGUSR1 — dump some tables and statistics.
  • SIGUSR2 — dump the new MAC-IP table in ethers(5) format.

🍓 FILES 🍓

  • /etc/ethers — MAC-IP pairs list.
  • /var/log/ipguard_<iface>.log — log file.
  • /var/run/ipguard_<iface>.pid — pid file.

🔥 SEE ALSO 🔥

RFC 826, ethers(5), tcpdump(1), pcap(3), libnet

💀 BUGS 💀

  • Do not use wildcard IP 0.0.0.0 in ethers with the -x option. legal clients will be banned. discovered by irix. not the vibe.
  • strange bug with libnet_get_hwaddr() isn't working on OpenBSD 4.0, discovered by irix. use the -j option.
  • ipguard will not prevent changing the MAC address along with the IP by the pirate. it's not a miracle worker bestie.
  • signals HUP, USR1 or USR2 work only when received with a new ARP packet. it's not a bug, it's a feature. periodt.
  • when using the -s <user> option, ipguard will drop root privileges after creating the log and pid files. so it will not delete or reopen these files.
  • probably too many command line options. another one or two and i'll put them all into /etc/ethers as comments. (author is so real for this 😭)
  • ipguard was written as a simple small tool and the author hasn't any plans for support of external databases SQL/LDAP/Whatever. use scripts.

👑 AUTHOR 👑

SeaD <sead at deep.perm.ru>

okay that's the whole thing, bestie. this page is from the System Manager's Manual, source/version and date at the bottom: ipguard(8) 🦋✨ you're gonna do great out there with your ARP tables protected. muah 💋

📦 where this page comes from