Example Sieve external lists with properties

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

The MTA supports a private feature of Sieve external lists, whereby external lists can return properties associated with list entries. This can be a powerful additional tool. This section presents two examples below, both variants on "capturing" copies of particular messages passing through the MTA.

Capturing a user's "external" messages

Suppose that you wish to capture copies of certain users' Internet correspondence, without bothering to capture copies of those users' internal correspondence (meaning that direct use of an ldap_capture LDAP attribute would capture unneeded messages), and that you'd like to keep track of which users are in this category in LDAP, rather than hard-coding such a list directly into a Sieve script. One approach for doing this would be to use channel-level source and destination Sieve scripts on the tcp_local channel (which is the channel handling messages coming in from, or going to, the Internet), where such Sieve scripts make use of an external list to check LDAP to determine which users' messages are eligible for capture. Using the properties feature of the MTA's Sieve external lists implementation, the external list will also return the capturer address to use (the address to which to send the captured message copies). The components of such an approach are:

  1. Add some user-level LDAP attribute to the schema (or disable schema checking) and set that attribute on the users for whom you want capture, with a value which is the address to which to send the captured message copies. (Note that typically such an attribute should have ACIs so that users themselves can't even see the attribute, let alone change its value.) This example will assume there is an attribute named mailCaptureInternet for this purpose. (Note that if you already have ldap_capture defined and pointing to the name of some LDAP attribute used for unconditional capture, then you probably don't want to use the same attribute for this "conditional" capture, as that would merely result in an additional capture copy in the "conditional" cases. Instead you want a different LDAP attribute, which will only be consulted and have an effect in this special case.)
  2. Set the ldap_spare_4 MTA option to the name of this "conditional capture" attribute; in unified configuration:

    msconfig> set mta.ldap_spare_4 "mailCaptureInternet"

    or in legacy MTA configuration mode, set in the option.dat file:


    Pointing ldap_spare_4 at this attribute means that the attribute's value will be included in probes of the SIEVE_EXTLISTS mapping table, which will turn out to be convenient.

  3. Define Sieve external lists named "capture-to" and "capture-from" via a SIEVE_EXTLISTS mapping table as follows. (In legacy configuration mode, this SIEVE_EXTLISTS mapping table should be placed in the MTA mappings file; in Unified Configuration mode, the mapping table can be created by editting from within the msconfig utility.)

    ! Define an external list named "capture-to" for use in "envelope" tests of 
    ! the To address.  Because the LDAP_SPARE_4 field of the pattern has a 
    ! match pattern of %*, a probe will match this entry only when the envelope 
    ! To recipient being tested has a non-empty mailCaptureInternet value: 
      envelope|*|%*|*|*|capture-to|*   $Y$*$1$2 
      envelope|*|*|*|*|capture-to|*    $N
    ! When the probe matches, the test succeeds ($Y) and the entry returns 
    ! <mailCaptureInternet-value> for the matched address as the first (indeed 
    ! only) property, so it will be accessible via Sieve ${1} variable. 
    ! Note that because this is a recipient-specific test, making use of the 
    ! LDAP_SPARE_4 value, the entry includes $* in the template. 
    ! Now define an external list named "capture-from" for use in "envelope" tests 
    ! of the From address.  Because the Sieve language is oriented towards 
    ! performing actions on behalf of message recipients, obtaining information 
    ! from LDAP regarding the message sender (envelope From) requires some 
    ! additional, explicit LDAP lookups (more than is required for the "capture-to" 
    ! external list case). 
    ! First, get the base DN for the user entries in the domain of the From 
    ! address and rebuild a new probe: 
      envelope|*|*|*|*|capture-from|*@*  $N$CBASEDN|FROM|$4@$5|$}$5,_base_dn_{ 
    ! If the envelope From was that of a user in one of "our" domains, then 
    ! the $}<domain-name>,_base_dn_{ lookup should succeed, so the entry 
    ! succeeded and the probe is now: 
    ! BASEDN|FROM|<from-address>|<basedn-of-from-domain> 
      BASEDN|FROM|*|*     \
    ! When this probe matched and the LDAP lookup succeeds, then the test 
    ! succeeds ($Y) and the entry returns <mailCaptureInternet-value> 
    ! as a first property (so accessible via Sieve ${1} variable), thus the 
    ! capture attribute value for that matched address is available. 
  4. On the tcp_local channel (and any other dedicated-to-Internet-correspondence channel(s)), use a sourcefilter Sieve along the lines of:

    require ["envelope","extlists","variables"]; 
    if envelope :list "to" "capture-to" { capture "${1}"; } 

    and a destinationfilter Sieve along the lines of:

    require ["envelope","extlists","variables"]; 
    if envelope :list "from" "capture-from" { capture "${1}"; } 

Note that this example used the same LDAP attribute mailCaptureInternet to determine capture for both incoming and outgoing directions. (The incoming, "capture-to", list took advantage of setting ldap_spare_4 to conveniently fetch the value of this attribute for the recipient; for the outgoing, "capture-from", list, two separate, explicitly configured LDAP lookups were required to first locate where in the directory to search, and second fetch the actual attribute value.) But separate attributes could be used, if different criteria were desired for incoming vs. outgoing. Also, in this example the Sieve external list itself simply checks the attribute value---and the fact that the capture is (intended) for Internet correspondence is incorporated by virtue of the Sieve filters being placed on the Internet correspondence channel (tcp_local). More complicated Sieve filter tests combined with this external list consultation could further refine which messages are captured; see for instance, the additional, "attachment type" testing shown in the example below. Or use of a Sieve filter consulting these external lists on different MTA channels could completely alter which messages get captured.

See also: