Skip to content

10 Advanced Configuration

This chapter describes some more advanced configuration options. Please be aware that you should backup all files you modify because after an update/upgrade of EMM they will be overwritten by default values.

10.1 EMM Configuration

Menu Configuration, sub-menu Change configuration in DB allows you to change certain configuration parameters of the EMM GUI service like file paths, server addresses and limiting values. You should have a look at the list of parameters to understand which parameters can be changed.

In the section of parameters with prefix mailaddress you should define email addresses for support requests by your users and email addresses for certain notification mails. By default, these email addresses are either set to values provided by you in advance or they are set to an invalid sender domain and, therefore, would never leave the EMM server running the GUI service.

Properties with prefix birt define the URLs for the statistics service. Property birt.url is mandatory and should be set to the FQDN of the server running this service + /birt. Property birt.url.intern is the way how the GUI service accesses the statistics service. If both services run on the same server, the value for fastest access is http://localhost:8080/birt. But if the statistics server runs on a different server, it has to be set to the same value as birt.url. (If GUI service and statistics service run on separate servers, make sure that both use the same domain and differ only in their subdomain.)

More parameters can be modified directly in database table company_info_tbl. Some parameters of interest:

  • import.classic.maxRows: limits the max. size of import files for wizard-based import
  • import.recipient.maxRows: limits the max. size of import files for profile-based import
  • import.reference.maxRows: limits the max. size of import files for reference table import
  • recipient.maxRows: limits the maximum amount of recipients in a tenant

Parameters with prefix Max limit certain resources to avoid an overload of the database and parameters with prefix Expire define, after how many days certain entries are deleted from the database to limit the required storage space.

If a certain parameter does not use the value 0 for company_id, it is valid not for all tenants of the EMM instance, but only for the tenant with the company ID defined in database field company_id.

Table config_tbl holds parameters valid for the whole instance of EMM. Some parameters of interest:

  • attachment.maxSize: defines the maximum byte size of a file you may use as attachment for emails
  • linktimeout: timeout in milliseconds for link checker (verifies, if all links in your emails lead to an existing target page)
  • threadcount: maximum number of links that are checked in parallel by the link checker

If the EMM database holds more than 10,000 recipients and you open the recipient list you will be greeted with message The option you selected is too large to be displayed completely. Please limit your selection to reduce the amount of recipients.

If you want more than 10,000 recipients to be processed for the recipient list (which will take longer to display), set field max_recipients in database table company_tbl to the value you want:

UPDATE company_tbl SET max_recipients = 100000 WHERE company_id = 2;
If your EMM installation works with more than one tenant, you may use a different value for company_id (company_id 1 is usually the admin tenant).

To increase security, EMM blocks logins when the same IP address generates a certain number of failed logins. The default value for the maximum number of failed logins is 3 and the default value for the lock out time is 300 seconds. You can change both values in the database in table company_tbl, field max_login_fails and login_block_time. Examples:

UPDATE company_tbl SET max_login_fails = 5 WHERE company_id = 2;
UPDATE company_tbl SET login_block_time = 600 WHERE company_id = 2;
We recommend that you set a HSTS header (HTTP Strict Transport Security) for the responses of the EMM frontend service. This ensures that the browser of the EMM user always uses the secure HTTPS protocol to connect with the frontend of EMM and no longer permit the use of the insecure HTTP protocol.

To activate this header, use this SQL code:

INSERT INTO http_response_headers_tbl (header_name, header_value, overwrite, app_types) VALUES ('Strict-Transport-Security', 'max-age=15768000', 1, 'emm');
the max-age parameter defines the validity period ot this header in seconds. If you replace "emm" with "emm, rdir", the redirect service will be protected with a HSTS header as well.

If a change to the database configuration of EMM does not come into effect within 5 minutes, you have to restart the GUI service.

10.2 High Availability Solution for MariaDB Database

If you want to operate more than one MariaDB DBMS for better availability of the EMM database, you can use a transparent proxy that acts like the DBMS endpoint and offers high availability internally, for instance by using a DBMS cluster.

Alternatively, you can list more than one DBMS endpoint (hostname) in the database access configuration for the Python database driver (backend) and for configuration file context.xml of Tomcat (frontend).

To allow the EMM backend services to be able to access more than one DBMS endpoint, you have to list the endpoints for key host separated by comma without blanks like this

host=mariadb1.domain.com,mariadb2.domain.com
in DBMS configuration file dbcfg.

To allow the EMM frontend services to be able to access more than one DBMS endpoint, the JDBC connection string for attribute url in tag Resource of Tomcat configuration file context.xml can contain more than one hostname separated by comma, like

jdbc:mariadb:sequential://mariadb1.domain.com/emm?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=UTF-8,mariadb2.domain.com/emm?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=UTF-8

See https://mariadb.com/docs/connectors/mariadb-connector-j/failover-and-high-availability-with-mariadb-connector-j-for-2x-driver for more details.

This entry in context.xml is automatically created at EMM startup time based on the endpoint names in file dbcfg.

Please be aware that AGNITAS can not guarantee that this configuration works because we have to rely on software provided by third parties. If you need more information on how to implement a MariaDB-based HA solution for the EMM database, please contact the AGNITAS support team at support@agnitas.com for details.

10.3 Configuration of Webservices 2.0

The powerful webservice interface 2.0 (optional premium feature) runs as a separate web application in directory /home/console/webapps/webservices.

After EMM has been launched you may request the WSDL file for the webservices via URL

