19.4 Limit Excessive IP Address Connections Using Metermaid—Example

This example uses MeterMaid to throttle IP addresses at 10 connections/minute. For reference, the equivalent conn_throttle.so setup in the mappings file would be as follows:

PORT_ACCESS
   *|*|*|*|*  $C$|INTERNAL_IP;$3|$Y$E
   *|*|*|*|*  $C$[/opt/SUNWmsgsr/lib/conn_throttle.so,throttle,$3,10]\
$N421$ Connection$ declined$ at$ this$ time$E
   *          $YEXTERNAL

This PORT_ACCESS mapping table implements conn_throttle.so to restrict connections to a rate of no more than 10 connections per minute for non-INTERNAL connections.

One fundamental difference between the two technologies is that instead of configuring details such as the rate-limit for throttling directly into the mapping table, MeterMaid uses configutil parameters for these settings. This example is described below.

1. Designate one of your systems to be the MeterMaid server host.

   On this system, set the following configutil parameter:

   local.metermaid.enable -v TRUE

   Set an authentication password used to verify communications between the client and MeterMaid server:

   configutil -o metermaid.config.secret -v password

2. Define a throttling table.

   MeterMaid's throttling behavior is determined by the use of named throttling tables that define operating characteristics. To define a table that throttles at a rate of 10 connections per minute, set the following parameters:

   configutil -o metermaid.table.ext_throttle.data_type -v ipv4 configutil -o metermaid.table.ext_throttle.quota -v 10

   ext_throttle is the name of the throttling table. ipv4 is the data type Internet Protocol version 4 address representation. 10 is the quota (connection limit).

3. On the MeterMaid system, start MeterMaid.

   # start-msg metermaid

4. On systems where the MTA will use MeterMaid to do throttling, specify the MeterMaid host and password.

   These are required:

   configutil -o metermaid.config.secret -v MeterMaid_Password configutil -o metermaid.config.serverhost -v name_or_ipaddress_of_MetermaidHost

5. Set up the MeterMaid PORT_ACCESS table.

   This table is similar to the equivalent conn_throttle.so setup:

   PORT_ACCESS *|*|*|*|* $C$|INTERNAL_IP;$3|$Y$E *|*|*|*|* $C$:A$[/opt/SUNWmsgsr/lib/check_metermaid.so,throttle,\ ext_throttle,$3] $N421$ Connection$ declined$ at$ this$ time$E * $YEXTERNAL

   The first line checks to see if the IP address attempting a connection is internal. If it is, it allows the connection. The second line runs the IP address through MeterMaid and if it has connected too frequently, it declines the connection. The third line allows any other connections through, but flagged as EXTERNAL.

   Note that this call to check_metermaid.so is very similar to the callout to conn_throttle.so. The function in check_metermaid.so is the same. throttle and its arguments are simply the table name as configured using metermaid.table.tablename and the IP address to check ($3). Like conn_throttle.so, this function returns success when the limit (as specified in metermaid.table.ext_throttle.quota) has been reached. This allows the remainder of the mapping entry line is processed, which sends a message (421 SMTP code, transient negative completion, Connection not accepted at this time) to the remote SMTP client, and tells the Dispatcher to close the connection.

   Note also that $:A ensures that this line will only be processed when being called from the Dispatcher. Without this, the call to check_metermaid.so would also happen in the context of the tcp_smtp_server processes which also probes the PORT_ACCESS mapping table. This would cause MeterMaid to count each incoming connection twice.

This is the basic configuration to set up MeterMaid as a conn_throttle.so replacement. See 10.3.2 Mapping Operations and 18.3.4 PORT_ACCESS Mapping Table for information on these topics.

19.4.1 Additional Useful MeterMaid Options

Two additional configuration options may be useful in some circumstances. The conn_throttle.so shared library also had a throttle_p function that would penalize connections that exceeded the limit by applying a consequence for an extended period beyond the basic 60 seconds. This same behavior is available in MeterMaid by configuring the following option on the MeterMaid server system:

configutil -o metermaid.table.ext_throttle.options -v penalize

This changes the behavior for the ext_throttle table so that connections may be penalized for connection attempts greater than the value set for metermaid.table.ext_throttle.quota.

The other option is relevant for systems that receive a large number of connections. Because MeterMaid is able to keep track of connections throughout the distributed MTA environment, it's possible that the limit of the number of connections being retained in MeterMaid's internal in-memory database may be insufficient for the overall volume of the MTA environment. The default is 1000 entries per table, but if you anticipate having more than 1000 connections per minute throughout your MTA environment, you can increase this number through this configuration option:

configutil -o metermaid.table.ext_throttle.max_entries -v max_entries

Note that even if the max_entries is reached during the 60 second period, MeterMaid will automatically discard the oldest and least frequently used entries. Thus, the more frequently connecting systems will remain in MeterMaid's table to be counted, keeping enough information to provide effective throttling.