firehol-iptrap(5)

💖 firehol-iptrap — bestie edition 💖

okay so you're here for firehol-iptrap, which lives in the FireHOL manual pages (that's the firehol-iptrap(5) situation, section 5, very demure, very manual-page). no cap, this one's a banger: it's the helper that dynamically puts IP addresses in an ipset. 🎀

---

✨ NAME ✨

firehol-iptrap — dynamically put IP addresses in an ipset. that's it. that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

{ iptrap | iptrap4 | iptrap6 } ipset type seconds [ timeout | counters ]
[ method method ] [rule-params] [ except [rule-params] ]...

{ ipuntrap | ipuntrap4 | ipuntrap6 } ipset type [ timeout | counters ] [
method method ] [rule-params] [ except [rule-params] ]...

look at her. two whole forms. one traps, one untraps. iconic behavior honestly. 💅

---

💜 DESCRIPTION 💜

so, iptrap adds the IP addresses of the matching packets to ipset. that's the whole job. it sees a packet it likes and it's like "you. ipset. now." ✨

and ipuntrap deletes the IP addresses of the matching packets from ipset. it's the reverse. the breakup arc. 💔

🫶 both helpers do not affect the flow of traffic. like, at all. they do not ACCEPT, REJECT, DROP packets or affect the firewall in any way. they're literally just vibing on the side, taking notes. zero main character energy in the packet path.

ipset is the name of the ipset to use. yep. just the name. 🍓

type selects which of the IP addresses of the matching packets will be used (added or removed from the ipset). type can be src, dst, src,dst, dst,src, etc. and heads up bestie — if type is a pair, then the ipset must be an ipset of pairs too. they gotta match. it's giving "couples costume or nothing". 👑

seconds is required by iptrap and gives the duration in seconds of the lifetime of each IP address that is added to ipset. every matching packet will refresh this duration for the IP address in the ipset. the Linux kernel will automatically remove the IP from the ipset when this time expires. the user may monitor the remaining time for each IP, by running ipset list NAME (where NAME is the ipset parameter given in the iptrap command). so cute of the kernel to do the cleanup for you. 🧚

the seconds value default will not set any seconds. the ipset default will be used. (no drama, just defaults.)

a seconds of 0 (zero), writes to the ipset permanently (this is a feature of the ipset command, not the ipset FireHOL helper). so like, forever-forever. 👀

the keywords timeout and counters are mutually exclusive. pick one, babe, you can't have both. timeout is the default and means that each IP address every time is matched its timeout will be refreshed, while counters means that its packets and bytes counters will be refreshed. and unfortunately the kernel either re-add the IP in the ipset with the new timeout — but its counters will be lost — or just the counters will be updated, but the timeout will not be refreshed. 😭 the kernel said "choose." tragic but real.

method is defines the storage method of the underlying ipset. it accepts all the types the ipset commands accepts. 📚

method and type should match. like, they should be in a situationship that actually works. for example:

• if method is hash:ip then method should be either src or dst
• if method is hash:ip,ip then method should be either src,dst or dst,src
• if method is hash:ip,port,ip method should be src,src,dst or src,dst,dst or dst,src,src or dst,dst,src

for more information check the manual page of the ipset command. 🔥

the rule-params define a set of rule parameters to restrict the traffic that is matched to this helper. see firehol-params(5) for more details. 🫶

except rule-params are used to exclude traffic, i.e. traffic that normally is matched by the first set of rule-params, will be excluded if matched by the second. it's the "not you tho" clause. 🙈

iptrap and ipuntrap are hooked on PREROUTING so it is only useful for incoming traffic. incoming only, bestie. outbound? not invited. 🚪

iptrap and ipuntrap cannot setup both IPv4 and IPv6 traps with one call. the reason is that the ipset can either be IPv4 or IPv6. one or the other. no switching. pick a lane (an address family). 🌈

both helpers will create the ipset specified, if that ipset is not already created by other statements. when the ipset is created by the iptrap helper, the ipset will not be reset (emptied) when the firewall is restarted. she persists. 💅

the ipset options used when these helpers create ipsets can be controlled with the variable IPTRAP_DEFAULT_IPSET_OPTIONS. yes, that's a real environment variable. go nuts. ⭐

---

🔥 EXAMPLES 🔥

💖 Example: mini-IDS

# Example: mini-IDS
# add to the ipset `trap` for an hour (3600 seconds) all IPs from all packets
# coming from eth0 and going to tcp/3306 (mysql).
iptrap4 src trap 3600 inface eth0 proto tcp dport 3306 log "TRAPPED HTTP"
# block them
blacklist4 full inface eth0 log "BLOCKED" src ipset:trap except src ipset:whitelist

catch 'em, then block 'em, but never block the whitelist. the whitelist is sacred. 🎀

💜 Example: ipuntrap

# Example: ipuntrap
ipuntrap4 src trap inface eth0 src ipset:trap proto tcp dport 80 log "UNTRAPPED HTTP"

free them from the trap. releasing them back into the wild. 🦋

🌸 Example: a knock

# Example: a knock
# The user will be able to knock at tcp/12345
iptrap4 src knock1 30 inface eth0 proto tcp dport 12345 log "KNOCK STEP 1"
# in 30 seconds knock at tcp/23456
iptrap4 src knock2 60 inface eth0 proto tcp dport 23456 src ipset:knock1 log "KNOCK STEP 2"
# in 60 seconds knock at tcp/34566
iptrap4 src knock3 90 inface eth0 proto tcp dport 34567 src ipset:knock2 log "KNOCK STEP 3"
#
# and in 90 seconds ssh
interface ...
    server ssh accept src ipset:knock3

a whole port-knocking choreography. knock, knock, knock, and the door opens. it's giving heist movie. 🔥 (note: the interface ... bit is a placeholder, that's literally what the original shows, don't come for me.)

---

👑 SEE ALSO 👑

• firehol(1) — FireHOL program
• firehol.conf(5) — FireHOL configuration
• FireHOL Website
• FireHOL Online PDF Manual
• FireHOL Online Documentation

---

💜 AUTHORS 💜

FireHOL Team. that's them. the whole squad. 🫶

---

and that's a wrap bestie ✨ this page was built by the FireHOL Reference, version 3.1.8, on 13 Apr 2025 — so if you're reading this, go forth and trap responsibly 💅🎀💖