19.3 Configutil Parameters for MeterMaid

MeterMaid's configuration is stored in msg.conf and is maintained by configutil. Here are some of the settings currently supported by MeterMaid. Defaults are in parenthesis. See configutil Parameters in Sun Java System Messaging Server 6.3 Administration Reference for complete list of MeterMaid parameters.

Chapter 19, Throttling Incoming Connections Using MeterMaid

• local.metermaid.enable This setting must be set to yes on the system that will run the MeterMaid daemon so that the Watcher will start and control MeterMaid.

• logfile.metermaid.* These settings are the same as those used by imap, pop, and other services. By default MeterMaid writes its log file into msg-svr-base/data/log/metermaid

• metermaid.config.listenaddr (INADDR_ANY) 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.

• metermaid.config.maxthreads (20) 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.

• metermaid.config.port (63837) This is the port to which MeterMaid listens for connections and to which MeterMaid clients will connect.

• metermaid.config.secret (No default; value must be supplied) In order to authenticate incoming connections, MeterMaid uses a shared secret that the clients send once they connect to MeterMaid.

• metermaid.config.serverhost (No default; value must be supplied) This is the host name or IP address to which the clients will connect. It may be the same as metermaid.config.listenaddr but will most likely have a particular value to direct clients to one system in particular in the Messaging Server environment.

These settings are used by the check_metermaid client:

• metermaid.mtaclient.connectfrequency (15) 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.mtaclient.connectfrequency, no additional attempts will be attempted. It prevents check_metermaid.so from trying to connect to MeterMaid too frequently if it is not working.

• metermaid.mtaclient.connectwait (5) 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 connectwait seconds before returning a fail status and allowing this connection to continue.

• metermaid.mtaclient.debug (no) 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.

• metermaid.mtaclient.maxconns (3) 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.

• metermaid.mtaclient.readwait (10) When communicating with MeterMaid, the client will wait readwait seconds before returning a fail status and allowing this connection to continue.

Lastly, the throttling tables are also defined in msg.conf as shown here. The * in each configuration parameter is the name of the particular table being defined. For example, for a table called internal, the first parameter would be called metermaid.table.internal.data_type.

• metermaid.table.*.data_type (string) 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.table.*.options below).

• metermaid.table.*.max_entries (1000) 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.

• metermaid.table.*.options 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.table.*.quota (100) 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.)

• metermaid.table.*.quota_time (60) 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.

• metermaid.table.*storage (hash) 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.

• metermaid.table.*.type (throttle) Currently, the only table type supported by MeterMaid is throttle. 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.

Metermaid was coded to be as efficient as possible, but may not match your expectations as it uses weighted averages to limit the connection rate rather than maintaining a list of just how many connections there have been over the previous quota_time period.

For example, let's say you are trying to limit connections to 1250 mails per hour (metermaid.table.tcp_auth_msg_throttle.quota = 1250). This limits connections to an average rate of 1250/hour. In other words, if all 1250 connections are used up in the first second, then half an hour later, an additional 625 are provided. After another 15 minutes, you'd get another 362, and so on.

A common misconception is that one hour after the initial connection attempt, all will be forgiven. But Metermaid looks at an average connection rate rather than a specific count. The net effect is the same in the long run (over a 24 hour period, a total of 1250 * 24 would be allowed), but it's not mathematically precise in a short period.

A future goals for Metermaid is that instead of offering an average throughput rate, it would maintain a distinct list of connection attempts, and be able to expire each attempt after the precise time. This has not yet been done because it's a much more computationally expensive operation to maintain than computing an average rate.