Installation:InstallGuideRHEL

From OpenEMM Wiki

Jump to: navigation, search

Contents



AGNITAS OpenEMM

Install and Administration Guide

Red Hat Enterprise Linux and compatible 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 Red Hat 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 hardening it against various intrusion attempts.

yum update

[edit]

Operating System: Package Installation

(run as superuser)

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

yum install mysql-server sendmail-cf MySQL-python

[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.x.y" openemm

Note: In this document x and y are used as placeholders for the version number of the current release of 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)

Edit the file ’/etc/sysconfig/iptables’. The following example, shows permission rules for the services 25 (SMTP), 8080 (OpenEMM Redirection), 8081 (OpenEMM Console) and 80 (Optional, in case of forwarded Redirection services, see appendix). Add/modify the lines in the section ’-A RH-Firewall-1-INPUT’.

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

-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 25 -j ACCEPT

-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT

-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8080 -j ACCEPT

-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8081 -j ACCEPT

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

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

/etc/init.d/iptables restart

[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

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

Change the line:

DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

to:

dnl DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

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

This will enable Sendmail to listen on all available network interfaces, which is required by the OpenEMM bounce management system. By default Sendmail is listing only on the local interface lo0 for connections.


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

Add the following line at the end of file: INPUT_MAIL_FILTER(`bav', `S=unix:/home/openemm/var/run/bav.sock, F=T')dnl

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

This will enable the dynamic mail loop required by the bounce management system of OpenEMM.

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


If file relay-domains does not exist, create the file - for example by

touch relay-domains

and add a line, which specifies your DNS entry for the sender hostname (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, which activates the bounce management for that FQDN:

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

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


To activate the Sendmail changes, run the following commands:

cd /etc/mail

make

and restart the Sendmail service by:

/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.

[edit]

Install OpenEMM 5.x.y

(run as superuser)

Get the latest version of the OpenEMM binary code from

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

Your choice is the RPM package for Red Hat Enterprise Linux based distributions.

Copy the RPM package to a temporary location, /tmp is a good choice. Change into that directory and install OpenEMM as superuser by running the following command:

rpm -ihv OpenEMM-5.x.y-1.i386.rpm

Attention: The RPM package is running on Red Hat Linux Systems only. It was tested on Red Hat Enterprise Linux 4, CentOS 4 and Fedora Core 5.

[edit]

Read Access to Maillog

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

(run as superuser)

In the file ’/etc/logrotate.d/syslog’ add the following line after the line ’sharedscripts’:

---File: /etc/logrotate.d/syslog---

create 0604

---File: /etc/logrotate.d/syslog---

Also run

chmod 604 /var/log/maillog

to set the permissions of the current maillog.

[edit]

Initialize/Update the MySQL Database

(run as superuser)

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

/etc/init.d/mysqld restart

OpenEMM assumes mysqld is running on localhost.

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.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

Change to the directory containing the startup/shutdown script.

cd bin

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 package

rpm -e OpenEMM

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:

/usr/sbin/userdel openemm

8. If you want to install a new version of OpenEMM create group and user openemm again (see section "Operating System: Create the openemm User"), continue with chapter "Install OpenEMM 5.0.x" and omit section "Read Access to Maillog".

[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:InstallGuideRHEL"
Views
Personal tools