http://<domain>/2.0/emmservices.wsdl
To be able to access the new webservices of EMM you have to create a webservice user with a password first. See the user manual for details.

10.4 Configuration of DKIM Keys

EMM supports DKIM keys as an essential standard to improve the deliverability of emails. DKIM key configuration and administration is done by two shell scripts in directory /home/merger/bin of the EMM server running the merger service:

  • dkim-creat lets you create and implement new DKIM keys. Its syntax is
    dkim-creat <domain> <selector> <length> <companyname> <company-ids>
  • dkim-mgr is the core tool to maintain DKIM keys. It is used by dkim-creat

To create a new DKIM key, launch dkim-creat as user merger in your working directory with 5 parameters:

  • the domain for which a DKIM key should be created (<domain>)
  • a selector like "emm" to identify the correct DKIM key (<selector>)
  • the bit length of the key - we recommend 2.048 bits, maximum should be 4.096 bits (<length>)
  • a name for your organisation (<companyname>)
  • one or more comma-separated IDs of the tenants you want to use the DKIM key for example
    $ dkim-creat agnitas.com emm 2048 "AGNITAS AG" 2

dkim-creat generates three files in your current directory: - \@\.pub, containing the public key - \@\.priv, containing the private key - install-<selector>@<domain>.sh, a little shell script to save your private DKIM key in the EMM database

Furthermore, dkim-creat shows the necessary configuration of the DKIM entry with the public DKIM key in the DNS record of your sender domain. Example: 

Creating private/public key pair emm@agnitas.com.priv/emm@agnitas.com.pub for agnitas.com (selector emm) with 2048 bit

Installation sample for your DNS:

emm._domainkey.agnitas.com. IN TXT "v=DKIM1; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtWA2bIcq3n95h7hixhTDdSt2Bjcy209N7OOAHm/81lSY/PbkY7n5x5LELGvMuuOfg7QVChTM5dslDmJ2EHG8TSptZRuOPCw1fW2X3J8zkJK74wLSSVUoKWTYwefp7+WYfoY+XxLzc40DWS1kxYNSvO9KaKxctMYYiKruAtdpnDBuK/tEbTJZBBWH55vwTmXhYbX6L2ZsKIyKjueGfx7RTm3GrVAWRTpBo9krBbM0PL4dP8h3yySr9Hv/WwXk19qeaC0oksVKChiXpc8CCt1gdLWQ5FeqoKnc6LkMkl4th0gPY/voJB6EQA1BC5ZNbpYxgma1UEv1bG37iKV7hJ+LhQIDAQAB"

Creating install-emm@agnitas.com.sh .. add done.

Execute script install-<selector>@<domain>.sh after you have entered your new public DKIM key in the DKIM entry of the DNS record for your sender domain. The script then saves your private DKIM key into the EMM database.

When you start dkim-mgr without parameters it shows you the DKIM key entries in your EMM database in table dkim_key_tbl.

10.5 Mailserver Configuration

The mailservers of EMM are organized into mailersets. By default, only mailerset 0 exists and every tenant defined in field mailerset of database table company_tbl uses this mailerset. Mailersets are defined in table serverset_tbl and their properties are defined in table serverprop_tbl.

If you plan any changes to the configuration of mailservers and/or mailersets in the database, do not do them during times of heavy mail traffic. If you remove mailservers from the database configuration, keep them running for at least another 24 hours to let the configuration changes propagate, to wait for the mail queues being emptied and to let the bounce responses being forwarded to the merger service.

In cases of emergency, you may enforce an immediate propagation of a setup change through restarting process npickup of the merger service:

/home/merger/bin/npickup.sh stop
/home/merger/bin/npickup.sh start

10.6 Configuration of a Smart Relay Server

To improve deliverability of your mailings or for security reasons it may make sense to use a smart relay to send out emails with EMM.

To configure a smart relay for EMM, define in Postfix configuration file main.cf in directory /etc/postfix/ line

relayhost = [192.168.0.1]
where 192.168.0.1 is an example for the IP address of your smart relay server. You may also use the FQDN of your smart relay server instead of its IP address.

You should define this configuration for every server that runs a mailer service. Usually this also includes servers running frontend services.

Please make sure that port 25 is open on your smart relay server and be advised that a smart relay complicates bounce management, especially if the MX entry of the DNS record for your sender domain does not point to your smart relay.

To make sure that the smart relay reports bounces back to EMM, you should define a forwarding configuration for the Postfix service on the smart relay server so that incoming bounces are forwarded to EMM. If the smart relay uses Postfix, we recommend a file mail-transport in directory /etc/postfix/ with this content:

news@domain1.com          reply_1@mailloop.domain.com
news@domain2.com          reply_2@mailloop.domain.com
news@domain3.com          reply_3@mailloop.domain.com
In this example the left side shows the sender addresses you use for your emails and the right side shows the filter addresses created by EMM (in GUI menu Response Processing).

In Postfix configuration file main.cf in directory /etc/postfix/ add these two lines:

relay_domains = domain1.com, domain2.com, domain3.com
virtual_mailbox_maps = hash:/etc/postfix/mail-transport
to make sure that the map in file mail-transport is processed by Postfix.

Activate this new forwarding configuration with

postmap /etc/postfix/mail-transport
systemctl reload postfix

10.7 Configuration Issues when Migration to a new Platform

If you want to migrate EMM to a new platform with (partly) different host names of servers, we recommend to check the following configuration issues: