Check_memcache.so callout

From Messaging Server Technical Reference Wiki
Jump to: navigation, search



New in 8.0, the check_memcache.so mapping callout can be used to access memcache from mapping tables or rewrite rules. The callout is similar to the check_metermaid.so callout, and provides a number of routines that can be called.

The general parameter format for all routines is:


[flags],[host[:port][;host[:port]...]],key[,value/lockout/quota][,timeout/test/quota_time]
(0)      (1)   (2)                     (3)  (4)                   (5)     (6)  (7)

The first four arguments common to all routines are:

flags (bit-encoded integer)
The flags parameter provides a number of flags that affect the entire option. The default is 0 if no value is specified. The bits and their meanings are shown in the check_memcache.so flags parameter bit values below.
host (string)
Host name of memcached server to use. The value specified by the memcache_host MTA option will be used if no host is provided here. If a semicolon-separated list of host:port pairs is specified one will be chosen by applying a hash function to the key. This provides the means to distribute key-value pairs across multiple memcache servers. Note that the algorithm used is the same as for the memcache Sieve extension.
port (integer 0-65535)
The memcached server port. The value specified by the memcache_port MTA option will be used if no port is provided here.
key (string)
The key associated with the entry being accessed.
check_memcache.so flags parameter bit values
Bit(s) Value(s) Meaning
0-⁠2 0-⁠7 Debug level. Higher levels produce more debug output.
3 8 If set, causes all permanent failures to return as successful.
4 16 If set, causes an empty string to be returned regardless of what the callout did or didn't do.
5 32 Sets the penalize flag for throttle operations.
6 64 If set, hashes the provided key prior to use.
7 128 If set, normalizes the provided key to lower case
8 256 If set, don't add entry if it is missing. This flag applies to the ADJUST, ADJUST_AND_TEST, and THROTTLE routines.
9 512 If set, treat the entry (which must exist) as a throttle entry. This flag applies to the ADJUST and ADJUST_AND_TEST routines and must be used in order for these routines to handle throttle data.

Additional parameters are consumed by specific routines:

value (string or unsigned integer)
The value to be added, stored, replaced, etc.
timeout (unsigned integer)
Amount of time that the server should retain the entry, specified as an integer number of seconds. The default is 0, which means the entry should be retained indefinitely.
test
An unsigned integer preceeded by a single character indicating the type of test to perform. Possible test types are: (1) <i - Callout succeeds if the result is less than i, (2) >i - Callout succeeds if the result is greater than i, and (3) =i - Callout succeeds if the result is equal to i.
quota_time, quota (unsigned integers)
Throttle parameters. See the MeterMaid documentation for details of the semantics of these parameters.

The available routines and their specific parameter formats are:


add,flags,[host:[port]],key,value,timeoout

Adds an entry with the specified key, value and timeout. This routine will fail if an entry with the specified key is already present. An empty string is always returned.


adjust,flags,[host:[port]],key,value[,timeout]

Adjust the entry with the specified key by the amount specified by value. The entry must contain an unsigned decimal string and value must be an optionally signed integer. The specified entry will be created (with a value of 0) prior to adjustment if it doesn't already exist. The adjusted value is retured as an unsigned decimal string. The timeout value is only used if the entry has to be created.


adjust_and_test,flags,[host:[port]],key,value,test[,timeout]

Adjust the entry with the specified key as adjust would, then test the result with the specified test. An empty string is always returned.


append,flags,[host:[port]],key,value

Append the specified value to the entry with the specified key. This routine will fail if an entry with the specified key is not already present. An empty string is already returned.


fetch,flags,[host:[port]],key

Return the value of the entry with the specified key. The callout fails if no entry with the specified key is present.


prepend,flags,[host:[port]],key,value

Prepend the specified value to the entry with the specified key. This routine will fail if an entry with the specified key is not already present. An empty string is already returned.


remove,flags,[host:[port]],key[,lockout]

Remove the entry with the specified key. The lockout, if present, is an unsigned integer specifying the amount of time to "lock" the key - during that time attempts to add an entry with that key will fail. A lockout value of 0 is the default and causes no lockout to occur. This routine will fail if an entry with the specified key is not already present. An empty string is already returned.


replace,flags,[host:[port]],key,value,timeout

Update value and timeout of the entry with the specified key. This routine will fail if an entry with the specified key is not already present. An empty string is always returned.


store,flags,[host:[port]],key,value,timeout

Creates a new entry or updates an existing entry with the specified key, value, and timeout.


test,flags,[host:[port]],key,test

Tests the value of the entry with the specified key.


throttle,flags,[host:[port]],key,quota,quota_time

Implements the MeterMaid throttle capability. See the MeterMaid documentation for details of throttle semantics. Note that since there is no server-side awareness of entry semantics, the quota and quota_time parameters must be specified in every throttle call in case the entry needs to be created. If the entry already exists, the parameter values will be checked against the corresponding values store in the entry. The call will fail if this check fails.

This callout has also been enhanced to work with the mapping table $. facility in order to be able to handle temporary errors in a sensible fashion.

An example of using memcached to implement a simple rate limit on a given authenticated sender to 10 messages every 5 minutes would be to add the following to the end of the FROM_ACCESS mapping:


FROM_ACCESS

  TCP|*|SMTP*|MAIL|tcp_*|*|*  $C$;R$[IMTA_LIB:check_memcache.so,throttle,0,memcache.example.com:22122,sendlim-$4,10,300]$X4.2.3|$NRate$ too$ high$E

This would limit users to 10 messages every 5 minutes (300 seconds). Here "memcache.example.com:22122" would be replaced with name and port of an actual memcached server.

A more flexible mechanism would allow the limit to be specified on a per-user basis along with a default. This could be accomplished by defining an LDAP attribute for the purpose, say senderRateLimit, and making it available to the FROM_ACCESS mapping via the sixth spare LDAP slot:


    msconfig> set ldap_spare_6 senderRateLimit
    msconfig# set include_spares1 32

The follow additions to the FROM_ACCESS mapping would then be needed:


FROM_ACCESS

  TCP|*|SMTP*|MAIL|tcp_*|*|*|  $C$;R$[IMTA_LIB:check_memcache.so,throttle,0,memcache.example.com:22122,sendlim-$4,10,300]$X4.2.3|$NRate$ too$ high$E
  TCP|*|SMTP*|MAIL|tcp_*|*|*|*  $C$;R$[IMTA_LIB:check_memcache.so,throttle,0,memcache.example.com:22122,sendlim-$4,$5,300]$X4.2.3|$NRate$ too$ high$E

See also: