phreld.conf

NAME

DESCRIPTION

Comments are introduced by #, //, --, or /**/. The preprocessor directives #include, #if, and #endif are supported.

Example:

options {
    debug 2;
    traceoptions [ configuration ];
    user nobody;
    group nobody;
    chroot /var/phreld;
    stats /var/run/phreld.stat;
    nice 5;
}

phrel {
    protocol icmp;
    threshold pps 10 rate 10;
    include [ 192.168.33.128/28 ];
    redis {
        server host 127.0.0.1 port 6379 username "phrel" passname "secret";
        #server socket /var/run/redis/redis.sock;
        instance-file ~/phreld.id;
        #instance-id 1;
        algo combined;
        threshold 2;
    }
}

OPTIONS BLOCK

debug LEVEL;

debug LEVEL background; debug background; Set the debug level. Values of 1 to 9 are valid. A value of 1 or greater prevents forking to the background unless background is also specified. A bare debug background statement sets the debug level to 1 and forces a background fork. (Default: off)

traceoptions [NAME ...];

Enable tracing for the named categories. The special name configuration causes the parsed configuration to be logged after startup. The name all enables every trace category. When debug is 2 or greater, the configuration trace is enabled automatically. A single category may also be given without brackets.

user USER;

Run as user USER. (Default: current)

group GROUP;

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

chroot DIR;

Change root to DIR. (Default: none)

stats [FILE];

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

nice NUM;

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

PHREL BLOCK

interface INTERFACE;

Monitor incoming traffic on INTERFACE. (Default: any)

ipv4 on|off|enable|disable;

Set IPv4 processing on or off. (Default: on)

ipv6 on|off|enable|disable;

Set IPv6 processing on or off. (Default: on)

protocol PROTOCOL;

Monitor traffic for PROTOCOL. May be combined with port to build a capture expression. Mutually exclusive with expression. (Default: any)

port PORT;

Monitor UDP/TCP traffic on PORT. Valid range is 1 to 65535. May be combined with protocol to build a capture expression. Mutually exclusive with expression. (Default: any)

expression EXPR;

Use a tcpdump-format capture expression. Mutually exclusive with protocol and port.

rate PPS;

Default rate limit for thresholds that do not specify a rate. (Default: 0)

burst PACKETS;

Default burst size. (Default: 5)

decay SECONDS;

Default decay time. (Default: 900)

threshold pps N [rate N] [burst N] [decay N];

Add a threshold of N packets per second. This statement may be repeated. When a host crosses the threshold, nftables rules are inserted using the configured rate, burst, and decay values.

exclude [CIDR ...];

exclude CIDR; Exclude traffic from the given prefix. Statements are additive. Takes precedence over include ranges.

include [CIDR ...];

include CIDR; Include only traffic from the given prefix. Statements are additive. A bare IPv4 address implies /32.

algo avg|sum|max;

Algorithm used to calculate host PPS. (Default: avg)

interval SECONDS;

Interval over which PPS is calculated. Valid range is 1 to 900. (Default: 30)

check-interval SECONDS;

Interval between threshold checks and Redis sync updates. Valid range is 1 to 900. (Default: 30)

stats-interval SECONDS;

Interval between statistics file updates. Valid range is 1 to 3600. (Default: 300)

test;

Run in test mode without updating nftables.

direction in|out|inout;

Packet capture direction. (Default: in)

promiscuous;

promiscuous enable; promiscuous disable; Control promiscuous mode on the capture interface. A bare promiscuous statement is equivalent to promiscuousenable. (Default: off)

action drop;

action reject; action accept; nftables action for offending hosts. (Default: drop)

nft-priority NUM;

Priority of phreld's nftables hook chain. Valid range is -300 to 300. (Default: -10)

redis { ... };

Configure Redis cross-instance synchronization. If Redis is unreachable at startup, phreld logs a warning and continues as a single-instance rate limiter. Redis support must be compiled into phreld.

server OPTIONS;

Connection parameters for Redis. Options may appear in any order on a single server statement:

host HOST;

Redis hostname or address.

port PORT;

Redis TCP port. Valid range is 1 to 65535. (Default: 6379)

socket PATH;

Unix domain socket path. Takes precedence over host and port.

username USER;

ACL username for Redis 6 and later.

passname PASS;

Password for Redis authentication.

instance-id ID;

Unique instance identifier. When unset, the ID is read from instance-file or auto-assigned via Redis.

instance-file PATH;

File used to persist an auto-assigned instance id. (Default: ~/phreld.id)

algo avg|sum|max|combined;

Algorithm used to merge local and peer PPS data. (Default: combined)

threshold PPS;

Minimum PPS before writing stats to Redis. (Default: 2)

disable;

disabled; Disable Redis cross-instance synchronization for this phrel block. When set, phreld does not connect to Redis or perform any Redis operations, even if server connection parameters are also present.

FILES

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

Default configuration file.

~/phreld.id

Default instance id persistence file when instance-file is not set.

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>

Index

NAME

DESCRIPTION

OPTIONS BLOCK

PHREL BLOCK

FILES

SEE ALSO

COPYRIGHT

AUTHOR