ip-sentinel(8)

📦 version 0.12, in fedora 43, fedora 44

okay bestie, sit down, we're reading ip-sentinel(8) — straight out of the System Manager's Manual. Yes it's a daemon page. Yes it's got warnings. Yes we're doing this together. 🫶

✨ NAME ✨

ip-sentinel — keeps your IP space clean 💅

🌸 SYNOPSIS 🌸

ip-sentinel [--user|-u username] [--group|-g groupname] [--chroot|-r
dir] [--ipfile|-i file] [--pidfile|-p file] [--logfile|-l file]
[--errfile|-e file] [--mac mac] [--llmac mac] [--direction dir]
[--action program] [--nofork|-n] [--help|-h] [--version] interface

🦋 DESCRIPTION 🦋

So. ip-sentinel boots up a daemon whose whole entire job is stopping unauthorized usage of IPs inside an ethernet broadcastdomain — and it does that by answering ARP requests. 🎯

The way it works is lowkey genius: once the requesting party gets that faked reply, it stores the MAC address in its ARP-table, and from then on it sends all its future packets to that invalid MAC. Which means the IP is just… unreachable. Rendered useless. Ghosted. 💀

After startup it opens its logfiles, goes into a chroot jail, drops privileges, and forks itself into background by default. Every one of those operations is configurable with the options down below, bestie. ✨

Warning: with an uncareful configuration, ip-sentinel can bring down the entire network and your physical presence at the ip-sentinel machine and/or the switch will be required to fix it. 😭 Some switches can show an unexpected behavior and even crash when the special 802.* mac-addresses get used. So like… be careful. fr fr.

🎀 OPTIONS 🎀

  • --user|-u username and --group|-g groupname — after doing basical initializations, the program drops its privilegies by changing its user and group ID. The username and groupname parameters decide these new IDs, and they have to be an alphanumeric username/groupname or a numeric uid/gid. 🫶
