Difference between revisions of "Check memcache.so callout"

From Messaging Server Technical Reference Wiki
Jump to: navigation, search
m (Bulk update)
m (Bulk update)
 
(11 intermediate revisions by one user not shown)
Line 3: Line 3:
 
{{DISPLAYTITLE:Check_memcache.so callout}}
 
{{DISPLAYTITLE:Check_memcache.so callout}}
  
New in 8.0, the check_memcache.so mapping callout can be used to access memcache from mappings or rewrite rules. The callout is similar to the check_metermaid.so callout, and provides a number of routines that can be caled.  
+
New in 8.0, the <code>check_memcache.so</code> mapping callout can be used to access memcache from [[Mapping entry templates#mapping_routine_substitutions|mapping tables]] or [[Rewrite routine substitutions#Rewrite_routine_substitutions|rewrite rules]]. The callout is similar to the [[check_metermaid callouts#check_metermaid_callouts|<code>check_metermaid.so</code> callout]], and provides a number of routines that can be called.  
  
 
The general parameter format for all routines is:  
 
The general parameter format for all routines is:  
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  [flags],[host[:port][;host[:port]...]],key[,value/lockout/quota][,timeout/test/quota_time]
+
  &#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                    
+
  [[Check_memcache.so callout#memcache_params_call0|(0)]]     [[Check_memcache.so callout#memcache_params_call1|(1)]]   [[Check_memcache.so callout#memcache_params_call2|(2)]]                     [[Check_memcache.so callout#memcache_params_call3|(3)]]  [[Check_memcache.so callout#memcache_params_call4|(4)]]                   [[Check_memcache.so callout#memcache_params_call5|(5)]]     [[Check_memcache.so callout#memcache_params_call6|(6)]]  [[Check_memcache.so callout#memcache_params_call7|(7)]]</font>
</font>
+
 
The first four arguments common to all routines are:  
 
The first four arguments common to all routines are:  
  
Line 16: Line 15:
  
 
<dt>
 
<dt>
<code>flags</code> (bit-encoded integer)
+
<span id='memcache_params_call0'></span>''<code>flags</code>'' (bit-encoded integer)
 
</dt>
 
</dt>
  
 
<dd>
 
<dd>
  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 callout#table_check_memcache_flag_parameter|table below]].
+
  The ''<code>flags</code>''  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 callout#table_check_memcache_flag_parameter|<code>check_memcache.so </code>''<code>flags</code>''  parameter bit values]] below.
 
</dd>
 
</dd>
  
 
<dt>
 
<dt>
host (string)
+
<span id='memcache_params_call1'></span>''<code>host</code>'' (string)
 
</dt>
 
</dt>
  
 
<dd>
 
<dd>
  Host name of memcached server to use. The value specified by the <code>memcache_host</code> 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.  
+
  Host name of memcached server to use. The value specified by the [[memcache_host MTA/channel options#memcache_host|<code>memcache_host</code>]]  MTA option will be used if no host is provided here. If a semicolon-separated list of ''<code>host</code>''<code>:</code>''<code>port</code>'' 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 [[Sieve memcache extension#Sieve_memcache_extension|memcache Sieve extension]].  
 
</dd>
 
</dd>
  
 
<dt>
 
<dt>
port (integer 0-65535)
+
<span id='memcache_params_call2'></span>''<code>port</code>'' (integer 0-65535)
 
</dt>
 
</dt>
  
 
<dd>
 
<dd>
  The memcached server port. The value specified by the <code>memcache_port</code> MTA option will be used if no port is provided here.  
+
  The memcached server port. The value specified by the [[memcache_port MTA/channel options#memcache_port|<code>memcache_port</code>]]  MTA option will be used if no port is provided here.  
 
</dd>
 
</dd>
  
 
<dt>
 
<dt>
key (string)
+
<span id='memcache_params_call3'></span>''<code>key</code>'' (string)
 
</dt>
 
</dt>
  
Line 51: Line 50:
 
{| border="1"
 
{| border="1"
  
|+ <span id='table_check_memcache_flag_parameter'></span>'''check_memcache.so flag parameter bit values'''
+
|+ <span id='table_check_memcache_flag_parameter'></span>'''<tt>check_memcache.so </tt>'''''<tt>flags</tt>''''' parameter bit values'''
 
|- style="background:lightseagreen"
 
|- style="background:lightseagreen"
 
! align="left" scope="col" | Bit(s)
 
! align="left" scope="col" | Bit(s)
Line 57: Line 56:
 
! align="center" scope="col" | Meaning
 
! align="center" scope="col" | Meaning
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
| | 0-2
+
| |         0-⁠2   
| | 0-7
+
| | 0-⁠7
 
| |        Debug level. Higher levels produce more debug output.     
 
| |        Debug level. Higher levels produce more debug output.     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
Line 71: Line 70:
 
| | 5
 
| | 5
 
| | 32
 
| | 32
| |        Sets the penalize flag for throttle operations.     
+
| |        Sets the penalize flag for <tt>throttle</tt> operations.     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
 
| | 6
 
| | 6
 
| | 64
 
| | 64
| |        If set, hashes the provided key prior to use.    
+
| |        If set, hashes the provided ''<tt>key</tt>'' prior to use. This can be      useful in meeting encrypted at rest requirements.      The hash function used is controlled by the [[memcache_hash_algorithm MTA option#memcache_hash_algorithm|<tt>memcache_hash_algorithm</tt>]]      MTA option.   
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
 
| | 7
 
| | 7
 
| | 128
 
| | 128
| |        If set, normalizes the provided key to lower case     
+
| |        If set, normalizes the provided ''<tt>key</tt>'' to lower case     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
 
| | 8
 
| | 8
 
| | 256
 
| | 256
| |        If set, don&#x27;t add entry if it is missing. This flag      applies to the ADJUST, ADJUST_AND_TEST, and THROTTLE routines.     
+
| |        If set, don&#x27;t add entry if it is missing. This flag      applies to the <tt>ADJUST</tt>, <tt>ADJUST_AND_TEST</tt>, and       <tt>THROTTLE</tt> routines.     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
 
| | 9
 
| | 9
 
| | 512
 
| | 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.     
+
| |        If set, treat the entry (which must exist) as a throttle      entry. This flag applies to the <tt>ADJUST</tt> and       <tt>ADJUST_AND_TEST</tt>       routines and must be used in order for these routines to handle      throttle data.     
 
|}
 
|}
  
Line 95: Line 94:
  
 
<dt>
 
<dt>
value (string or unsigned integer)
+
<span id='memcache_params_call4'></span>''<code>value</code>'' (string or unsigned integer)
 
</dt>
 
</dt>
  
Line 103: Line 102:
  
 
<dt>
 
<dt>
timeout (unsigned integer)
+
<span id='memcache_params_call5'></span>''<code>timeout</code>'' (unsigned integer)
 
</dt>
 
</dt>
  
 
<dd>
 
<dd>
  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.  
+
  Amount of time that the server should retain the entry, specified as an integer number of seconds. The default is <code>0</code>, which means the entry should be retained indefinitely.  
 
</dd>
 
</dd>
  
 
<dt>
 
<dt>
test
+
<span id='memcache_params_call6'></span>''<code>test</code>''
 
</dt>
 
</dt>
  
 
<dd>
 
<dd>
  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.  
+
  An unsigned integer preceeded by a single character indicating the type of test to perform. Possible test types are: (1) <code>&#x3c;</code>''<code>i</code>'' - Callout succeeds if the result is less than ''<code>i</code>'', (2) <code>&#x3e;</code>''<code>i</code>'' - Callout succeeds if the result is greater than ''<code>i</code>'', and (3) <code>=</code>''<code>i</code>'' - Callout succeeds if the result is equal to ''<code>i</code>''.  
 
</dd>
 
</dd>
  
 
<dt>
 
<dt>
quota_time, quota (unsigned integers)
+
<span id='memcache_params_call7'></span>''<code>quota_time</code>'', ''<code>quota</code>''  (unsigned integers)
 
</dt>
 
</dt>
  
 
<dd>
 
<dd>
  Throttle parameters. See the MeterMaid documentation for details of the semantics of these parameters.  
+
  Throttle parameters. ''<code>quota_time</code>'' specifies the specifies the duration of the period over which counts are recorded, and ''<code>quota</code>'' specifies the maximum number of counts to permit during the period.  
 
</dd>
 
</dd>
  
Line 131: Line 130:
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  ADD,flags,[host:[port]],key,value,timeoout
+
  add,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value'',''timeoout''</font>
</font>
+
Adds an entry with the specified ''<code>key</code>'', ''<code>value</code>'' and ''<code>timeout</code>''. This routine will fail if an entry with the specified ''<code>key</code>''  is already present. An empty string is always returned.  
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.  
+
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  ADJUST,flags,[host:[port]],key,value[,timeout]
+
  adjust,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value''&#x5b;,''timeout''&#x5d;
 
  </font>
 
  </font>
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&#x27;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 the entry with the specified ''<code>key</code>'' by the amount specified by ''<code>value</code>''. The entry must contain an unsigned decimal string and ''<code>value</code>'' must be an optionally signed integer. The specified entry will be created (with a value of <code>0</code>) prior to adjustment if it doesn&#x27;t already exist. The adjusted value is retured as an unsigned decimal string. The ''<code>timeout</code>'' value is only used if the entry has to be created.  
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  ADJUST_AND_TEST,flags,[host:[port]],key,value,test[,timeout]
+
  adjust_and_test,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value'',''test''&#x5b;,''timeout''&#x5d;
 
  </font>
 
  </font>
Adjust the entry with the specified key as ADJUST would, then test the result with the specified test. An empty string is always returned.  
+
Adjust the entry with the specified ''<code>key</code>'' as <code>adjust</code> would, then test the result with the specified ''<code>test</code>''. An empty string is always returned.  
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  APPEND,flags,[host:[port]],key,value
+
  append,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value''</font>
</font>
+
Append the specified ''<code>value</code>'' to the entry with the specified ''<code>key</code>''. This routine will fail if an entry with the specified ''<code>key</code>'' is not already present.  An empty string is already returned.  
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.  
+
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  FETCH,flags,[host:[port]],key
+
  fetch,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key''</font>
</font>
+
Return the value of the entry with the specified ''<code>key</code>''. The callout fails if no entry with the specified ''<code>key</code>'' is present.  
Return the value of the entry with the specified key. The callout fails if no entry with the specified key is present.  
+
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  PREPEND,flags,[host:[port]],key,value
+
  prepend,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value''</font>
</font>
+
Prepend  the specified ''<code>value</code>'' to the entry with the specified ''<code>key</code>''. This routine will fail if an entry with the specified ''<code>key</code>'' is not already present.  An empty string is already returned.  
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.  
+
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  REMOVE,flags,[host:[port]],key[,lockout]
+
  remove,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key''&#x5b;,''lockout''&#x5d;
 
  </font>
 
  </font>
Remove the entry with the specified key. 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 default 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.  
+
Remove the entry with the specified ''<code>key</code>''. The ''<code>lockout</code>'', 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 ''<code>key</code>''  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 ''<code>key</code>'' is not already present.  An empty string is already returned.  
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  REPLACE,flags,[host:[port]],key,value,timeout
+
  replace,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value'',''timeout''</font>
</font>
+
Update value and timeout of the entry with the specified ''<code>key</code>''. This routine will fail if an entry with the specified ''<code>key</code>''  is not already present. An empty string is always returned.  
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.  
+
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  STORE,flags,,[host:[port]],key,value,timeout
+
  store,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''value'',''timeout''</font>
 +
Creates a new entry or updates an existing entry with the specified ''<code>key</code>'', ''<code>value</code>'', and  ''<code>timeout</code>''.
 +
 +
<font color="mediumblue">
 +
test,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''test''</font>
 +
Tests the value of the entry with the specified ''<code>key</code>''.
 +
 +
<font color="mediumblue">
 +
throttle,''flags'',&#x5b;''host'':&#x5b;''port''&#x5d;&#x5d;,''key'',''quota'',''quota_time''</font>
 +
Implements the MeterMaid throttle capability. See the  [[MeterMaid#MeterMaid|MeterMaid]] documentation for details of throttle semantics. Note that since there is no server-side awareness of entry semantics, the  ''<code>quota</code>'' and ''<code>quota_time</code>'' 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  [[Mapping entry templates#Mapping_LDAP_query_URL_substitutions|<code>$.</code>]] 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 <code>FROM_ACCESS</code> mapping:
 +
 +
<font color="mediumblue">
 +
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
 
  </font>
 
  </font>
Creates a new entry or updates and existing entry with the specified key, value, and timeout.
+
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 <code>FROM_ACCESS</code> mapping via the sixth spare LDAP slot:
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
TEST,flags,,[host:[port]],key,test
+
    msconfig&#x3e; set ldap_spare_6 senderRateLimit
 +
    msconfig# set include_spares1 32
 
  </font>
 
  </font>
Tests the value of the entry with the specified key.
+
The follow additions to the <code>FROM_ACCESS</code> mapping would then be needed:
 
   
 
   
 
  <font color="mediumblue">
 
  <font color="mediumblue">
  THROTTLE,flags,,[host:[port]],key,quota,quota_time
+
  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
 
  </font>
 
  </font>
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&#x27;s  <code>$.</code> facility in order to be able to handle temporary errors in a sensible fashion.
+
See also:
 +
* [[Mapping entry templates#Mapping_routine_substitutions|Mapping entry templates]]
 +
* [[Rewrite routine substitutions#Rewrite_routine_substitutions|Rewrite routine substitutions]]
 +
* [[check_metermaid callouts#check_metermaid_callouts|check_metermaid callouts]]
 +
* [[memcache_host MTA/channel options#memcache_host|memcache_host Option]]
 +
* [[memcache_port MTA/channel options#memcache_port|memcache_port Option]]
 +
* [[Memcache MTA options#Memcache_MTA_options|Memcache MTA options]]
 +
* [[Sieve memcache extension#Sieve_memcache_extension|Sieve memcache extension]]
 +
* [[MeterMaid#MeterMaid|MeterMaid]]
 +
* [[Mapping entry templates#Mapping_LDAP_query_URL_substitutions|Mapping entry templates]]
 +
* [[Callout routines#Callout_routines|Callout routines]]
 
[[Category: Reference]]
 
[[Category: Reference]]
 
[[Category: Discussion]]
 
[[Category: Discussion]]

Latest revision as of 17:11, 13 February 2020



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. This can be useful in meeting encrypted at rest requirements. The hash function used is controlled by the memcache_hash_algorithm MTA option.
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. quota_time specifies the specifies the duration of the period over which counts are recorded, and quota specifies the maximum number of counts to permit during the period.

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: