先转载古来，回头再翻译...
Installation:InstallGuideDebian
From OpenEMM Wiki
Jump to: navigation, search
Contents
[hide]
* 1 How to use this document
* 2 Technical Overview of OpenEMM
* 3 Operating System
o 3.1 Operating System: Updates
o 3.2 Operating System: Package Installation
o 3.3 Operating System: Create the ’openemm’ User
* 4 Installation: Sun Java JDK
* 5 Enable OpenEMM access in the iptables-Firewall
* 6 Domain and Hostname
o 6.1 What is a DNS entry and what is the purpose?
o 6.2 What is a Hostname, a Domain and a FQHN?
o 6.3 How do I get a Domain and a FQHN?
* 7 Domain Name Service (DNS) Configuration
o 7.1 Redirect services
o 7.2 Bounce Management
+ 7.2.1 What is the bounce management?
+ 7.2.2 Setting up a bounce management for delayed bounces
* 8 Configuration Changes - Sendmail
* 9 Install OpenEMM 5.x.y
o 9.1 Read Access to Maillog
o 9.2 Initialize the MySQL Database
o 9.3 Update an existing MySQL Database
o 9.4 Start OpenEMM
* 10 Uninstallation
* 11 Appendix
AGNITAS OpenEMM
Install and Administration Guide
Debian and related Linux distributions
This information is not up to date. It probably should be updated and merged with the normal Installation Guide for the other Linux distributions for OpenEMM 6 -- akuckartz
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 Debian 3.1 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
* Red Hat Enterprise Linux 4 (http://www.redhat.com), Fedora Core 5 (http://fedora.redhat.com) or compatible OS like CentOS 4 (http://www.centos.org)
* or any other Linux distribution like openSuSE (no RPM yet, tarball only)
* Sun Java JDK 5
* Packages: mysql-server, sendmail-cf, MySQL-python
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.
apt-get update
[edit]
Operating System: Package Installation
(run as superuser)
Install the required packages. Further depencies will be resolved automatically by the installation programm.
apt-get install mysql-server-4.1 python-mysqldb sendmail-cf
OpenEMM will not work with mysql-4.0, therefore, you need at least version 4.1.
[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.y" 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)
A firewall on Debian/Ubuntu is provided by the ufw package, which is disabled by default. You can check to see if something has configured a firewall for you by typing the following:-
/sbin/iptables -L -n
If you are root, it will list your current firewall configuration. The following is the response from an open firewall:-
Chain INPUT (policy ACCEPT)
target prot opt source destination
Chain FORWARD (policy ACCEPT)
target prot opt source destination
Chain OUTPUT (policy ACCEPT)
target prot opt source destination
If you do not have an open firewall you will need to open certain ports, to allow permission for OpenEmm.
The following shows a number of commands which will by example, set insert into your firewall permission rules allowing for the services 25 (SMTP), 8080 (OpenEMM Redirection), 8081 (OpenEMM Console) and 80 (Optional, in case of forwarded Redirection services, see appendix).
/sbin/iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport 25 -j ACCEPT
/sbin/iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT
/sbin/iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport 8080 -j ACCEPT
/sbin/iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport 8081 -j ACCEPT
If you need to do this, you should put the 4 lines listed in a file which will be run, after your firewall has been set up, and your network configured.
Note: The following is not tested, so please can someone remove this note if they try this
If you are using ufw, then you will need to edit the file /etc/ufw/before.rules and add the following lines, before the comment block # ufw-not-local
-A ufw-before-input -m state --state NEW -m tcp -p tcp --dport 25 -j ACCEPT
-A ufw-before-input -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT
-A ufw-before-input -m state --state NEW -m tcp -p tcp --dport 8080 -j ACCEPT
-A ufw-before-input -m state --state NEW -m tcp -p tcp --dport 8081 -j ACCEPT
You will need to save the file and reload ufw by typing the following:-
/etc/init.d/ufw reload
[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) If you want to use the bounce management of OpenEMM for delayed bounces, some modifications are required by the superuser:
---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 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.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.x.y
mv USR_SHARE/* /usr/share/doc/OpenEMM-5.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.x.y’.
The file bin/smctrl is a 32-bit binary executable that is linked to 32-bit Java libraries. This means that if you are on a 64 bit Debian/Ubuntu machine, you need to run "sudo aptitude install ia32-sun-java5-bin". Otherwise you will get errors telling you the "/home/openemm/bin/smctrl" file does not exist. Some more details can be found at http://www.openemm.org/forums/ftopic829.html.
[edit]
Read Access to Maillog
OpenEMM requires read access to ’/var/log/maillog’.
(run as superuser)
---File: /etc/syslog.conf---
Change the line:
mail.* /var/log/mail.log
to:
mail.* /var/log/maillog
---File: /etc/syslog.conf---
---File: /etc/cron.weekly/sysklogd---
Change the line:
savelog -g adm -m 640 -u root -c 4 $LOG >/dev/null
to:
savelog -g adm -m 644 -u root -c 4 $LOG >/dev/null
---File: /etc/cron.weekly/sysklogd---
Also run
chmod 644 /var/log/maillog
to set the permissions of the current maillog.
[edit]
Initialize the MySQL Database
(run as superuser)
Make sure that MySQL is running. This is done by:
/etc/init.d/mysqld 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.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]
Update an existing MySQL Database
(run as superuser)
Users of OpenEMM 5.0.3 (or earlier) need to upgrade the MySQL Database, because of new data tables and fields. To update the Database, simply run the following command:
mysql -u root -p openemm < update_openemm.sql
The required Script "update_openemm.sql" will be found in
/usr/share/doc/OpenEMM-5.1.x.y
After the update you are ready to use OpenEMM 5.1.x.y!
[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.somecompany.com: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 putting the following code in your firewall script:
iptables -A PREROUTING –t nat -i eth+ -p tcp --dport 80 -j REDIRECT --to-port 8080
Commiting the changes requires a restart of the script. |
发表于 2010-1-8 10:52
|