PORTSENTRY.CONF(5)

💖 PORTSENTRY.CONF(5) 💖

okay bestie, so this is portsentry.conf — the main character config file for portsentry. It lives in the File Formats Manual section of the manual, so it's the (5) one, not the (8) one, don't mix them up 💅

---

✨ NAME ✨

portsentry.conf — literally the main configuration file for portsentry, no cap 🎀

---

🌸 DESCRIPTION 🌸

This page is the quick lil' tour of what portsentry.conf actually looks like — it documents the format of portsentry(8)'s config file. Just the format. The basics. The vibe check. 💜

---

👑 OPTIONS 👑

• TCP_PORTS — a comma delimited string of all the TCP ports you want PortSentry to listen on. This string can NOT have any spaces in it, fr fr, none, zero. You can put in as many sockets as you want and PortSentry will try to bind them all up until the default limit of 64.

For the stealth scan detection modes, the ports aren't "bound" per se — instead they're monitored at the socket level for connections 👀

For the Advanced Stealth Scan Detection (peep below) this list is *ignored*.

• UDP_PORTS — same as above except it's for UDP ports. You need to be very careful with UDP mode because an attacker can forge a port sweep and make you block literally any number of hosts 😭 Use this option with caution, or honestly not at all if your host is a well-known Internet connected system.

For the Advanced Stealth Scan Detection (see below) this list is *ignored*.

• ADVANCED_PORTS_TCP — a number saying the highest port number to monitor down from. Any port *below* this number gets monitored. Default is 1024 (the reserved port range) but you can go as large as 65535 (system max). Going over 1024 with this option is recommended ✨
• ADVANCED_PORTS_UDP — same as above except for UDP.
• ADVANCED_EXCLUDE_TCP — a comma delimited string of TCP ports that should be manually excluded from monitoring in Advanced mode. These are usually ports that remote clients might hit by mistake and that shouldn't set off alarms (ident, SSL, etc). 🙈
• ADVANCED_EXCLUDE_UDP — same as above except for UDP.
• IGNORE_FILE — the path to the file holding the IP addresses of hosts you want to always be ignored 🫶
• BLOCKED_FILE — the path to the file holding the IP addresses of blocked hosts 💀
• RESOLVE_HOST — this option turns off DNS resolution for hosts. If your DNS server is slow, turning off resolution may be more effective 🦋
• BLOCK_UDP — this option disables all automatic responses to UDP probes. Because UDP can be easily forged, it may let an attacker start a denial of service attack against the protected host, making it block all manner of hosts that should normally be left alone. Setting this option to "0" disables all responses, although the connects are still logged. This option is mainly useful for Internet exposed hosts. For internal hosts you should leave it enabled. And if someone internally is firing spoofed packets at you, then bestie you have a much bigger problem than a denial of service 😭
• BLOCK_TCP — same as above, but for TCP. Packet forgery isn't as big a problem though, because PortSentry waits for a full connect to occur, and that's much harder to forge in the basic modes. Leave this enabled, even for Internet connected hosts. For stealth scan detection modes the UDP warning applies:

An attacker can cause you to block hosts you don't want to through packet forgery. I wouldn't worry about this until it is a problem, but you should be aware of it.

• KILL_ROUTE — this is the command to run to drop the offending route (see route(8)) if an attack is detected. This is the *full path* to the route command along with the necessary parameters to make the command work. The macro $TARGET$ will be substituted with the attacking host IP and is REQUIRED in this option. Your gateway should be a *dead host* on the local subnet. On some systems though you can just put in the localhost address (127.0.0.1) and this will probably work. All packets from the target host will get routed to this address so don't mess this up. More modern route commands will include a -blackhole or -reject flag. Check your man(1) pages and if your route command supports this feature you should use it (although it's recommend using packet filtering instead, see below).