Attention: if you've got a dietlibc-compiled version on a system that uses remote NSS (like LDAP, NIS) for passwd-lookups, you will have to use numeric IDs. no cap.
  • --chroot|-r dirname — tells the program which directory to go into and call chroot() in, after it finishes its initialization. Default? It's the homedirectory of the user you specified with the --user option. 🏠
  • --ipfile|-i filename — sets the name of the configuration file holding the list of forbidden IPs. This name is relative to the chroot, and it's ips.cfg by default. This file gets reread automatically after changes, so you can just edit and go. ✨
  • --pidfile|-p filename — sets the file where the pid of the daemon gets written. This filename is relative to the root-filesystem, and it's /var/run/ip-sentinel.run by default. 📝
  • --logfile|-l filename — sets the file where normal operations get logged. "Normal operations" means stuff like an ARP-reply for a forbidden IP. This filename is relative to the root-filesystem, and it's /var/log/ip-sentinel.out by default. 🌈
  • --errfile|-e filename — sets the file where error-conditions get logged. Error-conditions are things like detected DOS attacks (aka bombing the ip-sentinel with ARP-requests) or errors in the configuration file. This filename is relative to the root-filesystem, and it's /var/log/ip-sentinel.err by default. 🚨
  • --nofork|-n — prevents the daemon from going into background after initialization. This one's useful when you're using advanced init-concepts like minit (http://www.fefe.de/minit/). 👑
  • --direction dir — ip-sentinel can answer both requests asking for an intruder's address, and requests coming from an intruder asking for official addresses. This parameter says which requests shall be answered. Possible values are FROM (requests from intruders), TO (requests to intruders) and BOTH. The current default value is TO, but it will probably change to BOTH in future versions. 👀
  • --mac mac — use mac as the default faked mac-address; see below for the possible values. This parameter can be overriden in the ipfile for each questionable IP. The default value is RANDOM. 🎲
  • --llmac mac — specifies the mac-address used in the link-level headers when answering requests from intruders. On top of the values described below, ip-sentinel also understands the SAME string, which means the address from the ARP-header will be used. If you're not using the FROM or BOTH directions, the assigned value won't have any effect. The default is LOCAL. 💅
  • --poison — when an intruder sends a request from a registered ip address and this option is set, ip-sentinel will send ARP replies that are poisoning this ip. When the @!srcmac syntax is used for the questionable ip, the srcmac is used as the is-at mac. Else, the mac specified by the --mac option is used. ☠️

This option takes an affect only when --destination BOTH or FROM is specified.

  • --action program — execute program when a faked ARP reply gets generated. It will be called with 6 arguments:
    • type — 0 when an intruder sent the request, 1 when a protected IP was requested, and -1 else (should never happen) 🙈
    • spa — the protocol address (IP) of the source
    • sha — the hardware address (MAC) of the source
    • tpa — the protocol address (IP) of the target
    • tha — the hardware address (MAC) of the target
    • mac — the generated MAC address

The program will be executed only without evaluating its return value or something else. Also please note that the program will be executed in the chroot with restricted rights. 🔒

  • --help|-h — prints help message and exits. 🫶
  • --version — prints the version of the program and exits. ⭐
  • interface — specifies the network-interface where ip-sentinel listens for ARP-requests and sends ARP-replies. It's a name like "eth0"; aliases like "eth0:1" are not possible. 🚫

and that's it for this part, bestie — the rest is coming, don't go anywhere 🌸

🎀 CONFIGURATION FILE 🎀

okay bestie, so where does this file even live? The location of the configfile is relative to the chosen chroot-directory. Its default is baked in at compilation time, but you can override it with the --ipfile option. 💅

The content of this file follows this syntax, and I'm gonna walk you through literally every single form because there are no skips on this tour:

  • ip [mac] — says this ip shall be blocked. And "blocked" means ARP-replies will be generated telling everyone that the IP address ip has the MAC mac. No mac given? A random one gets chosen for you. 🎲
⚠️ Attention: assigning a MAC in a switched environment will not have the desired effect, because the switch will be confused when receiving ARP-replies for the same IP on different ports (this one of the bad-host and this one of the ip-sentinel host). Yeah. Chaos.

Examples are: 192.168.42.23 11:22:33:44:55:66 or 10.0.0.0.

  • ip@[!]srcmac [mac] — same energy as above, but when receiving ARP-requests, the entire sender-address (IP and MAC) gets compared against the ip and srcmac values. This setting affects packets from intruders only; ip-sentinel will not generate replies when ip is requested. 🕵️♀️

When the srcmac is negated with !, only addresses from this ip which are not having this mac will be matching.

Examples are: 10.0.0.1@0:1:2:3:4:5 or 10.0.0.2@!a:b:c:d:e:f.

  • *@srcmac [mac] — every host using the srcmac will be blocked unless there is a matching ip@srcmac specification. Heads up: this option does not support ! modifiers. 🙅♀️
  • net/mask [mac] / net/mask@[!]srcmac [mac] — says IPs of an entire network shall be blocked. See above for the meaning of "blocked". You can specify a MAC address; else a random one will be generated. ✨

Examples are: 169.0.0.0/8, 192.168.8.15/255.255.65.31 or 192.168.23.42/26 a:b:c:d:e:f.

  • !ip / !ip@[!]srcmac — the given IP address ip will be ignored. By default, any not specified address will be ignored, but when you've got blocked netmasks it may be useful to allow certain IPs. 🫶

An example is: !192.168.23.42

  • !net/mask / !net/mask@[!]srcmac — tells that IPs of the given network shall be ignored.

Examples are: !192.168.1.0/255.255.255.0 or !0.0.0.0/0 (the default).

  • # comment (and empty lines) — a comment; will be ignored. Bestie, your notes are safe. 📝

To be switch-friendly, there are only a few random MACs possible, and they're having the format de:ad:be:ef:00:XX. Within a short timespan only 32 values are possible for XX.

When having overlapping networks and/or single IPs, the one with the most specified netmask (count of 1's) takes precedence. When netmasks are equal, networks which are using the @srcmac or @!srcmac syntax are taking precedence over those without source-macs. This @... rule does not apply to IPs. And the behavior is unspecified when having overlapping networks with the same count of 1's and @... specification, or when having duplicate IPs. 💀

⚡ PERFORMANCE ⚡

The lookup of single IPs has a complexity of O(log n) and this of netmasks a complexity of O(n). Slay, math. 🧮

🌈 SPECIAL MAC ADDRESSES 🌈

Beside the usual hex-octets-delimited-by-colons mac addresses, ip-sentinel understands some special strings both on the commandline and in the configuration file:

  • LOCAL — expands to the mac-address of the used interface. 👑
  • RANDOM — means a random mac-address which is newly calculated on every usage. 🎰
  • 802.1d — expands to 01:80:C2:00:00:00 which is the "Bridge Group Address".
  • 802.3x — expands to 01:80:C2:00:00:01 which is the "IEEE Std. 802.3x Full Duplex PAUSE operation". This MAC address will be blocked by a lot of switches and will probably become the default in future versions. 🔥

The 802.* addresses are having a special meaning for some switches, and packets having them as destination-address will be dropped by the switch instead of flooding all ports. But it depends on the used switch how/if these macs are honored. 🤷♀️

💀 Some switches can show an unexpected behavior or even crash if the special 802.* mac-addresses will be used. No cap, be careful.

🎀 RANGES 🎀

Except in comments, it is possible to specify ranges everywhere in the configuration file. These ranges are having the format {from-to} or {item1,item2,...,itemN}. The first format includes any number beginning at from till to (inclusive), while the latter format expands to the listed items only. The expansion happens on a line-level and it is possible to use more than one range per line, so that

192.168.0.{1-3}     0:0:0:0:0:1
192.168.1.{1,3}     0:0:0:0:0:2
192.168.{2,4}.{1-3} 0:0:0:0:0:3

is the same like writing

192.168.0.1         0:0:0:0:0:1
192.168.0.2         0:0:0:0:0:1
192.168.0.3         0:0:0:0:0:1
192.168.1.1         0:0:0:0:0:1
192.168.1.3         0:0:0:0:0:1
192.168.2.1         0:0:0:0:0:3
192.168.2.2         0:0:0:0:0:3
192.168.2.3         0:0:0:0:0:3
192.168.4.1         0:0:0:0:0:3
192.168.4.2         0:0:0:0:0:3
192.168.4.3         0:0:0:0:0:3
⚠️ Because there can be created very much entries with a single line (e.g. {0-255}.{0-255}.{0-255}.{0-255} would cover the entire IPv4 internet), ranges should be used sparely. When possible, large ranges should be expressed with netmasks. Bestie, don't do that to your config. 😭

🌟 EXAMPLE 🌟

0.0.0.0/0                 ## Block anything
!192.168.0.0/24           ## Allow IPs of the form 192.168.0.*
192.168.0.0               ## but block 192.168.0.0
192.168.0.1 a:b:c:d:e:f   ## use a special mac for 192.168.0.1
192.168.0.2 802.1d        ## and 01:80:C2:00:00:00 for 192.168.0.2
10.0.0.1@a:a:a:a:a:a
10.0.0.2@!1:1:1:1:1:1
*@b:b:b:b:b:b             ## block MAC b:b:b:b:b:b regardless of the IP

This setup will not send ARP-replies for the IPs 192.168.0.{3-255} but when a host tries to use e.g. 169.254.145.213, ip-sentinel will tell that this IP has a MAC of de:ad:be:ef:00:XX. iconic behavior honestly. ✨

When an intruder is at 10.0.0.1 and uses the mac a:a:a:a:a:a:, a faked reply will be generated. Users at the same ip but another mac will be ignored. 🙈

In opposite, users with ip 10.0.0.2 and mac 1:1:1:1:1:1 will be ignored but intruders with other macs (e.g. 2:2:2:2:2:2) are getting faked replies. When --poision is used, ip-sentinel will generate a 10.0.0.2 is at 1:1:1:1:1:1 arp-reply to a broad address. 💅

🦋 SEE ALSO 🦋

RFC 826, IEEE Std 802.1D

💖 AUTHOR 💖

Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>

and that's a wrap bestie 🫶 this whole thing is ip-sentinel version 0.11, dated Dec 15 2004 — shoutout to the legend Enrico Scholz, and yeah the page itself signs off as ip-sentinel(8). go forth and block those IPs, mwah 💅🎀

📦 where this page comes from