
                                                                  Johannes Nohl
                                                             Berlin, 2015-10-18


## Tine 2.0 simpleMail SMTP-Backend (LDAP) ##


ABSTRACT

When storing additional mail attributes outside user's Distinguished Name (DN) 
you can link to user's LDAP branch and mail transfer agents like Postfix will 
follow the target DN provided as i.e. “special_result_attribute”. With Tine 2.0 
those external mail config is readable and - as required - writable through the 
simpleMail backend for SMTP. You may use the provided LDAP scheme or configure 
all by yourself (e.g. how to link mail addresses to user's DN). 


PURPOSE AND OVERVIEW

Tine 2.0 can handle user specific smtp settings in LDAP directories; additional
information for *mail aliases*, *mail forwarding addresses* and an option to
*forward only* (no local delivery) can be managed within the Admin module.

While already existing backends for SMTP were limited to information stored as
attributes in user's LDAP-node (DN:uid), simpleMail can read attributes from
DNs anywhere else in the LDAP-tree. In addition simpleMail can write DNs below
a predefined path outside the uid entry. To keep the relationship between
simplMail's DN and user's account settings one attribute (to be named) holds
the DN of the user's node. Mail transfer agents will follow this attribute to
account settings in LDAP. 

Additionally the linked mail information is needed for Felamimail's “out of
office” assistant which will respond only to known aliases. 

LIMITATION: You need to store Tine 2.0's accounts and your mail settings in
            the same LDAP (probably on different subtrees) - the backend uses
            your already existing connection.


CONFIGURATION

Currently there's no possibility to use GUI, therefore you need to configure
simpleMail backend manually. You may select the backend option “simpleMail” 
within Tine 2.0 Setup (setup.php) but to make it fly you need to add further 
options to the configuration key “smtp” which is an javascript object (json) 
and can be accessed by the command line interface (cli) or directly in SQL-DB 
table tine20_config. 

simpleMail settings are stored within the json being themselves such an json
object:

“smtp” => { 
            [ SMTP SETTINGS like host, port, etc. ], 
            "active":true,
            "backend":"ldap_simplemail", 
            "simplemail":{ 
              [ YOUR simpleMail CONFIG GOES HERE] 
            } 
          }

To see current SMTP settings from cli: 
#> php setup.php --getconfig -- configkey=smtp

To set new SMTP config by cli: 
#> php setup.php --setconfig -- configkey=smtp configvalue='{[ JSON ]}'


OPTIONS - All available options for JSON

[mandatory] base:
Search base in LDAP for mail information (default search in subtree) and
default branch to store new entries (see storage_base)


[optional] scope: 
1 = (subtree; default), 2 = (one level), 3 (base entry).


[optional] skeleton: 
Attributes used as search filter for user related DNs and at the same time a
template for newly created DNs. You must not provide objectClass top which is
added programmatically. The attribute holding the wildcard %s represents the 
link to user's DN ("special_result_attribute"). 

  Default:  "skeleton":{ 
              "objectclass":["simplemail","mailrouting"],
              "mailUserDN":"%s" 
            },

  Note: The wildcard %s will be substituted at runtime (by inserting user's DN)


[optional] readonly: 
On saving changes request will be ignored silently. Default is false. 

        
[optional] storage_base: 
Base in LDAP-tree for writing new entries, defaults to base (see above). If 
given and different to base new config-DNs will be stored beneath. 


[optional] storage_rdn: 
Name giving attribute for newly created entries - relative DN (RDN). 

  Default:  "storage_rdn:":"cn=%u{tine20}", 

  Note: The wildcard %u will be filled at runtime (by inserting user's 
  account_name)


[optional] property_mapping: 
If you use different LDAP attributes than below you need to provide a 
parameterized mapping table. 

  Default:  "property_mapping":{ 
              "emailAliases":"mailalternateaddress",
              "emailForwards":"mailforwardingaddress",
              "emailForwardOnly":"maildiscard:boolean" 
            },

  Note: You can define a property (attribute) as on/off-option (instead of a 
        set of attributes) by adding :boolean to its LDAP equivalent.


EXAMPLES

Below you may find three common but minimal configurations (only the backend 
specific part of json is shown) 
 

1) Get information readonly from anywhere below a specific part of the
LDAP-tree (default entries here match the LDAP scheme “simpleMail”):

            "simplemail":{ 
              "base":"ou=mail,ou=config,dc=example,dc=com",
              "readonly":true 
            }

  Hint: If you manage mail settings aside Tine 2.0 this is how you get your
        aliases known to Felamimail. 

2) Read entries from subtree and write them below specified place; provide the
necessary information about your DN structure - needed for proper searches and 
for saving new mail properties. Be aware of the mailUserDN attribute which 
holds the relation to user's DN:

            "simplemail":{ 
              "base":"ou=mail,ou=config,dc=example,dc=com", 
              "skeleton":{
                "objectclass":["simplemail","mailrouting"], 
                "mailUserDN":"%s" 
              } 
            }

3) Non-simpleMail-schema exemplified: Tine 2.0 serves the primary domain all 
other mail options are set by a fantasy-admin-tool... 

            "simplemail":{ 
              "base":"ou=postfixAdmin,dc=example,dc=com", 
              "scope":1,
              "skeleton":{
                "objectclass":["postfixAdmin"], 
                "tine20userDN":"%s" 
              },
              "property_mapping":{ 
                "emailAliases":"virtualMailAccount",
                "emailForwards":"forwardMail",
                "emailForwardOnly":"doNotDeliver" 
              },
              "storage_base":"ou=userSettings,ou=postfixAdmin,dc=example,dc=com",
              "storage_rdn:":"cn=mailconfig-%u"
            } 


FURTHER READINGS

- Postfix' special_result_attribute http://www.postfix.org/ldap_table.5.html

- Tine 2.0 cli functions https://wiki.tine20.org/CLI_Functions

Edited 2017-10-22, small changes and typos. 
