14 Using and Configuring MeterMaid for Access Control

MeterMaid is a server that can provide centralized metering and management of connections and transactions through monitoring IP addresses and SMTP envelope addresses. Functionally, MeterMaid can be used to limit how often a particular IP address can connect to the MTA. Limiting connections by particular IP addresses is useful for preventing excessive connections used in denial-of-service attacks. MeterMaid supplants conn_throttle.so by providing similar functionality, but extending it across the Oracle Communications Messaging Server installation. No new enhancements are planned for conn_throttle.so and MeterMaid is its more effective replacement.

Technical Overview

conn_throttle.so is a shared library used as a callout from the MTA's mapping table that uses an in-memory table of incoming connections to determine when a particular IP address has recently connected too often and should be turned away for awhile. While having an in-memory table is good for performance, its largest cost is that each individual process on each server maintains its own table.

In most cases, the conn_throttle.so callout is done in the PORT_ACCESS mapping that is accessed by the Dispatcher, a single process on each system. The only cost is that there is a separate table per server.

The primary improvement by MeterMaid is that it maintains a single repository of the throttling information that can be accessed by all systems and processes within the Messaging Server environment. It continues to maintain an in-memory database to store this data to maximize performance. Restarting MeterMaid will lose all information previously stored, but since the data is typically very short lived, the cost of such a restart (done infrequently) is very low.

Theory of Operations

MeterMaid's configuration is maintained by the msconfig command in Unified Configuration or the configutil command in legacy configuration.

MeterMaid is accessed from the MTA through a mapping table callout using check_metermaid.so. It can be called from any of the *_ACCESS tables. When called from the PORT_ACCESS table, it can be used to check limits based on the IP address of the connection which will be the most common way to implement MeterMaid as a replacement for the older conn_throttle.so. If called from other *_ACCESS tables, MeterMaid can also be used to establish limits on other data such as the envelope from or envelope to addresses as well as IP addresses.

This chapter only describes the throttle entry point in check_metermaid.so. For a complete list of check_metermaid.so entry points, refer to "MeterMaid Reference." The throttle routine contacts MeterMaid providing two subsequent arguments separated by commas. The first is the name of the table against which the data will be checked, and the second is the data to be checked.

If the result from the probe is that the particular data being checked has exceeded its quota in that table, check_metermaid.so returns success so that the mapping engine will continue processing this entry. The remainder of the entry would then be used to handle this connection that has exceeded its quota.

PORT_ACCESS

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

Note the $:A flag test in the mapping table entry before the call to check_metermaid.so. This is to ensure that we only do the MeterMaid probe when PORT_ACCESS is being checked by the dispatcher as it will set the A flag for its probe.

Options for MeterMaid

MeterMaid's configuration is maintained by setting options using the msconfig command in Unified Configuration or using the configutil command in legacy configuration. Table 14-1 describes some of the settings currently supported by MeterMaid.

Table 14-1 Options for MeterMaid

Unified Configuration Option	Legacy Configuration Option	Description
metermaid.enable	local.metermaid.enable	This setting must be set to 1 on the system that will run the MeterMaid daemon so that the Watcher will start and control MeterMaid.
metermaid.logfile.*	logfile.metermaid.*	These settings are the same as those used by imap, pop, and other services. By default MeterMaid writes its log file into MessagingServer_home/data/log/metermaid.
metermaid.listenaddr	metermaid.config.listenaddr	The address to which MeterMaid should bind. On most systems, the default would not need to be changed, but for multi-homed or HA systems, specifying the appropriate address here is recommended.Default: (INADDR_ANY)
metermaid.maxthreads	metermaid.config.maxthreads	The MeterMaid server is multithreaded and maintains a pool of threads onto which its tasks are scheduled. This value sets the maximum number of threads that will be used by MeterMaid. On systems with more than 4 CPUs, increasing this value may increase overall throughput.Default: 20
metermaid.port	metermaid.config.port	This is the port to which MeterMaid listens for connections and to which MeterMaid clients will connect. Default: 63837
metermaid.secret	metermaid.config.secret	In order to authenticate incoming connections, MeterMaid uses a shared secret that the clients send once they connect to MeterMaid.No default. Value must be supplied.
metermaid.sslusessl	service.metermaid.sslusessl	Requires the use of SSL for all incoming connections to the MeterMaid server.Default: 0

