Check memcache.so callout

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

The general parameter format for all routines is: &#x5b;flags&#x5d;,&#x5b;host&#x5b;:port&#x5d;&#x5b;;host&#x5b;:port&#x5d;...&#x5d;&#x5d;,key&#x5b;,value/lockout/quota&#x5d;&#x5b;,timeout/test/quota_time&#x5d; (0)     (1)   (2)                     (3)  (4)                   (5)     (6)  (7) The first four arguments common to all routines are:



    (bit-encoded integer) 

 The   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     parameter bit values below. 

    (string) 

 Host name of memcached server to use. The value specified by the   MTA option will be used if no host is provided here. If a semicolon-separated list of     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. 

    (integer 0-65535) 

 The memcached server port. The value specified by the   MTA option will be used if no port is provided here. 

 <span id='memcache_params_call3'>   (string) </dt>

 The key associated with the entry being accessed. </dd>

</dl>

Additional parameters are consumed by specific routines:

<dl>

 <span id='memcache_params_call4'>   (string or unsigned integer) </dt>

 The value to be added, stored, replaced, etc. </dd>

 <span id='memcache_params_call5'>   (unsigned integer) </dt>

 Amount of time that the server should retain the entry, specified as an integer number of seconds. The default is,  which means the entry should be retained indefinitely. </dd>

 <span id='memcache_params_call6'>   </dt>

 An unsigned integer preceeded by a single character indicating the type of test to perform. Possible test types are: (1)   - Callout succeeds if the result  is less than  , (2)    - Callout succeeds if the result  is greater than  , and (3)    - Callout succeeds if the result is  equal to  . </dd>

 <span id='memcache_params_call7'>  ,   (unsigned integers) </dt>

 Throttle parameters.   specifies the specifies the duration of the period over which counts are recorded, and   specifies the maximum number of counts to permit during the period. </dd>

</dl>

The available routines and their specific parameter formats are: add,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value,timeoout Adds an entry with the specified  ,   and  . This routine will fail if an entry with the specified   is already present. An empty string is always returned. adjust,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value&#x5b;,timeout&#x5d; Adjust the entry with the specified   by the amount specified by  . The entry must contain an unsigned decimal string and   must be an optionally signed integer. The specified entry will be created (with a value of ) prior to adjustment if it doesn&#x27;t already exist. The adjusted value is retured as an unsigned decimal string. The   value is only used if the entry has to be created. adjust_and_test,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value,test&#x5b;,timeout&#x5d; Adjust the entry with the specified   as   would, then test the result with the specified  . An empty string is always returned. append,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value Append the specified   to the entry with the specified  . This routine will fail if an entry with the specified   is not already present. An empty string is already returned. fetch,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key Return the value of the entry with the specified  . The callout fails if no entry with the specified   is present. prepend,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value Prepend the specified   to the entry with the  specified  . This routine will fail if an entry with the specified   is not already present. An empty string is already returned. remove,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key&#x5b;,lockout&#x5d; Remove the entry with the specified  . The  , 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   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   is not already present. An empty string is already returned. replace,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value,timeout Update value and timeout of the entry with the specified  . This routine will fail if an entry with the specified   is not already present. An empty string is always returned. store,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,value,timeout Creates a new entry or updates an existing entry with the specified  ,  , and  . test,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,key,test Tests the value of the entry with the specified  . throttle,flags,&#x5b;host:&#x5b;port&#x5d;&#x5d;,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   and   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  mapping: FROM_ACCESS TCP&#x7c;&#x2a;&#x7c;SMTP&#x2a;&#x7c;MAIL&#x7c;tcp_&#x2a;&#x7c;&#x2a;&#x7c;&#x2a; $C$;R$&#x5b;IMTA_LIB:check_memcache.so,throttle,0,memcache.example.com:22122,sendlim-$4,10,300&#x5d;$X4.2.3&#x7c;$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  mapping via the sixth spare LDAP slot: msconfig&#x3e; set ldap_spare_6 senderRateLimit msconfig# set include_spares1 32 The follow additions to the  mapping would then be needed: FROM_ACCESS TCP&#x7c;&#x2a;&#x7c;SMTP&#x2a;&#x7c;MAIL&#x7c;tcp_&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c; $C$;R$&#x5b;IMTA_LIB:check_memcache.so,throttle,0,memcache.example.com:22122,sendlim-$4,10,300&#x5d;$X4.2.3&#x7c;$NRate$ too$ high$E TCP&#x7c;&#x2a;&#x7c;SMTP&#x2a;&#x7c;MAIL&#x7c;tcp_&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a; $C$;R$&#x5b;IMTA_LIB:check_memcache.so,throttle,0,memcache.example.com:22122,sendlim-$4,$5,300&#x5d;$X4.2.3&#x7c;$NRate$ too$ high$E

See also:
 * Mapping entry templates
 * Rewrite routine substitutions
 * check_metermaid callouts
 * memcache_host Option
 * memcache_port Option
 * Memcache MTA options
 * Sieve memcache extension
 * MeterMaid
 * Mapping entry templates
 * Callout routines