phreld

NAME

SYNOPSIS

DESCRIPTION

NOTE: phreld requires nftables (the nf_tables kernel subsystem and libnftables). There is no iptables fallback.

This application can be used to protect a public server against abusive hosts and defend against brute force login attempts. It is particularly well suited to protecting nameservers (DNS) from random hosts which flood requests and preventing SSH brute force login attempts. Both IPv4 and IPv6 are supported.

NOTE: phreld will automatically ignore any traffic sourced from the local server.

The newest version of phrel is available at:

http://www.digitalgenesis.com/software/phrel/

When a configuration file is used, command-line options override values from the file. A positional expression argument, if present, supplies a tcpdump-format BPF filter. It cannot be combined with -P or -p, which build a capture filter from protocol and port settings.  

OPTIONS

Preferences

-I, --interface=INTERFACE

Monitor incoming traffic on specified interface. (Default: any)

-4, --ipv4

Enable IPv4 monitoring. When -4 is used without -6, IPv6 monitoring is disabled. (Default: on)

-6, --ipv6

Enable IPv6 monitoring. When -6 is used without -4, IPv4 monitoring is disabled. (Default: on)

-P, --protocol=PROTOCOL

Monitor incoming traffic only for specified PROTOCOL. Builds a capture filter together with -p. May not be combined with a positional BPF expression. (Default: any)

-p, --port=PORT

Monitor incoming traffic only on UDP/TCP specified PORT. Builds a capture filter together with -P. May not be combined with a positional BPF expression. (Default: any)

-T, --threshold=PPS[:RATE[:BURST[:DECAY]]]

Add threshold of PPS. This option may be specified multiple times to define different thresholds. If the threshold is triggered by a host, nftables rule(s) will be inserted using a rate limiter of RATE PPS with a burst of BURST packets. These rules will remain for at least DECAY seconds. If the offending host stays below the threshold, it will be removed or reduced to the lowest threshold it is currently violating. (Default: none)

-R, --rate=PPS

Use PPS as the default RATE. If a configured threshold does not specify RATE, this value will be used. (Default: 0)

-B, --burst=PACKETS

Use PACKETS as the default BURST size. If a configured threshold does not specify BURST, this value will be used. (Default: 5)

-D, --decay=SECONDS

Use SECONDS as the default DECAY. If a configured threshold does not specify DECAY, this value will be used. (Default: 900)

-X, --exclude=PREFIX[/CIDR]

Exclude packets from any host within the specified PREFIX range. This option may be specified multiple times to define different prefix ranges and will take precedence over included prefix ranges. The daemon will not track or take any action against hosts within the specified prefix range. Use this option to exclude source addresses that you trust, such as your mail servers or management network(s). (Default: none)

-Y, --include=PREFIX[/CIDR]

Include packets from any host within the specified PREFIX range. This option may be specified multiple times to define different prefix ranges. The daemon will track and take action against any hosts within the specified prefix range if the host has not already been excluded by a exclude prefix range. Any hosts that are not within the include prefix range(s) will be excluded. (Default: any)

-A, --algo=<avg|sum|max>

The algorithm to use to calculate a hosts Packets Per Second (PPS). Available options are; avg, sum or max. (Default: avg)

-i, --interval=SECONDS

Use an interval of SECONDS to calculate PPS over. Valid range is 1 to 900. Higher interval values increase memory usage but minimize the impact of short bursts. (Default: 30)

-c, --check-interval=SECONDS

Use an interval of SECONDS between checking threshold crossings. Valid range is 1 to 900. This interval also controls how often phreld writes local stats to Redis and reads peer stats back, when Redis sync is enabled. Lower values detect threshold crossings sooner but use more CPU. (Default: 30)

-s, --stats-interval=SECONDS

Use an interval of SECONDS between updates to the statistics file. Valid range is 1 to 3600. (Default: 300)

-t, --test

Run in test mode. Program will function as normal except no updates to nftables will be made. (Default: off)

-w, --direction=<in|out|inout>

The direction to capture packets from the interface. Available options are; in, out or inout. (Default: in)

-m, --promiscuous

Run with promiscuous mode enabled. Program will enable promiscuous mode on the network interface card (NIC) allowing packets in the same collision domain as the server to be read and processed. This will increase CPU utilization and is usually not needed. (Default: off)

-a, --action=<drop|reject|accept>

The nftables action used for offending hosts. (Default: drop)

--nft-priority=NUM

The priority at which phreld's nftables hook chain is evaluated within the netfilter input hook, relative to the default filter chain (priority 0). Valid range is -300 to 300. Lower values are evaluated earlier. (Default: -10)

Redis

The following options are available only when phreld is built with Redis support (configure--enable-redis).

-H, --redis-host=HOST[:PORT]

Connect to Redis at HOST and PORT to provide data synchronization between instances of PHREL. If PORT is omitted from HOST:PORT, 6379 is used. (Default: none)

--redis-port=PORT

Connect to Redis on PORT. Ignored if --redis-sock is set. (Default: 6379)

-K, --redis-sock=SOCKET

Connect to Redis on SOCKET to provide data synchronization between instances of PHREL. Takes precedence over --redis-host/--redis-port. (Default: none)

-U, --redis-user=USER

Use the username USER to connect to Redis. Requires Redis 6+ ACL support and --redis-pass to also be set. (Default: none, anonymous)

-W, --redis-pass=PASSWORD

Use the password PASSWORD to connect to Redis. (Default: none, anonymous)

--instance-id=ID

Use ID as this phreld's unique instance identifier when syncing via Redis. If unset, the ID is read from --instance-file, or auto-assigned via a Redis counter and saved there. (Default: none, auto-assign)

--instance-file=PATH

File used to persist an auto-assigned instance id across restarts. Only written when the instance id is auto-assigned. (Default: ~/phreld.id)

-G, --sync-algo=<avg|sum|max|combined>

The algorithm to use to merge a hosts Packets Per Second (PPS) with data received from peer instances via Redis. Available options are; avg, sum, max or combined. (Default: combined)

-L, --sync-threshold=PPS

Threshold for data to be written to Redis. This limits excessive writes to Redis. (Default: 2)

Process

-C, --config=FILE

Use configuration options specified within FILE. Command line options will override options specified within the configuration file. When invoked with no other options, phreld reads ${prefix}/etc/phrel/phreld.conf by default. When other command-line options or a BPF expression are given, a configuration file is not required unless -C is specified.

-u, --user=USER

Run as user USER. (Default: current)

-g, --group=GROUP

Run as group GROUP. (Default: current, or USER's primary group when --user is set)

-r, --chroot=DIR

Change root to DIRectory. (Default: none)

-o, --stats[=FILE]

Write statistics information to FILE. (Default: /var/run/phreld.stat)

-n, --nice=[+/-]NUM

Run with a nice value of NUM. Values of -20 to 19 are valid. (Default: +5)

-d, --debug[=LEVEL]

Set the debug level. Values of 1 to 9 are valid. A value of 1 or greater prevents forking to the background unless -b or --background is also given. If LEVEL is omitted, 1 is used. (Default: off)

-b, --background

Fork to the background even when debug is enabled. (Default: off)

General

-h, --help

Display the help/usage information.

-v, --version

Display the version information.

FILES

${prefix}/etc/phrel/phreld.conf

The configuration file.

EXAMPLES

phreld -p 53 -T 50:5 -T 75

Listen on interface eth0 for TCP traffic on port 25 (SMTP). At threshold 25, rate limit to 20 PPS with a burst size of 10 using a decay of 300 seconds. At threshold 50, rate limit to 10 PPS with a burst size of 5. At threshold 75 PPS, block traffic.

phreld -I eth0 -P tcp -p 25 -T 25:20:10:300 -T 50:10:5 -T 75:0

Listen on interface eth0 on port 53. At threshold 100 PPS, block traffic. Use default burst size of 10 and a decay of 1800 seconds for all thresholds. Exclude host 192.168.33.1, prefix range 192.168.55.0/24 (/24 is 255.255.255.0 in mask notation) and IPv6 prefix range 2001:4870:8000::/64.

phreld -I eth0 -p 53 -T 100 -B 10 -D 1800 -X 192.168.33.1 -X 192.168.55.0/24 -X 2001:4870:8000::/64

At threshold 50 PPS, block traffic. Listen to UDP traffic on port 53 except for host 192.168.33.1, prefix range 192.168.55.0/24 (/24 is 255.255.255.0 in mask notation) and IPv6 prefix range 2001:4870:8000::/64.

phreld -T 50 'udp dst port 53 and not (dst net 192.168.33.1 or 192.168.55.0/24 or 2001:4870:8000::/64)'  

SEE ALSO

COPYRIGHT

Copyright (C) 2004-2026 Digital Genesis, LLC. All rights reserved.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License <http://www.gnu.org/copyleft/gpl.html>
for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

AUTHOR

James M. Sella <sella@digital-genesis.com>

HISTORY

07/05/26 - Released version 2.1.0
07/05/26 - Released version 2.0.0
07/03/26 - Released version 1.1.0
04/20/13 - Released version 1.0.1
09/09/11 - Released version 1.0.0
01/25/09 - Released version 0.9.8
07/21/08 - Released version 0.9.7
10/26/06 - Released version 0.9.6
04/15/06 - Released version 0.9.5
03/26/06 - Released version 0.9.4
03/22/06 - Released version 0.9.3
03/06/06 - Released version 0.9.2
03/05/06 - Released version 0.9.1
03/02/06 - Released version 0.9.0

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

FILES

EXAMPLES

SEE ALSO

COPYRIGHT

AUTHOR

HISTORY