Table 14-2 describes the options used by the check_metermaid client:

Table 14-2 check_metermaid Options

Unified Configuration Option	Legacy Configuration Option	Description
metermaid_client.connectfrequency	metermaid.mtaclient.connectfrequency	Attempt a connection every connectfrequency seconds. When the client needs to connect to MeterMaid, it uses this as an internal throttle to prevent constant connection attempts when MeterMaid isn't available. During the time that the client is unable to communicate with MeterMaid, it will return a "fail" status to the MTA mapping engine indicating that MeterMaid has not blocked this connection. For example, if check_metermaid.so attempts to connect to MeterMaid, but it fails for some reason, during the next N seconds as specified by metermaid_client.connectfrequency (or metermaid.mtaclient.connectfrequency in legacy configuration), no additional attempts will be attempted. It prevents check_metermaid.so from trying to connect to MeterMaid too frequently if it is not working. Default: 15
metermaid_client.connecttimeout	metermaid.mtaclient.connectwait	When the client is waiting for a connection to MeterMaid (either an initial connection or to reuse another already established connection), it will wait for connecttimeout seconds before returning a fail status and allowing this connection to continue.Default: 5
metermaid_client.debug	metermaid.mtaclient.debug	If this option is enabled, debugging information from the client will be printed into either the server or thread-specific log file for the SMTP server. Default: no
metermaid_client.max_conns	metermaid.mtaclient.maxconns	In order to support multithreaded servers, the client can maintain a pool of connections to MeterMaid. By doing this, there can be increased concurrency during communications. However, due to internal locking done by MeterMaid, access to a particular table is limited to one request at a time, so multiple connections from a single process may provide limited benefit.Default: 3
metermaid_client.timeout	metermaid.mtaclient.readwait	When communicating with MeterMaid, the client will wait timeout seconds before returning a fail status and allowing this connection to continue.Default: 10
metermaid_client.server_host	metermaid.config.serverhost	This is the host name or IP address to which the clients will connect. It may be the same as metermaid.listenaddr but will most likely have a particular value to direct clients to one system in particular in the Messaging Server environment. No default. Value must be supplied.
metermaid_client.sslusessl	metermaid.mtaclient.sslusessl	Enables SSL communication with an SSL-enabled MeterMaid server.Default: 0

Lastly, the throttling tables are also defined in Unified and legacy configurations. Table 14-3 describes the options defining the throttling tables. The * in each configuration option is the name of the particular table being defined. For example, for a table called internal, the first option would be called metermaid.local_table:internal.data_type in Unified Configuration or metermaid.table.internal.data_type in legacy configuration.

Table 14-3 Options Defining Throttling Tables

