Installation:InstallGuideSUSE

From OpenEMM Wiki

Jump to: navigation, search

Contents



AGNITAS OpenEMM

Install and Administration Guide

Suse and OpenSuse Linux distributions


This document is a guidance through the installation process of OpenEMM. It requires a basic knowledge of Linux System Administration and (in case you need it) of Domain Name Services (DNS). The command-line examples are based on SuSE Linux.

[edit]
How to use this document

Below you will find a short description/overview of OpenEMM, the first professional e-mail marketing solution released as an Open Source. Following the description, this document will guide you through some nessessary steps, which are needed to run OpenEMM smoothly.

[edit]
Technical Overview of OpenEMM

OpenEMM is feature-rich enterprise software for e-mail marketing and mainly written in Java and Python. OpenEMM employs leading edge Java frameworks like Hibernate, Spring and Struts. Some performance-sensitive code is written in C. OpenEMM runs on top of a well proven Open Source software stack: Linux, MySQL, Sendmail and a web container like Resin (included in OpenEMM RPM and tarball) or Tomcat.

Requirements

Installation Steps

[edit]

Operating System

[edit]

Operating System: Updates

(run as superuser)

Update the Operating System to its latest release. This will keep your system at the most stable state and harding it against various intrusion attempts.

yast->Software->Online Update

[edit]

Operating System: Package Installation

(run as superuser)

Install the required packages. Further depencies will be resolved automatically by the installation programm.

yast -i mysql python-mysql sendmail

If package python-mysql is not available in OpenSuse, it is probably not needed.

[edit]

Operating System: Create the ’openemm’ User

(run as superuser)

Create a special user for OpenEMM. The default directory ’/home/openemm’ will be used by the OpenEMM software. OpenEMM runs completely under the permission of that user. Only the Sendmail part, which requires the root TCP port 25, will be run with superuser permissions. OpenEMM’s userspace concept adds more safety to your server and its services.

groupadd openemm

useradd -m -g openemm -d /home/openemm -c "OpenEMM 5.1.x" openemm

[edit]

Installation: Sun Java JDK

(run as superuser)

OpenEMM's Java Engine requires the installation of Sun's Java Development Kit (JDK). Currently, the license politics of Sun do not allow adding the JDK to our archives, a fact which should be resolved soon, since Sun is working on a new way to license its Java products.


1.) Receive the latest Sun JDK 5 from

http://java.sun.com/javase/downloads/index_jdk5.jsp ->JDK 5.0 Update 12

preferable the 'jdk-1_5_0_12-linux-i586.bin' package (or newer).


2.) Copy the file to ‘/tmp’ directory:

cp jdk-1_5_0_12-linux-i586.bin /tmp


3.) CD to the '/tmp' directory:

cd /tmp


4.) Give the file an execution permission:

chmod u+x jdk-1_5_0_12-linux-i586.bin


5.) Execute the file

./jdk-1_5_0_12-linux-i586.bin

follow the onscreen instructions and confirm the license agreement.


6.) Create a directory:

mkdir -p /opt/openemm.org/software


7.) Move the JDK-directory:

mv jdk1.5.0_12 /opt/openemm.org/software


8.) Change to that directory:

cd /opt/openemm.org/software


9.) Create a symbolic link for the JDK:

ln -s jdk1.5.0_12 java


10.) Test the JDK: /opt/openemm.org/software/java/bin/java -version


You should get an output like this:

---console output---

java version "1.5.0_12"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_12)

Java HotSpot(TM) Client VM (build 1.5.0_11-2, mixed mode, sharing)

---console output---



NOTE: If you want to use an existing JDK, simple edit '/home/openemm/.bash_profile' after the installation of the OpenEMMRPM/ Tarball and adjust the JAVA_HOME variable. Currently, only Sun JDK 5 is supported by OpenEMM. Sun JDK 6 has not been tested yet.

[edit]

Enable OpenEMM access in the iptables-Firewall

(run as superuser)

Use Yast to add permission for HTTP and SMTP:

yast -> Security and Users -> Firewall -> Allowed Services

select ’HTTP Server’ and ’Mail Server’. After that add permission for port 8080 and 8081:

-> Advance -> Settings for Zone: External Zone -> TCP Ports: 8080 8081

[edit]

Domain and Hostname

[edit]

What is a DNS entry and what is the purpose?

A DNS-Entry replaces the IP address of the server with a human readable address. You clients will only see the specified DNS-Address if they click on a link. Example: In place of the IP address 172.16.13.52, which results in a webpage, you will see the DNS address like http://www.yourcompany.com.

[edit]

What is a Hostname, a Domain and a FQHN?

A Fully Qualified Domain Name (FQDN) links to an IP address of a server. The Internet address may be composed of letters and numbers, by using this option nobody has to remember the difficult number sequence (IP).


A FQDN is divided in three levels:

1) The appendage of the domain is the Top Level Domain (TLD). Example: net, com or eu

2) The domain name will be inserted in front of the TLD. Example: openemm or agnitas

3) At the very first stands the hostname. For webpages mostly: www Example:

The FQDN www.yourcompany.com is composed of:

- www = hostname

- yourcompany = domain name

- com = TLD


As you can see, the FQDN consists of the hostname, the domain and the top level domain separated by dots. Finally the server IP address (i.e. 172.16.13.52) will be replaced by the addressable www.yourcompany.com address. The FQDN can be expanded with a subdomain (i.e. miami). The subdomain will be inserted between the hostname and the domain name. Example:

www.miami.yourcompany.com


[edit]

How do I get a Domain and a FQHN?

There a lot of providers where you may host a domain. You will only host the combination of the TLD and the domain name. Example: yourcompany.com.

You may link a domain to different targets by using different hostnames. Example: www.yourcompany.com (webpage) and mail.yourcompany.com (OpenEMM-Mailserver). The domain will be registered in a Domain Name Server (DNS). This server forwards all requests to the particular IP address. After a domain has been reserved, you may set up the FQDN in the providers web interface. The provider allows you to define several hostnames to get different FQDNs, which will forward to different servers. You may set up different addresses like

- e-mail server: mail.yourcompany.com

- FTP server: ftp.yourcompany.com

- web server: www.yourcompany.com etc.

[edit]

Domain Name Service (DNS) Configuration

[edit]

Redirect services

Basically, OpenEMM runs out of the box. It just requires a simple FQDN, which is usually already mapped to an available IP-address by your ISP. You can use that FQDN for the redirection services, provided by OpenEMM.

Example: Your machines hostname is

www.openemm.org


In that case simply add that FQDN, as shown in the section 'Initialize the MySQL Database' below. It would look like

http://www.openemm.org:8080


since the redirection services of OpenEMM usually uses port 8080. If you use port 8080, do not forget to include it in external links pointing to OpenEMM (like subscribe links in forms on your website). Hint: You can map that port to another port - see Appendix for further details.


[edit]

Bounce Management

[edit]

What is the bounce management?

The bounce management provides you with the capability to keep your mailinglists clean and up-to-date automatically. A bounce message is an error message, which will be send from a mailserver of the recipient to the sender automatically, if an E-Mail is not deliverable. The bounce management governs the enduring and passing E-Mails which are undeliverable. It also filters the error messages and autoresponder mails.

Setting up the bounce management of OpenEMM is not necessary, since bounce management for bounces received during the send process (instant bounces) works out of the box. But if OpenEMM should even process bounces (and autoresponder mails) which are received hours or even days later (which is quite often the case) you have to do some setup.


[edit]

Setting up a bounce management for delayed bounces

If you want to use the bounce management for delayed bounces you need to define a dedicated sender hostname for OpenEMM which is different from the existing host name of the server and you have to set up a A record and a MX (Mail Exchanger)record in your Domain Name Server (DNS) for the sender hostname. The MX record is used to route mail for a domain to one or more IP addresses. Sendmail needs the new (virtual) host as a destination, to forward all incoming response to, for further processing by OpenEMM.

