This document contains MeterMaid reference information and contains the following sections:
For MeterMaid-specific configutil options, you can search for options containing metermaid in the Messaging Server Reference.
There are two possible table types allowed by the metermaid.table.*.type options:
Greylisting tables may be used to provide an anti-spam/anti-virus technique. More information about setting up these tables can be found at the "Implementing Greylisting by Using MeterMaid" page.
A simple table may be used to store arbitrary data referenced by a key. The key data type is defined by metermaid.table.tablename.data_type, and the value data type is defined by metermaid.table.tablename.value_type. Some operations are only available to those simple tables where the value data type is integer.
Throttle tables are used to specify a particular "hit count" quota over quota_time seconds to limit connections, transactions, or certain other components of incoming connections. MeterMaid automatically maintains the count over time, decrementing it back down after quota_time has passed.
The check_metermaid.so shared library is traditionally used to throttle incoming connections in a mapping table such as PORT_ACCESS or MAIL_ACCESS. We now use a set of new routines to use data stored in simple tables (please refer to the msconfig metermaid.table:*_type option, or the configutil metermaid.table.*_type option). These routines now permit one to store, retrieve, and test arbitrary data stored in MeterMaid's ephemeral data store. Oracle Communications Messaging Server also uses the greylisting routine that works with greylisting tables.
Table 16-1 shows the routines available in check_metermaid.so, which of the two table types, simple and/or throttle, are supported for those routines, and a brief description of each one. Below that, detailed information about each routine is provided.
Note:
If any error should occur during processing such as a failure to communicate with MeterMaid, or if invalid options are provided to these routines, the routines will simply return FALSE and the shared library callout will fail.Table 16-1 check_metermaid.so Available Routines
| Routine | Description |
|---|---|
|
adjust |
Adds to or subtracts from an integer value in a table |
|
adjust_and_test |
Performs an adjust and then returns the result of a test operation |
|
fetch |
Returns a value from the table |
|
greylisting |
Returns TRUE if we are temporarily rejecting this transaction |
|
remove |
Removes an entry from a table |
|
store |
Stores a value into the table |
|
test |
Tests an integer value with a simple comparison, returning TRUE or FALSE |
|
throttle |
Increments a "hit count" and returns TRUE if quota_count is exceeded |
The following sections provide a description of each routine, a table showing the options used by the routine, the value returned, if any, to the calling environment, and sample usage.
This section describes the adjust routine.
Description
The adjust routine allows you to make a numeric adjustment to an integer value in a simple table.
Table 16-2 adjust Routine Options
| Option | Description |
|---|---|
|
table |
Table in which key is found. |
|
key |
Key corresponding to the value being adjusted. |
|
adjustment |
Positive or negative value to be added to the value. |
adjust Routine Return Value
Returns TRUE with the new value for key after the adjustment has been made as the resultant string.
adjust works by taking the current integer value for key in the table called table and adding adjustment to it, then storing the resulting value back. adjustment can be negative, thus reducing the value which can be negative.
If key doesn't exist in table, it will be presumed to have an initial value of 0 and key will be stored into table with a new value of adjustment.
Table 16-3 adjust Routine Supported Table and Value Types
| Table | Value | Supported? |
|---|---|---|
|
greylisting |
- |
- |
|
simple |
integer |
X |
|
simple |
string |
- |
|
throttle |
- |
- |
Example
The following example shows that the current value for fred@example.org will be increased by 35 after the adjust is completed. If fred@example.org did not exist in the scores table, it would be stored with a value of 35.
$[/opt/sun/comms/messaging/lib/check_metermaid.so,adjust,scores,fred@example.org,+35]
This section describes the adjust_and_test routine.
Description
The adjust_and_test routine allows you to make a numeric adjustment to an integer value in a simple table, and then test that value against a provided comparator.
Table 16-4 adjust_and_test Routine Options
| Option | Description |
|---|---|
|
table |
Table in which key is found |
|
key |
Key corresponding to the value being adjusted |
|
adjustment |
Positive or negative value to be added to the value |
|
comparator |
Comparison symbol(s) '<', '>', and/or '=', followed by a numeric value |
adjust_and_test Routine Return Value
Returns TRUE if the comparison is true, and FALSE otherwise; no resultant string is returned.
adjust_and_test first takes the current integer value for key in the table called table and adding adjustment to it, storing the resulting value back. The routine then compares the resulting value against the comparator, returning the result.
If key doesn't exist in table, it will be presumed to have an initial value of 0 and key will be stored into table with a new value of adjustment, and the comparison will be made against adjustment.
Table 16-5 adjust_and_test Routine Supported Table and Value Types
| Table | Value | Supported? |
|---|---|---|
|
greylisting |
- |
- |
|
simple |
integer |
X |
|
simple |
string |
- |
|
throttle |
- |
- |
Example
The following example shows that the current value for fred@example.org will be decreased by 2 after the adjust is completed. If fred@example.org did not exist in the scores table, it would be stored with a value of -2. Then this new value is checked to see if it is greater than or equal to 20, returning TRUE if it is.
$[/opt/sun/comms/messaging/lib/check_metermaid.so,adjust_and_test,scores,fred@example.org,-2,>=20]
This section describes the fetch routine.
Description
The fetch routine retrieves a value from a simple table.
Table 16-6 fetch Routine Options
| Option | Description |
|---|---|
|
table |
Table in which key is found |
|
key |
Key corresponding to the value being returned |
fetch Routine Return Value
Returns TRUE if key exists and returns its value as the resultant string, otherwise returns FALSE.
fetch retrieves the value associated with key in table and returns it as the resultant string. If key does not exist in table, then FALSE is returned and no resultant string is available.
Table 16-7 fetch Routine Supported Table and Value Types
| Table | Value | Supported? |
|---|---|---|
|
greylisting |
- |
X |
|
simple |
integer |
X |
|
simple |
string |
X |
|
throttle |
- |
- |
Example
The following example retrieves the current score for fred@example.org which can then use that information for subsequent processing, such as in a mapping table.
$[/opt/sun/comms/messaging/lib/check_metermaid.so,fetch,scores,fred@example.org]
The greylisting routine is used to validate entries in the table based on time and resubmission attempts. This is used as part of a Greylisting setup (see "Implementing Greylisting by Using MeterMaid" for details).
Table 16-8 greylisting Routine Options
| Option | Description |
|---|---|
|
table |
Table in which key is checked/stored |
|
key |
Key corresponding to the value being tested for greylisting. |
greylisting Routine Return Value
Returns TRUE if this probe should cause a temporary rejection for the submission attempt, otherwise returns FALSE to permit the attempt.
greylisting first probes table for key to see whether this entry has been previously permitted. If it is found to be allowed, FALSE is returned to permit the submission. Then it checks to see whether key exists and is in its resubmission period (specified by the resubmit_time table option). If so, key is marked as valid and is permitted (returning FALSE). If key exists, but is in the block_time period, the submission is refused as validation occurs after block_time has passed, and greylisting returns TRUE to return a temporary rejection for the attempt. Lastly, if key does not exist, it is stored into table and greylisting returns TRUE to return a temporary rejection for this new attempt.
Example
This example shows a greylisting probe for mail from barney@example.com going to local user fred@example.org. If this returns TRUE, then the mapping code should return a temporary rejection so that the message submission should be reattempted later.
$[IMTA_LIB:check_metermaid.so,greylisting,greylist_table,192.168.10.34|barney@example.com|fred@example.org]
This section describes the remove routine.
Description
The remove routine removes an entry from table.
Table 16-9 remove Routine Options
| Option | Description |
|---|---|
|
table |
Table in which key is found. |
|
key |
Key corresponding to the value being removed. |
remove Routine Return Value
Returns TRUE if key was removed from table, otherwise returns FALSE.
When an entry in a table is no longer needed, it may be removed using remove. Subsequent attempts to access key will result in its value not being found.
Supported Table and Value Types
Table 16-10 remove Routine Supported Table and Value Types
| Table | Value | Supported? |
|---|---|---|
|
greylisting |
- |
X |
|
simple |
integer |
X |
|
simple |
string |
X |
|
throttle |
- |
X |
Example
The following example can be used when the record for fred@example.org is no longer needed.
$[/opt/sun/comms/messaging/lib/check_metermaid.so,remove,scores,fred@example.org]
This section describes the store routine.
Description
The store routine is used to store a new value into the table.
Table 16-11 store Routine Options
| Option | Description |
|---|---|
|
table |
Table into which the new value is to be stored. |
|
key |
Key corresponding to the value. |
|
value |
New value. |
store Routine Return Value
Returns TRUE if the new value was stored, FALSE otherwise. Returns no resultant string.
store is similar to adjust in that it can be used to put data into a table. Unlike adjust, however, any previous value that may exist is overwritten by store. Also, in addition to integer data, strings may also stored into those tables that permit it. For a greylisting table, value is ignored and instead the new key is stored into table as a valid entry for subsequent queries.
Supported Table and Value Types
Table 16-12 store Routine Supported Table and Value Types
| Table | Value | Supported? |
|---|---|---|
|
greylisting |
- |
X |
|
simple |
integer |
X |
|
simple |
string |
X |
|
throttle |
- |
- |
Example
The following example sets an initial value into a table that can be used by subsequent fetch operations.
$[/opt/sun/comms/messaging/lib/check_metermaid.so,store,loginhosts,barney@example.org,quarry.example.org]
This section describes the test routine.
Description
The test routine allows you to compare an integer value in a simple table against a supplied comparator.
Table 16-13 test routine Options
| Option | Description |
|---|---|
|
table |
Table in which key is found |
|
key |
Key corresponding to the value being adjusted |
|
comparator |
Comparison symbol(s) '<', '>', and/or '=', followed by a numeric value |
test Routine Return Value
Returns TRUE if the comparison is true, and FALSE otherwise; no resultant string is returned.
test takes the current integer value for key in the table called table and compares the resulting value against the comparator, returning the result. If key does not exist in table, then 0 is used as the value to be compared.
Table 16-14 test Routine Supported Table and Value Types
| Table | Value | Supported? |
|---|---|---|
|
greylisting |
- |
X |
|
simple |
integer |
X |
|
simple |
string |
- |
|
throttle |
- |
X |
Example
The following example tests the number of login attempts made to see whether it exceeds a defined threshold.
$[/opt/sun/comms/messaging/lib/check_metermaid.so,test,logins,wilma@example.org,>5]
This section describes the throttle routine.
Description
The throttle routine is used to count incoming connections or transactions over a period of time enforcing a quota limit.
Table 16-15 throttle Routine Options
| Option | Description |
|---|---|
|
table |
Table in which is holding the items being counted |
|
key |
Key corresponding to the particular "hit count" to be incremented |
throttle Routine Return Value
Returns TRUE if quota has been exceeded during the past quota_time seconds, otherwise returns FALSE.
For more detailed information on setting up throttle tables with configuration examples, refer to the Messaging Server Security Guide.