Unified Configuration Option	Legacy Configuration Option	Valid for Table Types	Description
metermaid.local_table:*.data_type	metermaid.table.*.data_type	throttle simple greylisting	MeterMaid can support two kinds of data in its tables, string and ipv4. String data is limited to 255 bytes per entry and can be compared using case-sensitive or case-insensitive functions (see metermaid.local_table:*.options below).Default: string
metermaid.local_table:*.max_entries	metermaid.table.*.max_entries	throttle simple greylisting	When MeterMaid initializes each table, it pre-allocates this many entries. MeterMaid automatically recycles old entries, even if they haven't yet expired. When a new connection is received, MeterMaid will reuse the least recently accessed entry. A site should specify a value high enough to cache the connections received during quota_time.Default: 1000
metermaid.local_table:*.options	metermaid.table.*.options	throttle	This option is a comma-separated list of keywords that defines behavior or characteristics for the table. Valid keywords are: nocase - When working with the data, all comparisons are done using a case-insensitive comparison function. (This option is valid only for string data). penalize - After quota_time seconds, throttle will normally reset the connection count to 0, but if the penalize option is enabled, throttle will decrement the connection count by quota (but not less than 0) so that additional connection attempts will penalize future quota_time periods. For example, if quota were 5 with a quota_time of 60, and the system received 12 connection attempts during the first minute, the first 5 connections would be accepted and the remaining 7 would be declined. After 60 seconds has passed, the number of connections counted against the particular address would be reduced to 7, still keeping it above quota and declining connection attempts. Assuming no additional connection attempts were made, after another 60 second period, the number of connections would be further reduced down to 2, and MeterMaid would permit connection attempts again.
metermaid.local_table:*.quota	metermaid.table.*.quota	throttle	When a connection is received, it is counted against quota. If the number of connections received in quota_time seconds exceeds this value, MeterMaid will decline the connection. (The actual effect on the incoming connection is controlled by the mapping table and could result in additional scrutiny, a delay, or denying the connection.) Default: 100
metermaid.local_table:*.quota_time	metermaid.table.*.quota_time	throttle	This specifies the number of seconds during which connections will be counted against quota. After this many seconds, the number of connections counted against the incoming address will be reduced depending on the type of this table. Default: 60
metermaid.local_table:*.storage	metermaid.table.*.storage	throttle simple greylisting	MeterMaid can use two different storage methods, hash and splay. The default hash table method is recommended, but under some circumstances a splay tree may provide faster lookups.Default: hash
metermaid.local_table:*.table_type	metermaid.table.*.type	NA	MeterMaid supports three table types: throttle (default) - This type of table keeps track of the data, typically IP addresses, and will throttle the incoming connections to quota connections during a period of quota_time seconds. simple - This type of table may be used to store arbitrary data referenced by a key. greylisting - This type of table may be used to provide an anti-spam/anti-virus technique. More information about setting up this type of table can be found in the "Implementing Greylisting by Using MeterMaid" chapter.
metermaid.local_table:*.block_time	metermaid.table.*.block_time	greylisting	Specifies the ISO 8601 duration for how long we temporarily reject each delivery attempt based on sender and recipient information. Default: pt5m (5 minutes)
metermaid.local_table:*.resubmit_time	metermaid.table.*.resubmit_time	greylisting	Specifies the ISO 8601 duration during which, but after block_time, we must receive a subsequent delivery attempt based on the same sender and recipient information previously blocked. This sender and recipient combination is now flagged as permitted. Default: pt4h (4 hours)
metermaid.local_table:*.inactivity_time	metermaid.table.*.inactivity_time	greylisting	Specifies the ISO 8601 duration for how long we will continue to accept messages based on the sender and recipient information previously permitted. This permission expires after inactivity_time from the last allowed delivery. Default: p7d (7 days)

Table 14-4 describes the options used to enable access to multiple MeterMaid Servers from check_metermaid.so.

Table 14-4 Options Used to Enable Access to Multiple MeterMaid Servers from check_metermaid.so

Unified Configuration	Legacy Configuration	Description
metermaid_client.remote_table:table.server_nickname	metermaid.mtaclient.remote_table.table.server_nickname	Specifies the nickname for a particular MeterMaid server that is responsible for the referenced table. The nickname is a short keyword, consisting only of letters, numbers, and underscores, that will be used in the remote_server option names. No default. Value must be supplied.
metermaid_client.remote_server:nickname.max_conns	metermaid.mtaclient.remote_server.nickname.max_conns	Specifies the maximum number of concurrent connections to the MeterMaid server referenced by nickname. Default: 3
metermaid_client.remote_server:nickname.server_host	metermaid.mtaclient.remote_server.nickname.server_host	Specifies the host name of the MeterMaid server referenced by nickname. Defaults to the value of metermaid_client.server_host.
metermaid_client.remote_server:nickname.server_port	metermaid.mtaclient.remote_server.nickname.server_port	Specifies the port number of the MeterMaid server referenced by nickname.Default: 63837
metermaid_client.remote_server:nickname.sslusessl	metermaid.mtaclient.remote_server.nickname.sslusessl	Specifies whether or not to use SSL for the connection to the MeterMaid server referenced by nickname. Defaults to the value of metermaid_client.sslusessl.

Limit Excessive IP Address Connections Using Metermaid – Example

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