In our example the regular hostname is ‘host’ and the sender hostname for OpenEMM will be ‘news’.

The (abbreviated) DNS entry looks like this:

---Domain: openemm.org--- 86400 IN A 0 83.220.154.85

host 86400 IN A 10 83.220.154.85

news 86400 IN A 10 83.220.154.85

news.openemm.org. 86400 IN MX 10 host.openemm.org.

---Domain: openemm.org---


The first line assigns the IP address for openemm.org and the second line defines the regular hostname. The third and fourth line define the A record and MX record for sender hostname ‘news’, meaning that host ‘host’ accepts e-mails sent to host ‘news’.

Validate your correct setup by using a tool like ‘host’ or ‘dig’, for example host –a openemm.org host –a host.openemm.org host –a news.openemm.org

When you send e-mails and want to take advantage of the bounce management for delayed bounces there are two possibilities for the format of the sender address:


A.) Use whatever address you like. Set up a bounce filter in OpenEMM (see user manual) to foward the filtered response to a feedback e-mail address of your choice (different from the sender address, of course). Implement a forward mechanism to forward incoming mail sent back to the sender address to the email address generated by the bounce filter (in our example ext_1@news.openemm.org). The flow for responses of your e-mails works like this:

sender address -> filter-generated address (to filter out bounces) -> feedback address


B.) Use an e-mail address with the sender hostname (in our example news@news.openemm.org) Since no real e-mail addresses exist for the sender hostname, normally it would not be possible to reply to an e-mail with this ender address. To forward responses to a valid e-mail address you have to define a bounce filter with an e-mail feedback address of your choice. The e-mail address generated by the bounce filter (in our example ext_1@news.openemm.org) has to be defined as an alias in directory /home/openemm/conf/bav in a new file named bav.conf-local. Our example:

---File: /home/openemm/conf/bav/bav.conf-local----

news@news.openemm.org alias:ext_1@news.openemm.org

---File: /home/openemm/conf/bav/bav.conf-local ----

The flow for responses of your e-mails works like this:

sender address -> bav.conf-local -> filter-generated address -> feedback address

[edit]

Configuration Changes - Sendmail

(run as superuser)

To use the dynamic bounce management system of OpenEMM, some modifications are required by the superuser:

      • WARNING: Editing the files mentioned below breaks the YaST

configuration capabilities for sendmail. However, you can later re-activate YaST via MAIL_CREATE_CONFIG="yes" and YaST will not overwrite your sendmail configuration but save the new file as sendmail.cf.<name> so that you can compare the settings (with diff). If the changes are too many to copy them manually into the existing sendmail.cf, rename the new file to sendmail.cf, run /sbin/SuSEconfig and repeat the steps in this section.***

---File: /etc/sysconfig/mail---

Change the line:

MAIL_CREATE_CONFIG="yes"

to:

MAIL_CREATE_CONFIG="no"

---File: /etc/sysconfig/mail---

This line excludes Yast from sendmail configuration and allows you to change the configuration manually by yourself.


---File: /etc/mail/linux.mc---

Edit the line:

dnl undefine(`confHOST_STATUS_DIRECTORY')dnl

to:

undefine(`confHOST_STATUS_DIRECTORY')dnl

Append the following line at the end of the file:

INPUT_MAIL_FILTER(`bav',`S=unix:/home/openemm/var/run/bav.sock,F=T')dnl

---File: /etc/mail/linux.mc---


---File: /etc/mail/relay-domains---

Add a line at the end of the file, which specifies your DNS entry for the senderhostname (FQDN). In our example it is simply:

news.openemm.org

---File: /etc/mail/relay-domains---


---File: /etc/mail/mailertable---

Add a line at the end of the file, which activates the bounce management for that FQDN:

news.openemm.org procmail:/home/openemm/conf/bav/bav.rc

---File: /etc/mail/mailertable---


To activate your changes, run the following commands as superuser: cd /etc/mail

m4 linux.mc > /etc/sendmail.cf

m4 linux.submit.mc > submit.mc

make

/etc/init.d/sendmail restart

You may ignore the warning that /home/openemm/var/run/bav.sock is missing, since this file will be provided with the next step.

IMPORTANT: If you use AppArmor with SuSE it requires the following entries for the file /etc/apparmor.d/usr.sbin.sendmail. Otherwise, Sendmail will not be able to communicate with OpenEMM.

---File: /etc/apparmor.d/usr.sbin.sendmail---

/home/openemm/var/spool/ADMIN rwl,

/home/openemm/var/spool/ADMIN/* rwl,

/home/openemm/var/spool/QUEUE rwl,

/home/openemm/var/spool/QUEUE/* rwl,

---File: /etc/apparmor.d/usr.sbin.sendmail---

Finally, restart the AppArmor Service by

/etc/init.d/boot.apparmor reload

[edit]

Install OpenEMM 5.1.x.y

(run as superuser)

Get the latest version of the OpenEMM binary code from

http://www.sourceforge.net/projects/openemm

Your choice is a simple tarball for all non-RedHat compatible Linux systems.

Copy the Tarball to a temporary location, /tmp is a good choice.

Change into that directory and run the following commands as superuser:

cd /home/openemm

tar xzvf /tmp/OpenEMM-5.1.x.y.binary.tar.gz

chown -R openemm:openemm .bash* *

chown root:root bin/smctrl

chown root:root conf/bav/bav.rc

chmod 6755 bin/smctrl

chmod 0600 conf/bav/bav.rc

mkdir -p /usr/share/doc/OpenEMM-5.1.x.y

mv USR_SHARE/* /usr/share/doc/OpenEMM-5.1.x.y

The installation process fills the directory ’/home/openemm’ of the user ’openemm’ and also creates a directory including this document and various others at ’/usr/share/doc/OpenEMM-5.0.x.y’.

The tarball was tested with Suse 9.3 and openSuSE 10.0.

[edit]

Read Access to Maillog

OpenEMM requires read access to ’/var/log/maillog’.

(run as superuser)

---File: /etc/syslog-ng/syslog-ng.conf.in---

Change the line:

options { long_hostnames(off); sync(0); perm(0640); stats(3600); };

to:

options { long_hostnames(off); sync(0); perm(0644); stats(3600); };

Change the line:

destination mail { file("/var/log/mail"); };

to:

destination mail { file("/var/log/maillog"); };

---File: /etc/syslog-ng/syslog-ng.conf.in---

Finally, activate the changes with

/sbin/SuSEconfig

as superuser.

[edit]

Initialize the MySQL Database

(run as superuser)

Make sure that MySQL is running. This is done by:

/etc/init.d/mysql restart

Now you have three options:

A.) In case you want to setup the OpenEMM database from scratch, use the following commands:

cd /usr/share/doc/OpenEMM-5.1.x.y

mysqladmin -u root -p create openemm

(omit option –p in case your MySQL system is not password protected)

If you plan to use the redirect features of OpenEMM, open the file 'openemm.sql' with a text editor like edit or vim, and find and replace the string

http://localhost:8080

with a valid redirection URL. In our example it is

http://www.openemm.org:8080

If you plan to use the bounce management for delayed bounces, replace the empty mailloop string ' ' after the redirection URL you just entered in the step before with the sender hostname (see bounce management section). In our example it is

news.openemm.org

The sender hostname will be used as domain name for the forward addresses generated by the bounce filter.

Finally, load the database layout by

mysql -u root -p openemm <openemm.sql

B.) In case your old OpenEMM database is somehow lost but you made a backup file openemm.db from a former installation (see 7 Uninstallation), import the database by

mysql –u root openemm < /home/openemm/openemm.db

But you may have to update the database schema. Therefore, please read the next paragraph too.

C.) If you used OpenEMM before and an OpenEMM database already exists, you might have to update your database schema to add new tables and/or columns. Change to directory ‘/usr/share/doc/OpenEMM-5.x.y’ and look for files with names like ‘update_openemm-5.n.m-5.x.y.sql’. To update your database to the latest version you have to apply some or all of this files (depending on the former OpenEMM version you used) in the right sequence to your database. This is done by the (generic) command:

mysql -u root -p openemm < update_openemm-5.n.m-5.x.y.sql

To give you an example: If you want to update from OpenEMM 5.0.3 to 5.3.0 you have to run the following two commands in exactly that sequence:

mysql -u root -p openemm < update_openemm-5.0.3-5.1.0.sql

mysql -u root -p openemm < update_openemm-5.1.0-5.3.0.sql

[edit]

Start OpenEMM

(run as superuser)

Become the user ’openemm’ by running

su – openemm

To start the OpenEMM enviroment, run

OpenEMM.sh start

To stop OpenEMM

OpenEMM.sh stop

Point your webbrowser to

http://www.openemm.org:8081

(insert your own Console URL here) and log into OpenEMM as


Username: admin

Password: openemm


OpenEMM detects the language setting of your webbrowser and shows the appropiate login page. Obviously, your first step should be to change the password ’openemm’ in the Settings menu to a new password.

By default, the menus of OpenEMM are shown in English. To change to German language, click on menu "Settings" and choose submenu "User". Select user "admin" and change the language field from English to German. Retype your password twice (password and confirm field) and press the Save button. You have to log out and in again to activate the change of the user language.

[edit]

Uninstallation

If you want to upgrade to a new version of OpenEMM you have to uninstall the current version first. This is done by 7 simple steps:

1. Change to user openemm

su – openemm


2. Stop OpenEMM:

OpenEMM.sh stop


3. Exit openemm user and change back to root

exit


4. Uninstall OpenEMM files

rm –rf /opt/openemm.org


5.a For security reasons make a backup of the openemm database(omit option –p in case your MySQL system is not password protected)

mysqldump -aCceQx –u root -p -r /home/openemm.db openemm


5.b Or, if you want to start with your next installation from scratch, simply delete the openemm database

mysqladmin -u root -p drop openemm


6. Delete home directory of OpenEMM

rm -rf /home/openemm


7. Delete user openemm:

userdel openemm


8. If you want to install a new version of OpenEMM create group and user openemm again (see section 1.3), continue with chapter 6 and omit section 6.1.

[edit]

Appendix

----Optional Setup----

Look here, if your MySQLd's default charset is not UTF-8.

OpenEMM and Port 80

You can use your system as a redirect server to quantify mail opening rates and link clicks. This is helpful to determine the success of an e-mail marketing campaign. By default, OpenEMM enables that service at port 8080. If you want to use a URL without an explicit declaration of a port, the section ’Running OpenEMM as Redirection Server on Port 80’ shows you a way.

1.) To use your system as a redirection server on port 80, make sure there are no conflicting services running on TCP port 80, like an Apache Webserver. On CentOS the check is done by running

netstat -ant | grep ’:::80’

2.) If any services are active, stop them. Example: to stop a HTTPD Server (Apache2) run "/etc/init.d/httpd stop". Also make sure, these services DO NOT start automatically after system reboot (for example by using ’chkconfig’)

3.) If you use a external redirection device, like a firewall, you can forward all traffic to Port 8080 of the OpenEMM machine. Consult the documentation of your firewall system for further details.

Running OpenEMM as Redirection Server on Port 80

(run as superuser)

Enable a Prerouting Forwarding Rule from port 8080 to 80 by adding the following code after the comments at the top in "/etc/sysconfig/iptables"

---File: /etc/sysconfig/iptables---

*nat

:PREROUTING ACCEPT [0:0]

:POSTROUTING ACCEPT [0:0]

:OUTPUT ACCEPT [0:0]

-A PREROUTING -i eth+ -p tcp --dport 80 -j REDIRECT --to-port 8080

COMMIT

---File: /etc/sysconfig/iptables---

Commiting the changes requires a restart of iptables, which is done by

/etc/init.d/iptables restart

Retrieved from "http://www.openemm.org/wiki/Installation:InstallGuideSUSE"
Views
Personal tools