Also be aware that this creates what's known as an "asynchronous route", which basically means packets enter your host via one route and are sent out on another (dead) route. This works OK for full TCP connect requests, but for UDP and stealth scan modes it still allows packets to activate PortSentry and you may get a series of "already blocked" alarms by PortSentry. For UDP scans this method prevents ICMP messages from returning to the attacker so all ports appear open. However, if the attacker is performing an actual exploit with UDP, the drop route method will not work. The asynchronous route allows the packet to hit the system and the attacker could perform a "blind" attack with UDP if they know what the responses are going to be. 💀

By far the best method is to use the local packet filter (see ipfwadm(8), ipchains(8), or iptables(8)). This is a much cleaner solution and is detailed in the config file. The macro $PORT$ will substitute the port that was connected to by the attacker, but this is NOT required for this option. The macro $MODE$ reports what mode the blocking occurred in (tcp, udp, stcp, sudp, atcp, audp) but is also NOT required.

• KILL_HOSTS_DENY — this is the format of the string to drop into the hosts.deny file that TCP wrappers uses (see hosts_access(5), and hosts_options(5)). Again the $TARGET$ macro is expanded out to be the IP of the attacker and is required. You can also drop in any TCP wrapper escape codes here as well (%h, twist, etc). The macro $PORT$ will substitute the port that was connected to by the attacker, but this is NOT required for this option. The macro $MODE$ reports what mode the blocking occurred in (tcp, udp, stcp, sudp, atcp, audp) but is also NOT required.
• KILL_RUN_CMD — this is a command you want run *before* the route is dropped to the attacker. You can put in any program/script you want executed when an attack is detected. WE NEVER RECOMMEND PUTTING IN RETALIATORY ACTION AGAINST AN ATTACKING HOST. Virtually every time you're port scanned, the host doing the scanning has been compromised itself. So if you retaliate you are probably attacking an innocent(?) party 😭 Also, the goal of security is to make the person GO AWAY. You don't want to irritate them into making a personal vendetta against you. Remember, even a 13 year old can run a [insert favorite D.O.S. program here] attack against you from their Windows box to make your life miserable 💀 As above, the $TARGET$, $PORT$ and $MODE$ macros are available to you but they are not required with this option as above.
• KILL_RUN_CMD_FIRST — setting this to "1" makes the command above run before the route is dropped. Setting it to "0" makes the command run aftter the blocking has occurred. (yes, "aftter", that's what it says, iconic typo, keeping it 🎀)
• SCAN_TRIGGER — PortSentry has a state engine that remembers hosts that connected to it. Setting this value tells PortSentry to allow X number of grace port hits before it reacts. This will detect both sequential and random port sweeps. The default is 0, which reacts immediately. A setting of 1 or 2 will reduce false alarms, anything higher is probably too much, since anything more than 3 hits to different ports is pretty suspicious behavior 👀 Usually you can leave this at 0 without any consequence, with the exception of Advanced stealth scan detection modes where you may create a "hair trigger" if you aren't careful. Use your own discretion bestie.
• PORT_BANNER — a text banner you want displayed to the connecting host if PortSentry is activated. Leave this commented out if you don't want this feature. If you do use it, try not to taunt the person too badly 😅 It's recommended keeping it professional and to the point. The banner is *not* displayed when stealth scan detection modes are used.

---

🦋 SEE ALSO 🦋

portsentry(8), hosts_access(5), hosts_options(5), route(8), ipfwadm(8), ipchains(8)

/usr/share/doc/portsentry/README.install

---

💜 AUTHOR 💜

portsentry was written by Craig H. Howland <crowland@users.sf.net> 👑

This manual page is essentially just a "cut and paste" from the README.install file and was done by Guido Guenther <agx@debian.org> (hopefully without adding too many errors), for the Debian GNU/Linux system (but may be used by others) 🫶

---

and that's the whole page bestie!! this was PORTSENTRY.CONF(5) from the File Formats Manual — go configure responsibly, don't block innocent hosts, and remember: no cap, only packet filtering 💅✨🌈