PORT_ACCESS

   *|*|*|*|* $C$|INTERNAL_IP;$3|$Y$E
   *|*|*|*|* $C$[/opt/sun/comms/messaging/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 msconfig for these settings, as the following example shows.

On systems running the MeterMaid server:

Enable MeterMaid by running the following command:

msconfig set metermaid.enable 1

or in legacy configuration:

configutil -o local.metermaid.enable -v TRUE

Set an authentication password used to verify communications between the client and MeterMaid server:
```
msconfig set metermaid.secret password
```
or in legacy configuration:
```
configutil -o metermaid.config.secret -v password
```
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 options in msconfig:
```
set metermaid.local_table:ext_throttle.data_type ipv4set metermaid.local_table:ext_throttle.quota 10
```
or the following for legacy configuration using configutil:
```
configutil -o metermaid.table.ext_throttle.data_type -v ipv4configutil -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).
On the MeterMaid system, start MeterMaid.
```
start-msg metermaid
```

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

These are required:

msconfig set metermaid.secret MeterMaid_Password
msconfig set metermaid_client.server_host name_or_ipaddress_of_MetermaidHost

or the following for legacy configuration:

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

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/sun/comms/messaging/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.

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.local_table:tablename and the IP address to check ($3). Like conn_throttle.so, this function returns success when the limit (as specified in metermaid.local_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.

$: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. Fore more information, see the discussion on mapping operations in the Messaging Server Reference, as well as "PORT_ACCESS Mapping Table" for information on these topics.

Configuring check_metermaid.so Clients to Access Multiple MeterMaid Servers

The topics in this section include:

Considerations for Distributing Load Across Multiple MeterMaid Servers
Configuring check_metermaid.so to Access Multiple MeterMaid Servers

Considerations for Distributing Load Across Multiple MeterMaid Servers

If you have multiple MeterMaid tables in your deployment, you may be able to improve overall performance by distributing them across multiple MeterMaid servers. The check_metermaid.so client supports associations between MeterMaid tables and the servers that are responsible for their respective tables. The client also supports per server options for concurrency and use of SSL.

Configuring check_metermaid.so to Access Multiple MeterMaid Servers

To configure check_metermaid.so to access multiple MeterMaid Servers:

Define the list of all tables and associate them with nicknames for each server using msconfig (Unified Configuration):
```
set metermaid_client.remote_table:table1.server_nickname "alpha"
set metermaid_client.remote_table:table2.server_nickname "alpha"
set metermaid_client.remote_table:table3.server_nickname "beta"
```
or using configutil (legacy configuration):
```
configutil -o metermaid.mtaclient.remote_table.table1.server_nickname -v "alpha"
configutil -o metermaid.mtaclient.remote_table.table2.server_nickname -v "alpha"
configutil -o metermaid.mtaclient.remote_table.table3.server_nickname -v "beta"
```
where table1, table2, and table3 are tables defined in your deployment's MeterMaid configuration. The servers' nicknames allow the check_metermaid.so client to look for remote servers associated with those nicknames. Since nicknames become part of the configuration option names for the remote server definitions, they must include only letters, numbers, and underscores.

Create configuration entries for each server nickname for the host name and port for the server, the maximum number of connections, and whether it uses SSL. Run the following commands if you are using msconfig (Unified Configuration):

set metermaid_client.remote_server:alpha.max_conns 3
set metermaid_client.remote_server:alpha.server_host "alpha.example.com"
set metermaid_client.remote_server:alpha.server_port 63837
set metermaid_client.remote_server:alpha.sslusessl 0
set metermaid_client.remote_server:beta.max_conns 3
set metermaid_client.remote_server:beta.server_host "beta.example.com"
set metermaid_client.remote_server:beta.server_port 63837
set metermaid_client.remote_server:beta.sslusessl 0

Or run the following commands if you are using configutil (legacy configuration):

configutil -o metermaid.mtaclient.remote_server.alpha.max_conns -v 3
configutil -o metermaid.mtaclient.remote_server.alpha.server_host -v "alpha.example.com"
configutil -o metermaid.mtaclient.remote_server.alpha.server_port -v 63837
configutil -o metermaid.mtaclient.remote_server.alpha.sslusessl -v 0
configutil -o metermaid.mtaclient.remote_server.beta.max_conns -v 3
configutil -o metermaid.mtaclient.remote_server.beta.server_host -v "beta.example.com"
configutil -o metermaid.mtaclient.remote_server.beta.server_port -v 63837
configutil -o metermaid.mtaclient.remote_server.beta.sslusessl -v 0

For descriptions of these options, please see "MeterMaid Reference."

If you are using Unified Configuration and your configuration is compiled, recompile your configuration. This step is not necessary if you are using legacy configuration:
```
imsimta cnbuild
```
Restart components that are using check_metermaid.so. You would typically do this by restarting the dispatcher:
```
stop-msg dispatcherstart-msg dispatcher
```