AGNITAS OpenEMM Setup Guide for OpenEMM 6.0.1 Virtual Machine (for Windo !

and "inu#$
Ver!ion 1.%.& ' (010011) t *opene++.or,

OpenEMM

Table of contents
1 How to run OpenEMM VMX 4

1.1 Installation of VMware Player.................................................................4 1.2 How to start the OpenEMM Virtual Machine.........................................4 1.3 Login the OpenEMM Virtual Machine...................................................4 1.4 in! out your IP"#!!ress.........................................................................$

2 Domain Name Service DNS! "onfi#uration

2.1 %e!irect ser&ices......................................................................................$ 2.2 'ounce (anage(ent................................................................................)

% "onfi#uration "&an#es ' Sen(mail 4 *p(ate *+,s in propert- files an( M-S., $ Start an( stop OpenEMM

) / 10

#*+I,#- #* 2../

,his !ocu(ent is a gui!ance through the a!(inistration process of OpenEMM on a &irtual (achine 0VM12. It re3uires a 4asic 5nowle!ge of Linu6 -yste( a!(inistration an! 0in case you nee! it2 of 7o(ain +a(e -er&ices 07+-2. ,he co((an!"line e6a(ples are 4ase! on %e! Hat Linu6.

How to use t&is (ocument

'elow you will fin! a short !escription8o&er&iew of OpenEMM9 the first professional e"(ail (ar5eting solution release! as an Open -ource. ollowing the !escription9 this !ocu(ent will gui!e you through so(e nessessary steps9 which are nee!e! to run OpenEMM s(oothly.

Tec&nical Overview of OpenEMM

OpenEMM is feature"rich enterprise software for e"(ail (ar5eting an! (ainly written in :a&a an! Python. OpenEMM e(ploys lea!ing e!ge :a&a fra(ewor5s li5e Hi4ernate9 -pring an! -truts. -o(e perfor(ance"sensiti&e co!e is written in ;. OpenEMM runs on top of a well pro&en Open -ource software stac5< Linu69 My-=L9 -en!(ail an! the we4 container li5e %esin 0inclu!e! in OpenEMM %PM an! tar4all2.

+e1uirements
VMware Player a&aila4le at http<88www.&(ware.co(8pro!ucts8player8 #t least 2 *'yte of free storage on your har! !ri&e +etwor5 En&iron(ent9 running a 7H;P ser&ice

OpenEMM

1 How to run OpenEMM VMX

121 3nstallation of VMware 4la-er
>ou will fin! the (ost current &ersion 03.. at the creation of this !ocu(ent2 of VMware Player at http<88www.&(ware.co(8pro!ucts8player8 ollow the instructions on the we4site to install VMware Player.

122 How to start t&e OpenEMM Virtual Mac&ine

;reate the VM1 ?ip file with cat OpenEMM-6.0.1-VMX.part* >> OpenEMM-6.0.1-VMX.zip 0Linu62 or type OpenEMM-6.0.1-VMX.part* >> OpenEMM-6.0.1-VMX.zip 0@in!ows2 Anpac5 the OpenEMM")...1"VM1.?ip file in a !e!icate! !irectory. or e6a(ple into ;<BOpenEMM")...1"VM1. Open a file 4rowser an! !ou4le clic5 the configuration file OpenEMM-6.0.1.vmx to start the VMware Player. If VMware Player as5s you at the first start whether you (o&e! or copie! the VM1 &ersion of OpenEMM choose the !efault answer CI copie! itC. Press the Power On 4utton to start the Virtual Machine.

12% ,o#in t&e OpenEMM Virtual Mac&ine

#fter the OpenEMM VMware appliance was starte!9 log in as -uperuser root< Username Passwor! root openemm

>ou re3uire this login for a couple of configuration changes9 which are !escri4e! 4elow.

124 5in( out -our 34'6((ress

#fter the start of the OpenEMM &irtual (achine9 you can fin! out its IP"#!!ress 4y logging into the &irtual (achine an! run the following co((an!< i"con"i# ,his will result in an output li5e<

et$0

%in& encap Et$ernet '(a!!r 00 0) *+ ,- ., /+ inet a!!r 10*.16.1..1* 2cast 10*.16.*,,.*,, Mas& *,,.*,,.0.0

,he IP"#!!ress use! 4y the OpenEMM &irtual (achine is< 1/2.1).13.D2. @rite !own that a!!ress9 since you nee! it to connect to OpenEMM in -tep 4.

2 Domain Name Service DNS! "onfi#uration

0I+portant< If you si(ply want to test OpenEMM9 you can 4asically ignore the following section. In that case9 OpenEMM can not recei&e e"(ails9 4ounces or resol&e re!irection lin5s o&er the networ5. If you nee! those features9 please consult your local syste( a!(inistrator for the setup.2

221 +e(irect services

'asically9 OpenEMM runs out of the 4o6. It Eust re3uires a si(ple =7+ 0 ully =ualifie! 7o(ain +a(e29 which is usually alrea!y (appe! to an a&aila4le IP" a!!ress 4y your I-P. >ou can use that =7+ for the re!irection ser&ices9 pro&i!e! 4y OpenEMM. E6a(ple< >our (achines hostna(e is www.somecompany.com In that case si(ply a!! that =7+9 as shown in the section FInitiali?e the My-=L 7ata4aseF 4elow. It woul! loo5 li5e $ttp 33www.somecompany.com 1010 since the re!irection ser&ices of OpenEMM usually uses port D.D.. If you use port D.D.9 !o not forget to inclu!e it in e6ternal lin5s pointing to OpenEMM 0li5e su4scri4e lin5s in for(s on your we4site2. Hint< >ou can (ap that port to another port " see #ppen!i6 for further !etails.

222 7ounce mana#ement

What i! the -ounce +ana,e+ent. ,he 4ounce (anage(ent pro&i!es you with the capa4ility to 5eep your (ailinglists clean an! up"to"!ate auto(atically. # 4ounce (essage is an error (essage9 which will 4e sen! fro( a (ailser&er of the recipient to the sen!er auto(atically9 if an E"Mail is not !eli&era4le. ,he 4ounce (anage(ent go&erns the en!uring an! passing E"Mails which are un!eli&era4le. It also filters the error (essages an! autorespon!er (ails. -etting up the 4ounce (anage(ent of OpenEMM is not necessary9 since 4ounce (anage(ent for 4ounces recei&e! !uring the sen! process 0instant 4ounces2 wor5s out of the 4o6. 'ut if OpenEMM shoul! e&en process 4ounces 0an! autorespon!er (ails2 which are recei&e! hours or e&en !ays later 0which is 3uite often the case2 you ha&e to !o so(e setup. Settin, up -ounce +ana,e+ent for dela/ed -ounce! If you want to use the 4ounce (anage(ent for !elaye! 4ounces you nee! to !efine a !e!icate! sen!er hostna(e for OpenEMM which is !ifferent fro( the e6isting host na(e of the ser&er an! you ha&e to set up a # recor! an! a M1 0Mail E6changer2 recor! in your 7o(ain +a(e -er&er 07+-2 for the sen!er hostna(e. ,he M1 recor! is use! to route (ail for a !o(ain to one or (ore IP a!!resses. -en!(ail nee!s the new 0&irtual2 host as a !estination9 to forwar! all inco(ing response to9 for further processing 4y OpenEMM. In our e6a(ple the regular hostna(e is GhostH an! the sen!er hostna(e for OpenEMM will 4e GnewsH. ,he 0a44re&iate!2 7+- entry loo5s li5e this< """7o(ain< opene((.org"""
16400 $ost news news.openemm.or#. 16400 16400 16400 56 56 56 56 / / / MX 0 10 10 10 1..**0.1,4.1, 1..**0.1,4.1, 1..**0.1,4.1, $ost.openemm.or#.

"""7o(ain< opene((.org""" ,he first line assigns the IP a!!ress for opene((.org an! the secon! line !efines the regular hostna(e. ,he thir! an! fourth line !efine the # recor! an! the M1 recor! for sen!er hostna(e GnewsH9 (eaning that host GhostH accepts e"(ails sent to host GnewsH.

Vali!ate your correct setup 4y using a tool li5e GhostH or G!igH9 for e6a(ple
$ost 7a openemm.or# $ost 7a $ost.openemm.or# $ost 7a news.openemm.or#

@hen you sen! e"(ails an! want to ta5e a!&antage of the 4ounce (anage(ent for !elaye! 4ounces there are two possi4ilities for the for(at of the sen!er a!!ress< A.$ Ase whate&er a!!ress you li5e. -et up a 4ounce filter in OpenEMM 0see user (anual2 to fowar! the filtere! response to a fee!4ac5 e"(ail a!!ress of your choice 0!ifferent fro( the sen!er a!!ress9 of course2. I(ple(ent a forwar! (echanis( to forwar! inco(ing (ail sent 4ac5 to the sen!er a!!ress to the forwar! a!!ress generate! 4y the 4ounce filter 0in our e6a(ple e6tI1Jnews.opene((.org2. ,he flow for responses of your e"(ails wor5s li5e this<
sen!er a!!ress -> "i8ter-#enerate! "orwar! a!!ress 9to "i8ter o:t ;o:nces< -> "ee!;ac& a!!ress

0.$ Ase an e"(ail a!!ress with the sen!er hostna(e 0in our e6a(ple newsJnews.opene((.org2 -ince no real e"(ail a!!resses e6ist for the sen!er hostna(e9 nor(ally it woul! not 4e possi4le to reply to an e"(ail with this en!er a!!ress. ,o forwar! responses to a &ali! e"(ail a!!ress you ha&e to !efine a 4ounce filter with an e"(ail fee!4ac5 a!!ress of your choice. ,he forwar! a!!ress generate! 4y the 4ounce filter 0in our e6a(ple e6tI1Jnews.opene((.org2 has to 4e !efine! as an alias in !irectory 8ho(e8opene((8conf84a& in a new file na(e! 4a&.conf"local. Our e6a(ple< """ ile< 8ho(e8opene((8conf84a&84a&.conf"local""""
news=news.openemm.or#a8ias ext>1=news.openemm.or#

""" ile< 8ho(e8opene((8conf84a&84a&.conf"local """" ,he flow for responses of your e"(ails wor5s li5e this<
sen!er a!!ress -> ;av.con"-8oca8 -> "i8ter-#enerate! "orwar! a!!ress -> "ee!;ac& a!!ress

% "onfi#uration "&an#es ' Sen(mail

0run as superuser2 ,o use the 4ounce (anage(ent syste( of OpenEMM for !elaye! 4ounces9 so(e (o!ifications are re3uire! 4y the superuser< """ ile< 8etc8(ail8relay"!o(ains""" ,o a!! a host li5e Gnews.so(eco(pany.co(H run the following co((an!<
ec$o ?news.somecompany.com? > 3etc3mai83re8ay-!omains

""" ile< 8etc8(ail8relay"!o(ains"""

""" ile< 8etc8(ail8(ailerta4le""" #lso run the following co((an! 0in one line2<
ec$o ?news.somecompany.com procmai8 3$ome3openemm3con"3;av3;av.rc? > 3etc3mai83mai8erta;8e

""" ile< 8etc8(ail8(ailerta4le"""

,o acti&ate the -en!(ail changes9 run the following co((an!s<

c! 3etc3mai8 ma&e

an! restart the -en!(ail ser&ice 4y<

3etc3init.!3sen!mai8 restart

>ou (ay ignore the warning that 8ho(e8opene((8&ar8run84a&.soc5 is (issing9 since this file will 4e pro&i!e! with the ne6t step.

4 *p(ate *+,s in propert- files an( M-S.,

0run as superuser2 Properties Csyste(.urlC an! Cecs.ser&er.urlC in file Ce((.propertiesC an! property Cc(s.ccr.urlC in file Cc(s.propertiesC 04oth in !irectory C8ho(e8opene((8we4apps8core8@E'I+ 8classesC2 (ust 4e set to the A%L of your OpenEMM installation9 which is usually i!entical with your re!irection A%L li5e $ttp 33www.somecompany.com 1010 ,o use &ali! re!irect A%Ls9 you nee! to e!it a para(eter in the OpenEMM !ata4ase. ,he re!irect A%L shoul! a!!ress the ser&er OpenEMM is running on 0for local tests http<88localhost<D.D. is sufficient2. or e6a(ple9 you want to use the A%L Chttp<88www.so(eco(pany.co(C for re!irection purposes. %un the following co((an!s< mys@8 7: root openemm :p!ate company>t;8 set r!ir>!omainA?$ttp 33www.somecompany.com 1010?B @:it If you plan to use the 4ounce (anage(ent for !elaye! 4ounces9 you ha&e to enter the sen!er hostna(e 0see 4ounce (anage(ent section2 into the !ata4ase. or e6a(ple9 you want to use the sen!er hostna(e Knews.so(eco(pany.co(C. %un the following co((an!s< mys@8 7: root openemm :p!ate company>t;8 set mai88oop>!omainA?news.somecompany.com?B @:it ,he sen!er hostna(e will 4e use! as !o(ain na(e for the forwar! a!!resses generate! 4y the 4ounce filter.

$ Start an( stop OpenEMM

0run as superuser2 'eco(e the user Fopene((F 4y running s: 7 openemm ,o start the OpenEMM en&iro(ent9 run OpenEMM.s$ start

,o stop OpenEMM OpenEMM.s$ stop

Point your we44rowser to

$ttp 33www.somecompany.com 1010

0insert your own ;onsole A%L here2 an! log into OpenEMM as

Username a!min Passwor! openemm

Instea! of a host na(e9 you can also use the IP"#!!ress fro( step 1.4 a4o&e. OpenEMM !etects the language setting of your we44rowser an! shows the appropiate login page. O4&iously9 your first step shoul! 4e to change the passwor! Gopene((H in the -ettings (enu to a new passwor!. 'y !efault9 the (enus of OpenEMM are shown in English. ,o change to *er(an language9 clic5 on (enu K-ettingsL an! choose su4(enu KAserL. -elect user Ka!(inL an! change the language fiel! fro( English to *er(an. %etype your passwor! twice 0passwor! an! confir( fiel!2 an! press the -a&e 4utton. >ou ha&e to log out an! in again to acti&ate the change of the user language.