IEM Patch Installation
This document describes how to install and configure GreenArrow Engine’s IEM Patch. It starts with a list of what GreenArrow will need to install this patch for you. This is followed by installation instructions, in case you’d like to install the patch yourself, or are curious about what’s done during the patch installation process.
Information Needed by GreenArrow
In order for GreenArrow to install GreenArrow Engine’s IEM integration patch, we’ll need the following information:
- An SSH account with permission edit your IEM installation’s files, upload new files, and create new cron jobs.
- Login information for an IEM user who is able to edit their SMTP server settings. This will be needed to send a test campaign following the patch installation.
- If your IEM installation’s database is running on a different physical server than your GreenArrow Engine installation, root level access to your operating system and database will be needed so that your database can be configured to allow remote connections. If you’re using MySQL, the root level user is typically named
root, and if you’re running PostgreSQL, the root level user is typically named
postgres. Alternatively, you can perform the steps listed in the MySQL or PostgreSQL section below if you’d prefer not to grant this level of access.
Most IEM installations use
email_ as a prefix to their table names. If your installation uses a different prefix, or none at all, update the the table names in these instructions to match your installation.
Run the following MySQL commands on the same database that IEM uses. We recommend running these commands while logged in as the same MySQL user that IEM uses, so that this user will have the correct permissions on the
ALTER TABLE email_lists ADD COLUMN mailroute varchar(100); CREATE TABLE email_greenarrow_queue ( id int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, event_type varchar(15) NOT NULL, listid varchar(255), email varchar(255), statid varchar(255), bounce_type varchar(255), bounce_rule varchar(255), bounce_message varchar(255), bounce_time int(11) );
- Grant the MySQL account that IEM is using permission to
DELETErows in the
email_greenarrow_queuetable. If you created this table while logged in with the MySQL account that IEM is using, then these permissions should be present by default.
Create a MySQL account that has permission to
INSERTrows in the
email_greenarrow_queuetable. For example you could login as the MySQL root user, then run the following two commands, replacing
iem_dbwith your database name,
127.0.0.1with the IP address that connections will be coming from, and
passwordwith the actual password to assign to the new user:
CREATE USER 'greenarrow'@'127.0.0.1' IDENTIFIED BY 'password'; GRANT SELECT, INSERT ON iem_db.email_greenarrow_queue TO 'greenarrow'@'127.0.0.1';
If your MySQL installation is running on a different physical server than your GreenArrow Engine installation, verify that the MySQL server is configured to accept connections remotely, and that there are no firewall rules that would prevent a MySQL user from logging in from your GreenArrow Engine server. GreenArrow’s base IP address can be determined by contacting GreenArrow technical support, or running the following command on your GreenArrow server.
curl http://automation.whatismyip.com/n09230945.asp && echo
Most IEM installations use MySQL as their database. If your installation uses PostgreSQL, contact GreenArrow technical support for details on how to configure it.
There are three versions of the patch:
- IEM Patch 1.07 - For IEM 6.1.3 and 6.1.4 installations.
- IEM Patch 1.06 - For IEM 6.1.2 installations that have the bugfix described on this page applied.
- IEM Patch 1.05 - For IEM 6.1.2 installations.
These instructions assume that you’re applying version 1.07 of the patch. If that’s not the case, you’ll need to update some of the commands to match the version that you are applying.
Change to the parent directory of your IEM installation’s document root. For example, this might be
Download the patch:
Create a pre-patch copy of IEM in case any bugs are discovered that Interspire tech support is needed for. For example, if IEM is installed in the
iemdirectory, you could run:
cp -a iem iem.prestine
Test if the patch will apply cleanly:
cd iem patch -p1 --dry-run < ../iem-greenarrow-patch-1.07.patch
If you are installing this on an unmodified version of IEM Version 6.1.4, we have seen some cases where all “hunks” of this patch will fail. If
--dry-runis showing 100% failure, you can try running this:
dos2unix admin/com/ext/interspire_email/email.php admin/com/ext/interspire_email/email.php admin/com/install/schema.mysql.php admin/com/install/schema.pgsql.php admin/com/language/default/stats.php admin/com/templates/lists_form.tpl admin/com/templates/send_step3.tpl admin/functions/api/jobs_autoresponders.php form.php
You would then need to re-run the
--dry-runto see if this fixed the failures.
Apply the patch:
patch -p1 < ../iem-greenarrow-patch-1.07.patch
Verify that the file ownership and permissions are set properly.
- Verify the following settings in the
GREENARROW_INTEGRATION_ENABLED- set to
1to enable the patch’s functionality, or
0to disable it.
GREENARROW_SENDID_LISTID_PREFIX- gives a unique alphabetical ListID prefixes to each IEM installation that you’re using, so that GreenArrow Engine will know which installation to send bounce and spam complaint data back to. This is a short alphabetical string, such as
zand is not case sensitive:
Create a new crontab entry for the same user that’s running IEM’s send.php process. If GreenArrow Engine is not installed on the same server as IEM, or not installed in the default location, then you’ll need to adjust the path to PHP to match your server’s configuration. A typical
# IEM / GreenArrow Integration * * * * * /var/hvmail/apache/php/bin/php -f <iem_install_path>/admin/cron/greenarrow_integrate.php
GreenArrow Engine Configuration
This is not currently documented. Please contact GreenArrow technical support with the following information for each IEM installation, so that GreenArrow’s can be properly configured to hand bounce and spam complaint data off to IEM:
- Login info for the MySQL or PostgreSQL user that will insert rows into the
- Database name
- Database type (MySQL or PostgreSQL)
- Address of the database server (IP address or fully qualified domain name).
- The alphabetical ListID prefix being used by the installation. For example,
This is the final step to perform before conducting end-to-end testing. The IEM Patch Usage Instructions document describes how to configure IEM.
GreenArrow technical support can perform end-to-end testing for you. If you’d like us to do this, please contact us with login information for an IEM user who is able to edit their SMTP server settings.
Reversing the Patch
If you need to reverse the patch for some reason, the files that are modified by it are listed below:
admin/com/ext/interspire_email/email.php admin/com/install/schema.mysql.php admin/com/install/schema.pgsql.php admin/com/language/default/stats.php admin/com/templates/lists_form.tpl admin/com/templates/send_step3.tpl admin/functions/api/jobs_autoresponders.php admin/functions/api/lists.php admin/functions/api/send.php admin/functions/api/subscribers.php admin/functions/lists.php admin/functions/send.php form.php
You can reverse the patch by either restoring the original copies of each of the above files, or by using a
patch command, as shown below:
patch -R -p1 < iem-greenarrow-patch-1.07.patch