Sieve metermaid extension

As of the 8.0 release, the MTA supports a private " " operator, to access and manipulate data stored in MeterMaid; the operator has uses both as an action and as a test. This nonstandard extension is available without any special capability declaration; no " " action is needed for its use. By default, the " " operator may be used in any Sieve script, but its availability may be selectively disabled via the  MTA option.

The location of the MeterMaid server that Sieve scripts may query, as well as various other basics of MeterMaid communication, server are specified via  MeterMaid MTA options, especially ,  , and.

The various Sieve " " operations share a set of common nonpositional parameters:  

 :host host-string 

 Specifies the host name and port for the MeterMaid server to use in     format. The   part is optional and defaults to value given to the   MTA option. If " " isn&#x27;t specified, the host and port are given by the  and    MTA options respectively. 

 :duplicate 

 It may be necessary to evaluate Sieves more than once, e.g., when a message is sent to multiple recipients and the Sieve employs an envelope "to" test. Additionally, even if a particular Sieve script does not contain such a test, it may nevertheless be necessary to reevaluate it if a previous script was reevaluated and that action changed one or more of the inputs to the current script. 

 It is undesirable in most cases to reevaluate " " actions that perform increment, decrement, throttle or greylist operations. As such, most " " operations are skipped when a script is reevaluated. (The exact behavior is noted in each section below.) 

 However, there are cases, e.g., when using recipient-specific data, when reevaluation is the correct action. The " " nonpositional parameter provides this capability: if specified, the associated " " operation will be performed on both initial and subsequent evaluations. </dd>

 MATCH-TYPE and COMPARATOR </dt>

 See RFC 5228 for information about MATCH-TYPE and COMPARATOR parameters. </dd>

</dl>

The following " " operations are available: metermaid :adjustdown adjustment-value &#x5b;:host host-string&#x5d; &#x5b;:duplicate&#x5d; &#x5b;MATCH-TYPE&#x5d; &#x5b;COMPARATOR&#x5d; table-string key-string &#x5b;test-string&#x5d; The " " operation decrements the entry with the given key in the specified table by the adjustment value. This operation is only supported on simple tables configured for integer values and throttle tables.

The adjustment value can be either an integer or a string; if it is a string, it must contain an optionally signed decimal value. Negative adjustment value are allowed and will be converted into an appropriate increment operation.

The specified entry will be created (with a value of ) prior to adjustment if it doesn&#x27;t already exist.

The adjusted value is returned as an unsigned decimal string if neither MATCH-TYPE, COMPARATOR, nor   are specified. However, if any of these parameters are specified, this operation functions as a test with updated value of the entry being the tested value. MATCH-TYPE and COMPARATOR default to  and   respectively. For example: if metermaid :adjustdown 1 "table" "entry" "10" { ... handle entry less than 10 ... } " " operations are performed on reevaluations but the adjustment amount is changed to. " " causes the adjustment amount to be retained on reevaluations. metermaid :adjustup adjustment-value &#x5b;:host host-string&#x5d; &#x5b;:duplicate&#x5d; &#x5b;MATCH-TYPE&#x5d; &#x5b;COMPARATOR&#x5d; table-string key-string &#x5b;test-string&#x5d; The " " operation increments the entry with the specified key in the given table by the adjustment value. This operation is only supported on simple tables configured for integer values and throttle tables.

The adjustment value can be either an integer or a string; if it is a string, it must contain an optionally signed decimal value. Negative adjustments values are allowed and will be converted into an appropriate decrement operation.

The specified entry will be created (with a value of ) prior to adjustment if it doesn&#x27;t already exist.

