phreld.conf

Section: File Formats (5)
Updated: Sep 2011
Index Return to Main Contents

NAME

phreld.conf - Configuration for Per Host RatE Limiter Daemon

DESCRIPTION

The phreld.conf file is the configuration file for phreld(1).

The configuration file contains keywords entries, keyword and value pair entries and block entries.

Keyword entries enable a feature. Some keyword enabled features may accept an optional value.

Example of keyword entries:

  test
  promiscuous

Keyword and value pair entries are separated by one or more spaces or tabs. The value may be a quoted string.

Example of keyword and value pair entries:

  interface    eth0
  expression   "udp and port 53"

Block entries start with a keyword wrapped in angles brackets, an opening angle bracking (<) followed by a keyword and ended with a closing angle bracket (>). A block entry may contain keyword entries and keyword and value pair entries. The block entry is completed by an opening bracking and slash (</) followed by a matching keyword and ended with a closing angle bracket (>).

Example of a block entry:

  <threshold>
      pps     50
      rate    25
      burst   10
  </threshold>

Any characters following a # or ; character is considered a comment and will be ignored. Empty lines are ignored.

OPTIONS

Options can be given in any order. The available options heavily match up with command line arguments.

Preferences
interface <INTERFACE>: Monitor incoming traffic on specified INTERFACE. (Default: any)
ipv4 <on|off>: Set IPv4 to on or off. (Default: on)
ipv6 <on|off>: Set IPv6 to on or off. (Default: on)
protocol <PROTOCOL>: Monitor incoming traffic only for specified PROTOCOL. (Default: any)
port <PORT>: Monitor incoming traffic only on UDP/TCP specified PORT. (Default: any)
Block: <threshold>: Add threshold of PPS. This option may be specified multiple times to define different thresholds. If the threshold is triggered by a host, a chain will be inserted into iptables using a rate limiter of RATE PPS with a burst of BURST packets. This chain 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.
rate <PPS>: Use PPS as the default RATE. If a configured threshold does not specify RATE, this value will be used. (Default: 0)
burst <PACKETS>: Use PACKETS as the default BURST size. If a configured threshold does not specify BURST, this value will be used. (Default: 5)
decay <SECONDS>: Use SECONDS as the default DECAY. If a configured threshold does not specify DECAY, this value will be used. (Default: 900)
Block: <exclude>: 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)
Block: <include>: 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)
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)
interval <SECONDS>: Use an interval of SECONDS to calculate PPS over. Higher interval values will increase memory usage but will minimize the impact of bursts of traffic since there will be more data to average together. (Default: 30)
check-interval <SECONDS>: Use an interval of SECONDS between checking threshold crossings. Higher check interval values will increase CPU usage but will speed up detection of threshold crossings. (Default: 300)
Block: <snmptrap>: Send SNMP traps to HOST on PORT using COMMUNITY and VERSION. If INFORM enabled, any SNMP v2 trap will require an acknowledgment from the trap receiver or HOST (Default: none). PORT may be any value between 1 and 65535. (Default: 162) COMMUNITY may be any alphanumeric value. (Default: public) VERSION may be v1 or v2. (Default: v2) INFORM may be 0 or 1. (Default: 0)
test: Run in test mode. Program will function as normal except no updates to iptables will be made. (Default: off)
direction <in|out|inout>: The direction to capture packets from the interface. Available options are; in, out or inout. (Default: in)
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)
jump <CHAIN>: The DROP action of chains inserted into iptables will be replaced with CHAIN. (Default: DROP)
iptables <PATH>: Use the specified PATH to run the iptables utility. (Default: /sbin/iptables)
ip6tables <PATH>: Use the specified PATH to run the ip6tables utility. (Default: /sbin/ip6tables)
Database
Block: <database>: Configure a MySQL database to provide syncronization between instances of PHREL. This is useful for server farms behind a load balancer, or for providing a database to pull stats from.
host <HOST>: Connect to the MySQL database at HOST to provide data syncronization between instances of PHREL. (Default: none)
port <PORT>: Connect to the MySQL database on PORT to provide data syncronization between instances of PHREL. (Default: none)
sock <SOCKET>: Connect to the MySQL database on SOCKET to provide data syncronization between instances of PHREL. (Default: none)
name <DATABASE>: Use the database named DATABASE to store data. (Default: phrel)
user <USER>: Use the username USER to connect to the database (Default: phrel)
pass <PASSWORD>: Use the password PASSWORD to connect to the database (Default: none)
comp: Use compression protocol to communicate with the database. This is useful over low bandwidth links. (Default: off)
algo <avg|sum|max>: The algorithm to use to calculate a hosts Packets Per Second (PPS) for database input. Available options are; avg, sum or max. (Default: max)
threshold <PPS>: Threshold for data to be written to the database. This limits excessive inserts into the database. (Default: 2)
Process
user <USER>: Run as user USER. (Default: current)
group <GROUP>: Run as group GROUP. (Default: current)
chroot <DIR>: Change root to DIRectory. (Default: none)
stats [FILE]: Write statistics information to FILE. (Default: /var/run/phreld.stat)
dump [FILE]: Write hash dump 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)
debug [LEVEL]: Set the debug level to INT. Values of 1 to 9 are valid. (Default: off)

EXAMPLES

Listen on port 53. Enable promiscuous mode. At threshold 25 PPS, rate limit to 20 PPS, burst size of 10 and decay of 1800 seconds. At threshold 50 PPS, rate limit to 10 PPS. At threshold 75 block traffic. Send SNMP v2 traps for all alarms to 192.168.33.1 using community public. Send SNMP v1 traps for all alarms to 192.168.55.1 using community public.

  port   53
  promiscuous

  <threshold>
      pps    25
      rate   20
      burst  10
      decay  1800
  </threshold>

  <threshold>
      pps    50
      rate   10
  </threshold>

  <threshold>
      pps    75
  </threshold>

  <snmphost>
      host       192.168.33.1
      community  public
      version    v2c
  </snmphost>

  <snmphost>
      host       192.168.55.1
      community  public
      version    v1
  </snmphost>

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.

  interface  eth0
  protocol   tcp
  port       25

  <threshold>
      pps    25
      rate   20
      burst  10
      decay  300
  </threshold>

  <threshold>
      pps    50
      rate   10
      burst  5
  </threshold>

  <threshold>
      pps    75
      rate   0
  </threshold>

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.

  interface  eth0
  port       53
  burst      10
  decay      1800

  <threshold>
      pps    100
  </threshold>

  <exclude>
      prefix 192.168.33.1
      prefix 192.168.55.0/24
      prefix 2001:4870:8000::/64
  </exclude>

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..

  expression  "udp dst port 53 and not (dst net 192.168.33.1 or 192.168.55.0/24 or 2001:4870:8000::/64)"

  <threshold>
      pps    50
  </threshold>

COPYRIGHT

Copyright (C) 2005-2011 Digital Genesis Software. 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@digitalgenesis.com>

This document was created by man2html, using the manual pages.
Time: 06:48:27 GMT, September 11, 2011