5 EMM Deployment
5.1 Default Directory Structure
EMM uses a default directory structure noted as following* (replace <user> with the user name of the respective service):
| Backend Server | Directory Description |
|---|---|
| /home/<user>/bin/ | symbolic link to release/current/bin/ |
| /home/<user>/log/ | log files for automated processing by backend services |
| /home/<user>/release/ | directory of service releases |
| /home/<user>/release/current/ | symbolic link to active release |
| /home/<user>/scripts/ | symbolic link to release/current/scripts/ |
| /home/<user>/var/lock/ | file locks |
| /home/<user>/var/log/ | log files of backend services |
| /home/<user>/var/run/ | runtime files |
| /home/<user>/var/spool/postfix/ | spool files for mail processing by Postfix |
| /home/<user>/var/tmp/ | storage for temporary files |
| Frontend Server (with mailer service) | Directory Description |
|---|---|
| /home/<user>/bin/ | symbolic links to backend service scripts in release/backend/current/bin/ |
| /home/<user>/bin/emm.sh | symbolic link to tomcat/bin/emm.sh |
| /home/<user>/conf/ | symbolic link to tomcat/conf/ |
| /home/<user>/logs/ | Symbolic link to tomcat/logs/ |
| /home/<user>/release/ | releases of frontend services |
| /home/<user>/release/emm/ | directory of GUI service releases |
| /home/<user>/release/backend/ | directory of releases of mailer services |
| /home/<user>/release/backend/current/ | symbolic link to active release of mailer service |
| /home/<user>/release/manual/ | directory of user documentation |
| /home/<user>/release/rdir/ | directory of redirect service releases |
| /home/<user>/release/runtime/ | directory of releases of runtime files |
| /home/<user>/release/statistics/ | directory of releases of statistics services |
| /home/<user>/release/webservices/ | directory of releases of webservice API 2.0 |
| /home/<user>/scripts/ | symbolic link to release/backend/current/scripts/ |
| /home/<user>/tomcat/bin/ | Frontend startup and maintenance scripts |
| /home/<user>/tomcat/conf/ | Tomcat configuration files |
| /home/<user>/tomcat/lib/ | JAR libraries for database connections |
| /home/<user>/tomcat/logs/ | log files of frontend services |
| /home/<user>/var/lock/ | file locks |
| /home/<user>/var/log/ | log files of mailer service |
| /home/<user>/var/run/ | runtime files |
| /home/<user>/var/spool/postfix/ | spool files for mail processing by Postfix |
| /home/<user>/webapps/ | EMM services used by Tomcat |
| /home/<user>/webapps/emm/ | symbolic link to active release of GUI service |
| /home/<user>/webapps/manual/ | symbolic links to active user documentation |
| /home/<user>/webapps/rdir-iso/ | symbolic link to active release of ISO-8859-15 redirect service |
| /home/<user>/webapps/rdir-utf/ | symbolic link to active release of UTF-8 redirect service |
| /home/<user>/webapps/statistics/ | symbolic link to active release of statistics service |
| /home/<user>/webapps/webservices/ | symbolic link to active release of webservice API 2 |
* only major directories of the directory tree are shown
Depending on the combination of services on a certain server not all these directories have to exist on the same server.
5.2 Configuration files
Copy global distribution file backend-runtime-<release>.tar.gz to the home directory of user root on all servers running EMM services, unpack it and create required symbolic links:
mkdir -p /root/release
cd /root/release
tar xzpf ~/backend-runtime-<release>.tar.gz -C /root/release
ln -s V<release> /root/release/current
cd ..
ln -s release/current/bin /root
ln -s release/current/scripts/ /root
This installs the EMM Support Tool EST, the global EMM startup script agnitas.sh and its systemd configuration agnitas.service. Script agnitas.sh checks if all necessary directories and symbolic links exist and creates them if they are missing. It also checks if certain files have the required permissions and it makes sure that needed third party tools are available and accessible. Finally, it starts (or stops) all available EMM services on the server in the correct sequence.
If you want to start all EMM services automatically at boot time, you should link file agnitas.service in directory /etc/systemd/system/:
To finish this setup, you have to reload the systemd daemon to enable agnitas.service:
Configuration file system.cfg contains important initial data for your configuration like database connection parameters, hostnames, domain names, port addresses, public keys and your license ID. Since this file contains all information specific to your setup, it is separately provided by AGNITAS after the individual peculiarities of your EMM Inhouse installation have been clarified.
Copy your configuration file system.cfg on all servers running EMM services into directory /opt/agnitas.com/etc/ and make sure this file is readable by all users of the server with
5.3 Backend Deployment
Copy server-specific distribution file backend-<service>-<release>.tar.gz to the root directory of the server requiring the specified service. A typical installation consists of these 4 files:
- backend-merger-<release>.tar.gz (merger service)
- backend-mailer-<release>.tar.gz (mailer service)
- backend-mailloop-<release>.tar.gz (mailloop service)
- backend-console-<release>.tar.gz (backend utilities for frontend services)
- backend-rdir-<release>.tar.gz (backend utilities for redirect service)
5.3.1 Backend Default Deployment
To unpack the distribution files for all services (except for any backend service on EMM servers or redirect services) use the commands below, but
- replace <user> with the real user name (merger, mailout or mailloop)
- replace <service> with the name of the service (merger, mailer or mailloop)
- replace <release> with the number of your release
Always enter as user root (if not done already before as described in section Miscellaneous):
With SLES you have to remove the auto-generated sub directory bin in the directory of user <user> because it will be later replaced by a symlink:
After that, continue with
cd /home/<user>
[ -d release ] || mkdir release; chown <user>. release
cd release
tar xzpf ~/backend-<service>-<release>.tar.gz
rm -f current
ln -s V<release> current
chown -h <user>. current
cd ..
ln -s release/current/* .
chown -h <user>. *
The advantage of using symbolic links is that you only have to change the symlink back to the old release if there are any problems with the new one.
5.3.2 Deployment of Backend Utilities for Frontend + Redirect Services (User console / rdir)
To install the backend utilities for users console and rdir use these commands (if not done already before as described in section Miscellaneous):
After that, continue with
chmod g+x /home/<user>
cd /home/<user>
[ -d bin ] || mkdir bin; chown <user>. bin
[ -d release ] || mkdir release; chown <user>. release
[ -d release/backend ] || mkdir release/backend; chown <user>. release/backend
cd release/backend
Depending on your user:
or
rm -f current
ln -s V<release> current
chown -h <user>. current
cd ../..
ln -s release/backend/current/scripts .
chown -h <user>. scripts
cd bin
ln -s ../release/backend/current/bin/* .
The backend utilities allow you to create mail previews, among other things.
Do not forget to add read access for file dbcfg for the new users as mentioned at the end of section Database Connection Configuration.
5.3.3 Deployment of Mailer Service with Frontend + Redirect Services (User console / rdir)
There is another optional backend feature called direct-path for the servers running GUI and redirect services. This feature enables servers running a GUI or redirect service to send action-based mails directly without a time-consuming rerouting via merger and mailer services running on separate servers. This can be especially useful for time-critical mails like double opt-in confirmation mails. Since this feature is provided by the mailer service of EMM, you have to install the mailer service on the same server in case you want to use it. (For instructions on how to install this backend service, please see section [Backend Default Deployment] (#531-backend-default-deployment) above.)
If you install the mailer service on a frontend or redirect server, you also have to open port 25 for SMTP feedback to sent mails:
If the server running a frontend or redirect service provides sufficient hardware resources and if a mailer service is installed on the server, the direct-path feature can be enabled by setting
in file system.cfg in directory /opt/agnitas.com/etc/.
Note for installations with all frontend services running on the same server: In this case you do not need user rdir and you only have to install backend services for user console.
5.3.4 Additional Deployment for Merger Service
For the merger service make sure that user merger has permission to read the mail log at /var/log/maillog and that logrotate holds the same permission.
5.3.5 Additional Configuration for Servers with Mailer Service
Current versions of RHEL and SLES provide a "feature" that drops messages from being logged if the server has a high workload. If you use the default configuration values of RHEL or SLES (i.e. 1,000 entries max. within 30 seconds), and if the servers running a mailer service have a high workload due to a high mail output (or other EMM services running on the same server as well), this can lead to missing entries in the maillog. However, missing entries in the maillog mean that EMM does not know whether mails were delivered successfully, or not and may lead to an incomplete bounce management and incomplete statistics!
To make sure that even under high workload all messages are logged to the maillog, we recommend to change (or add) the following values of file journald.conf in directory /etc/systemd/:
Afterwards, restart the journal daemon with
to activate your changes.
SLES:
Additionally, add (or change) the following values in file rsyslog.conf of directory /etc after the line with parameter $IMJournalStateFile imjournal.state:
RHEL 8:
Additionally, replace in file rsyslog.conf of directory /etc/ the lines
module(load="imjournal" # provides access to the systemd journal
StateFile="imjournal.state") # File to store the position in the journal
with single line
module(load="imjournal" StateFile="imjournal.state" WorkAroundJournalBug="on" ratelimit.interval="10" ratelimit.burst="20000")
RHEL + SLES:
Afterwards, restart the rsyslog service to activate your changes:
5.4 Frontend Deployment
Copy server-specific distribution file frontend-<service>-<release>.tar.gz to the home directory of user console or rdir on the server requiring the specified service. A typical installation consists of these 4 files:
- frontend-emm-<release>.tar.gz
- frontend-statistics-<release>.tar.gz
- frontend-rdir-utf-<release>.tar.gz
- frontend-webservices-<release>.tar.gz (optional)
(Note: If you run the GUI service and the statistics service on separate servers, make sure that both use the same domain and differ only in their subdomain. Reason for this requirement is, that communications between GUI service and statistics service require Cookies and web browser have started to block those, if domains differ.)
To unpack and activate the distribution files for all users, use the commands below, but
- replace <user> with the user name of the service (console or rdir)
- replace <service> with the name of the service (GUI service: emm, statistics service: statistics, redirect service: rdir, webservices 2.0: webservices)
- replace <release> with the number of your release
Always enter as user root and omit the first 2 lines in case group and user have already been created by the instructions in section Deployment of Backend Utilities for Frontend + Redirect Services (User console / rdir):
After that, continue with
su - <user>
[ -d bin ] || mkdir bin; chown <user>. bin
[ -d release ] || mkdir release/<service>; chown <user>. release
cd release/<service>
tar xzpf ~/frontend-<service>-<release>.tar.gz
cd ../../webapps
For GUI service (emm) continue with:
For webservices 2.0 (webservices) continue with:
For statistics service (statistics) continue with:
For redirect service (rdir) continue with:
Note for installations with all frontend services running on the same server: In this case you do not need user rdir and you do not have to install the redirect service!
Warning: If you have installed frontend services before the corresponding backend services (see section Deployment of Backend Utilities for Frontend + Redirect Services (User console / rdir) and section Deployment of Mailer Service with Frontend + Redirect Services (User console / rdir) for details), do not start the frontend services. In case you did, install the backend services and manually start setup script sanity.sh in directory /home/console/bin/ or /home/rdir/bin/ with parameter console or rdir to create any missing working directories.
Do not forget to add read access for file dbcfg for the new users as mentioned at the end of section Database Connection Configuration.
5.4.1 Additional Deployment for GUI Service
If you want EMM to render good-looking thumbnail images and PDF documents in the EMM GUI, the EMM server running the GUI service needs the installation of some more packages:
RHEL:
dnf install gcc-c++ mesa-libgbm atk at-spi2-atk libXcomposite libXdamage libXrandr libXrender libxkbcommon pango
dnf module reset nodejs
dnf module enable nodejs:20
dnf install nodejs
SLES:
zypper install gcc-c++ libgbm1 libgbm-devel
SUSEConnect -p sle-module-web-scripting/15.4/x86_64
zypper install nodejs18
Finally, switch to user console, change to directory /home/console/webapps/emm/WEB-INF/ and install the NPM package puppeteer via port 443 (HTTPS) from the NPM server (operated by GitHub/Microsoft):
This means, that the server running the EMM GUI needs access to the Internet during deployment. If your server does not permit outbound access via port 443, please contact the AGNITAS support team at support@agnitas.com and we will provide you with the node package files which are required at runtime for directories /home/console/.cache/puppeteer and /home/console/webapps/emm/WEB-INF/node_modules.
Furthermore, puppeteer must be able to access the browser frontend of EMM from localhost. Therefore, make sure that your firewall rules do not block access of port 80 (HTTP) or 443 (HTTPS) from localhost.
5.4.2 Runtime Configuration
For frontend services we provide an additional runtime tarball each with file name frontend-runtime-<release>.tar.gz. Change to the user of the service and unpack the tarball in the user's home directory:
The tarballs provide license-specific files for home sub-directories
- tomcat/bin/: startup script emm.sh, its optional property file emm.sh.additional.properties and cleanup script tempcleaner.sh for the temp directory
- tomcat/conf/: various Tomcat configuration files like server.xml, context.xml.template and logging.properties as well as – depending on the service - server key files (*.key, *.pem), server certificate files (*.crt, cacerts) and a salt file (*.salt).
- tomcat/lib/: JAR libraries for database connections (Derby and MariaDB or Oracle DBMS)
To make sure that EMM startup script emm.sh can always be found without entering its path, create the following symlink in the bin directory of each frontend service:
5.4.3 EST (EMM Support Tool)
The runtime tarballs contain the interactive command line tool EST (EMM Support Tool) which should be your preferred way to check, configure and update various components of EMM. Simply start the tool with
(If you want to use EST on a server running a different EMM service, replace console with the name of this service.)
At launch time the top level menu is shown:
Current menu: Main
Please choose (Blank => Quit):
1. Show EMM status
2. Configuration
3. Database Maintenance
4. Security
5. Install or update package from AGNITAS Website
6. Install or update package from local file
7. Install or update package from AGNITAS Cloud
8. Show update history
9. Switch EMM version
10. Restart EMM
11. Send configuration and log files in email
0. Quit
>
Menu Show EMM status starts a brief health check of the EMM configuration on the current server and checks the integrity of the files via their checksums.
Menu Configuration offers various sub-menus which help you to check, change or create certain settings of your EMM configuration without having to deal directly with the EMM database or configuration files:
Current menu: Configuration
Please choose (Blank => Back to Main):
1. Configure basic environment (Java, Tomcat, Proxy)
2. Change configuration of database connection
3. Change basic configuration
4. Change system.cfg
5. Change layout images
6. Change client/account configuration
7. Change jobqueue configuration
8. Change default redirect homepage url
0. Back to Main
>
Sub-Menu Change configuration of database connection helps you to set up the configuration file as described in section Database Connection ConfigurationDatabase Connection Configuration.
Sub-menu Change basic configuration offers you to define the (important) domain names for various EMM services:
| EMM Service | Name of Parameter |
|---|---|
| GUI Service | system.url |
| Mailloop Service | system.defaultMailloopDomain |
| Redirect Service | system.defaultRdirDomain |
| Statistics Service | birt.url |
| Webservices | webservices.url |
You should also configure various email addresses for mails from EMM and notifications:
| Name of Parameter | Description |
|---|---|
| mailaddress.sender | sender address for all frontend emails (like reports), also used for 2FA and error mails |
| mailaddress.replyto | reply-to address for all frontend emails (like reports), also used for 2FA and error mails |
| mailaddress.bounce | bounce address for all frontend emails (like reports), also used for 2FA and error mails (optional) |
| mailaddress.info.cleaner | email address that gets notifications if a nightly DB cleaning process did not finish in time |
| mailaddress.error | email address for EMM error notifications like DB connection error |
| mailaddress.frontend | email address that gets notifications for user form errors and for action script errors |
| mailaddress.upload.database | email address that gets notifications that a new file was uploaded in the upload menu |
| mailaddress.upload.support | email address that gets any instructions included in a file upload |
| mailaddress.report_archive | email address that gets report mails to be archived |
| mailaddress.support | email adress that gets messages sent via button "report a problem" |
| mailaddress.feature_support | email adress that gets messages sent via button "suggest a feature" |
Sub-menu Change system.cfg offers you to change individual backend settings of your EMM installation. You should only change those values if you know what are you doing!
Sub-menu Change layout images offers you the possibility to change the logos of EMM for white-labeling. Just enter the file name of the logo you want to change and enter path and file name of the replacement:
favicon.ico (the icon often displayed in the browsers tab besides the title)
logo.svg (small logo in the webapplication above the menu and login mask)
logo.png (an alternative to the SVG logo)
edition_logo.png (logo in login mask)
report_logo.png (logo used inside pdf reports)
Please choose layout image to replace (Blank => Back):
> logo.svg
Please enter new image filepath for replacement of 'logo.svg':
> /home/user/image.png
Sub-menu Change client/account configuration offers you to change the domain names for the mailloop service and redirect service for each tenant separately (in case you have a multi-tenant license of EMM). Also, you should define an email address for property contact_tech, because OpenEMM will send certain warnings to this email address.
With sub-menu Change default redirect homepage url you can define for every redirect domain which web page is called if the recirect domain is used without further parameters.
Menu Database Maintenance offers a backup and restore of the database if a MariaDB type of EMM database is present on the server. Also, sub-menu Delete Companies with status todelete offers you to finally delete a tenant which is marked as "to be deleted". This option is needed, because as a safeguard measure when an EMM user deletes a tenant in the GUI of EMM, the tenant is no longer shown and marked as "to be deleted", but its data still exist for recovery reasons. To comply with the requirements of the EU GDPR it is advisable to finally delete a tenant after a safety period.
With menu Security you can set a new password for admin user emm-master if you select option Create new initial 'emm-master' password. You may use this option also in case you have forgotten the password for user emm-master of the master tenant.
Use sub-menu Install license file if you upgraded EMM to a new major version, because it will need a new license file. (Download the license file via your individual license link. If the link is lost, please contact the AGNITAS support team at support@agnitas.com.)
Also, you can use option Configure TLS certificate (https) to customize Tomcat's configuration file server.xml with your TLS certificate files so that EMM can be accessed by the HTTPS protocol.
Menus Install or update package from ... supports you in downloading packages of a new EMM release from various sources. Please be aware that you have to start EST as user root to be able to install or update any backend service. If you want to load a file from an external source (AGNITAS), make sure that the server EST is running on, is able to access this source. Otherwise download the file first with a different device, copy it to your server and install it as local file.
If you need to know which services and versions of EMM were active at what time in the past, menu Show update history provides a list of all available services, their versions and the exact startup times.
Menu Switch EMM version lets you roll back to a former version of an EMM service or roll forward to a later version. However, if you switch back not to an older patch level (last 3 digits of the version number), but to an older minor or major version (like going back from 20.10 to 20.04), please be advised that the database schema is not rolled back and, therefore, some feature may not work properly because it wants to use a database field that does not exist any longer in the new database schema.
After a change of version or after an EMM service update, use menu Restart EMM to restart the EMM installation on the current server (frontend and backend services, if available).
Menu Send configuration and log files in email helps you to create an email which sends all important EMM configuration information to an email address of your choice for diagnostic purposes or as a backup. For that reason, the tool collects certain configuration and log files from the current server as well as the content of database configuration tables of your EMM installation (if the database is accessable from the server) and sends them out as zipped and password-protected attachment. Since this attachment can become quite big, make sure that the receiving email address (if it is not AGNITAS) is able to handle this payload.
If EST reports an error during operation, re-start EST with option -debug and repeat the operation. In this case EST will show a stacktrace for the error, which may give you a hint what went wrong. If this does not help, please contact the AGNITAS support team at support@agnitas.com.
5.4.4 Documentation Deployment
For the deployment of the EMM user documentation we provide a tarball with file name EMM_Manual_<release>.tar.gz. This tarball contains the user manual as PDF file, the developer manual for the EMM webservices as PDF file and HTML files for the context-sensitive online help. This tarball is either offered by EST in menu Install or update package from AGNITAS Website or it can be manually deployed on the server running the GUI service as user console:
To activate the new release of the documentation, please change the symbolic links in directory /home/console/webapps/manual/ to the directory of the new documentation.