The adjusted value is returned as an unsigned decimal string if neither MATCH-TYPE, COMPARATOR, nor   are specified. However, if any of these parameters are specified this operation functions as a test with updated value of the entry being the tested value. MATCH-TYPE and COMPARATOR default to  and   respectively. For example: if metermaid :adjustup 1 "table" "entry" "10" { ... handle entry greater than 10 ... } " " operations are performed on reevaluations but the          adjustment amount is changed to. " " causes the adjustment          amount to be retained on reevaluations. metermaid :fetch &#x5b;:host host-string&#x5d; &#x5b;MATCH-TYPE&#x5d; &#x5b;COMPARATOR&#x5d; table-string key-string &#x5b;test-string&#x5d; The " " operation fetches the value of the entry with the specified key from the given table. Fetch is supported on all types of tables, although in the case of throttle tables it is implemented by performing an adjust with an adjustment value of.

The entry&#x27;s value is simply returned as a string if neither MATCH-TYPE, COMPARATOR, nor   are specified. An empty string will be returned if the specified entry doesn&#x27;t exist.

However, if any of the three parameters are specified, this operation functions as a test with current value of the entry being the tested value. MATCH-TYPE and COMPARATOR default to  and    respectively. The test always fails if the entry does not exist. This can be used to test for the existence of an entry: if metermaid :fetch :matches "table" "entry" "&#x2a;" { ... entry exists ... } " " operations are simply repeated on reevaluations. metermaid :greylisting &#x5b;:host host-string&#x5d; &#x5b;:duplicate&#x5d; &#x5b;MATCH-TYPE&#x5d; &#x5b;COMPARATOR&#x5d; table-string key-string &#x5b;test-string&#x5d; The " " operation provides access to the  MeterMaid greylisting capability. See the MeterMaid documentation for details of greylisting semantics. Of course this operation only works on greylisting tables.

This operation always functions as a test. If neither MATCH-TYPE, COMPARATOR, nor   are specified, then TRUE is returned if greylisting is engaged, while FALSE is returned if greylisting is not engaged or an error occurs.

If one of these three parameters is provided, the throttle is incremented and then Sieve tests are applied to the value. The default MATCH-TYPE is   and the default COMPARATOR is. Note that this is implemented as an adjust operation since the connect operation doesn&#x27;t provide the throttle value as a result.

The test aspect of " " operations is repeated on reevaluations, but the entry is not updated. " " causes the entire operation to be performed on reevaluations. metermaid :remove &#x5b;:host host-string&#x5d; &#x5b;:duplicate&#x5d; table-string key-string The " " operation removes the entry with the specified key from the given table. Returns TRUE if the operation is successful, FALSE if it is not.

Remove is supported on all types of tables.

" " operations are skipped and return success unconditionally on reevaluations by default. " " forces the operation to be performed on all reevaluations. metermaid :store &#x5b;:host host-string&#x5d; table-string key-string value-string The " " operation creates a new entry or updates an existing entry with the specified key in the given table. Returns TRUE if the operation is successful, FALSE if it is not.

Store is supported on all table types except throttle tables.

" " operations are simply repeated on reevaluations. metermaid :throttle &#x5b;:host host-string&#x5d; &#x5b;:duplicate&#x5d; &#x5b;MATCH-TYPE&#x5d; &#x5b;COMPARATOR&#x5d; table-string key-string The " " operation provides access to the MeterMaid throttle capability. See the MeterMaid documentation for details of throttle semantics. Of course this operation only works on throttle tables.

This operation always functions as a test. If neither MATCH-TYPE, COMPARATOR, nor   are specified, then TRUE is returned if the throttle is engaged, while FALSE is returned if the throttle is not engaged or an error occurs.

If one of these three parameters is provided, the throttle is incremented and then Sieve tests are applied to the value. The default MATCH-TYPE is    and the default COMPARATOR is. Note that this is implemented as an adjust operation since the connect operation doesn&#x27;t provide the throttle value as a result.

The test aspect of " " operations is repeated on reevaluations but the entry is not updated. " " causes the entire operation to be performed on reevaluations.

See also:
 * enable_sieve_metermaid MTA Option
 * MeterMaid MTA options
 * metermaid_host MTA Option
 * metermaid_port MTA Option
 * metermaid_secret MTA Option
 * MeterMaid
 * Sieve supported extensions
 * Sieve filters