Java Email Server

(JES)
version 2.8.x
License Information
Copyright (c) 2001-2014, Eric Dagherty (http!""###.eric$agherty.co%)
&'' rights reserve$.
(e$istri)tion an$ se in sorce an$ )inary *or%s, #ith or #ithot %o$i*ication, are
per%itte$ provi$e$ that the *o''o#ing con$itions are %et!
+ (e$istri)tions o* sorce co$e %st retain the a)ove copyright notice, this 'ist o*
con$itions an$ the *o''o#ing $isc'ai%er.
+ (e$istri)tions in )inary *or% %st repro$ce the a)ove copyright notice, this 'ist o*
con$itions an$ the *o''o#ing $isc'ai%er in the $oc%entation an$"or other %ateria's
provi$e$ #ith the $istri)tion.
+ ,either the na%e o* the copyright ho'$er nor the na%es o* its contri)tors %ay )e
se$ to en$orse or pro%ote pro$cts $erive$ *ro% this so*t#are #ithot speci*ic prior
#ritten per%ission.
-./S S01-2&(E /S 3(04/DED 56 -.E C036(/7.- .08DE( 99&S /S99 &,D
&,6 E:3(ESS 0( /;38/ED 2&((&,-/ES, /,C8<D/,7, 5<- ,0- 8/;/-ED -0, -.E
/;38/ED 2&((&,-/ES 01 ;E(C.&,-&5/8/-6 &,D 1/-,ESS 10( & 3&(-/C<8&(
3<(30SE &(E D/SC8&/;ED. /, ,0 E4E,- S.&88 -.E C036(/7.- .08DE( 5E
8/&58E 10( &,6 D/(EC-, /,D/(EC-, /,C/DE,-&8, S3EC/&8, E:E;38&(6, 0(
C0,SE=<E,-/&8 D&;&7ES (/,C8<D/,7, 5<- ,0- 8/;/-ED -0, 3(0C<(E;E,-
01 S<5S-/-<-E 700DS 0( SE(4/CES> 80SS 01 <SE, D&-&, 0( 3(01/-S> 0(
5<S/,ESS /,-E((<3-/0,) .02E4E( C&<SED &,D 0, &,6 -.E0(6 01
8/&5/8/-6, 2.E-.E( /, C0,-(&C-, S-(/C- 8/&5/8/-6, 0( -0(- (/,C8<D/,7
,E78/7E,CE 0( 0-.E(2/SE) &(/S/,7 /, &,6 2&6 0<- 01 -.E <SE 01 -./S
S01-2&(E, E4E, /1 &D4/SED 01 -.E 30SS/5/8/-6 01 S<C. D&;&7E.
-his version o* the $oc%entation processe$ #ith 8i)re0**ice 4.1.x, 'ast e$ite$ 1. Jan. 2014
Java Runtime
JES 2.8.x co%pi'es n$er Java SE ?, @. -he testing site has )een execte$ sing the SE
? J(E in #in$o#s @.
Dependencies
(nti%e
co%%ons-co$ec 1.4
co%%ons-$)cp 1.A (or 1.4)
co%%ons-poo' 1.B.4
co%%ons-'ogging 1.1.1
$er)y 10.10.1.1
$er)yc'ient 10.10.1.1
$er)ynet 10.10.1.1
JES-D,S 1.0
JES-Crypto 1.0
nix</D 1.0
-est (in a$$ition to the rnti%e 'i)raries)
Cavax-%ai' 1.B.1
Cnit 4.11
'og4C 1.2.1@
popA 1.B.1
s%tp 1.B.1
&'' the a*ore%entione$ 'i)raries are $o#n'oa$e$ #hen the %aven proCect co%pi'es.
-here are no csto% )i't versions o* externa' sorce co$e. JES is ho#ever $epen$ent on
three s)proCects, na%e'y nix</D, JES-Crypto an$ JES-D,S. -hey are avai'a)'e in the
sorce*orge svn repository an$ the prepacDage$ re'ease *i'es. -he correspon$ing Car
execta)'es have to )e %ana''y insta''e$ in the 'oca' %aven repository.
Table of Contents
Important considerations....................................................................................................6
Installation............................................................................................................................7
/nsta''ing JES on a 2in$o#s 3C.................................................................................................. @
/nsta''ing JES on a 8inx 3C........................................................................................................ @
Additional otes...................................................................................................................!
Setting p JES *or the *irst ti%e.................................................................................................... E
<sing a *i'esyste% as a )acDen$.............................................................................................E
<sing a $ata)ase as a )acDen$.............................................................................................. E
Java Service 2rapper.................................................................................................................. E
(nning JES sing Ces.sh in <nix 'iDes...................................................................................... 10
(nning JES sing %ai'.)at in 2in$o#s " %ai'.sh in <nix 'iDes..................................................10
JES-D,S................................................................................................................................... 10
Java Cryptographic Fey Strength 3o'icy....................................................................................12
Deve'oping " checDing ot JES n$er ,et5eans " Ec'ipse.........................................................12
<sing ,et5eans /DE............................................................................................................. 12
<sing Ec'ipse /DE................................................................................................................. 12
5i'$ /nstrctions *or version 2.@.x an$ higher...........................................................................12
Secrity po'icy entries that nee$ %ana' e$iting........................................................................1A
/sses #ith (1ree) E-%ai' Services............................................................................................. 1A
8ogging 1aci'ity.......................................................................................................................... 1A
Der)eros B 3rincipa's................................................................................................................. 14
;igration -oo'............................................................................................................................ 14
-esting the proCect sing ;aven................................................................................................. 14
<sing a recipient po'icy to han$'e %essage recipients...............................................................1B
JSSE Deystore pass#or$ an$"or Der)eros B principa' pass#or$s..............................................1B
JES 4a't an$ the %aster pass#or$.......................................................................................... 1?
<p$ating the %aster pass#or$.............................................................................................. 1?
;aster pass#or$ strength..................................................................................................... 1@
<p$ating the )on$ S;-3"303A ports on a rnning JES instance...........................................1@
T"e Confi#uration $ana#er %ac&End..............................................................................'(
/ntro$ction................................................................................................................................ 18
&pache $er)y............................................................................................................................. 18
Data)ase hosting.................................................................................................................. 18
-8S secre$ connection........................................................................................................ 18
Connection5ase$Con*igrator................................................................................................... 1E
-8S secre$ connection........................................................................................................ 1E
Secrity p$ates in the sorce................................................................................................... 1E
<ser access to $er)y................................................................................................................. 1E
<p$ating the $) ser cre$entia's........................................................................................... 20
Settings not avai'a)'e via the C5C............................................................................................. 20
)inal notes..........................................................................................................................*'
Appendi+.............................................................................................................................**
C5C Co%%an$s........................................................................................................................ 22
C5C Co%%an$s in D) %o$e................................................................................................ 22
C5C Co%%an$s in 1i'e %o$e............................................................................................... 2B
3ass#or$ *i'e entries an$ their respective (Dey"va'e) *or%at....................................................2?
Sa%p'e tests.x%' *i'e.................................................................................................................. 2@
Spporte$ &thentication ;echanis%s (per operation %o$e)....................................................28
JES exection arg%ents.......................................................................................................... 2E
'. Important considerations
a. Do not atte%pt to rn JES si%p'y )y invoDing the Car as an arg%ent *or a Cava
execta)'e, np'easant $isco%*ort #i'' )e the on'y res't. Certain arg%ents have to )e
passe$ to the J4; an$ JES itse'*. See sections GJava Service 2rapperG, G(nning JES
sing %ai'.)at in 2in$o#s " %ai'.sh in <nix-'iDesG *or $etai's regar$ing these arg%ents
an$"or the %ai'.)at " %ai'.sh co$e.
). JES ships #ith the secrity %anager o** )y $e*a't. 6o %st change the re'ative entry
in section Server Secrity 3o'icy o* %ai'.x%' to ena)'e it. 6o are strong'y encorage$ to
rea$ the present $oc%ent in its entirety.
c. Starting #ith version 2.B JES no 'onger spports Java versions prior to ?. /* yo are
#o'$ rather se an ear'ier Java version p'ease se'ect one o* the previos JES re'eases.
*. Installation
-o insta'' an$ rn this %ai' server, carry ot the *o''o#ing!
/nsta'' a Java JDF or J(E version ? or greater )y visiting!
http!""###.orac'e.co%"technet#orD"Cava"in$ex.ht%' or http!""###.Cava.co%)
0ptiona''y insta'' the JCE (Jave Cryptography Extension). (ea$ the GJava Cryptographic
Fey Strength 3o'icyG section *or $etai's.
*.' Installin# JES on a ,indo-s .C
1. Expan$ the $istri)tion archive to the $irectory o* choice.
2. ;o$i*y the inc'$e$ script *i'es *or yor 'oca' *i'e syste% (i* necessary).
A. E$it the %ai'.x%', ser.con* (i* sing the 1i'e )acDen$ option), 'og4C.properties
(optiona''y), #rapper.con* *i'es as nee$e$. See section entit'e$ GSetting p JES *or
the *irst ti%eG.
4. Spp'y (i* nee$e$) the necessary pass#or$s in the Gpass#or$G *i'e in the
secrity $irectory. De'ete the pass#or$ *i'e in the secrity $irectory an$ rena%e
pass#or$2in to pass#or$, i* yo p'an to se the spp'ie$ Deystore #ithot
changing the spp'ie$ pass#or$ (Deeping this pass#or$ is o* corse not
reco%%en$e$).
B. Se'ect one o* three (pre$e*ine$) #ays to rn the server!
a. as a stan$a'one conso'e app'ication sing %ai'.)at
). as a #rappe$ conso'e app'ication sing Ces.)at
c. as a #rappe$ service )y execting /nsta''Ces-,-.)at an$ starting it )y!
/. typing in the co%%an$ conso'e! net start JavaHE%ai'HServer,
//. accessing the Services conso'e, se'ecting Java E%ai' Server
an$ c'icDing on 9Start the Service9,
///. restarting the syste%.
Java 2rapper (i* se$) %st )e con*igre$ *or proper JES operation. (ea$ *rther
on.
/* yo p'an to rn JES sing %ai'.)at p'ease rea$ ahea$.
*.* Installin# JES on a Linu+
'
.C
Extract the contents o* the )in re'ease archive to a $irectory, pre*era)'y to
1 The example applies to a Ubuntu installation although it should work with any Debian release with trivial
modifications. Furthermore, linux systems, as well as other U!"#$%&!" systems, assign 'by default( the first
1)*+ ports exclusively to privileged users 'the root in the case of linux(. This has to be taken into account since the
mail related protocols use 'by default( these privileged 'well,known( ports.
"sr"'oca'"Ces or "opt"Ces.
/* JES is to )e execte$ at 'inx ()nt"De)ian) syste% start (ths #ith root
privi'eges, #hich are revoDe$ )y $o#ngra$ing to a 'ess privi'ege$ ser) !
Create a syste% ser exp'icit'y ca''e$ Ceserver #ith the *o''o#ing co%%an$
sing root privi'eges!
sudo adduser --system --ingroup <userGroup> jeserver
#here Iser7ropJ sho'$ i$ea''y )e s)stitte$ )y the grop the
a$%inistrator o* JES )e'ongs to. -he #rapper start script has )een a'tere$ to
rea$ the i$ o* the Ceserver ser *ro% the syste%.
;aDe sre everything in the insta'' $ir is o#ne$ )y the Ceserver ser an$
a$%in grop!
sudo chown -R jeserver:<userGroup> /usr/local/jes
(estrict the access to the insta''e$ *i'es as $esire$. ;aDe sre the Ces.sh
script in the )in $ir is execta)'e. E$it the Ceserver script *i'e in the )in insta''
$ir in or$er to set the JES3&-. arg%ent to the $irectory JES has )een
insta''e$ in.
1or exa%p'e! JES!"#$/usr/local/jes or JES!"#$/opt/jes
;ove or copy the Cerser script to "etc"init.$ an$ %aDe sre it is execta)'e!
sudo chmod ug%& /etc/init'd/jeserver
0ptiona''y prevent others *ro% execting it!
sudo chmod o-& /etc/init'd/jeserver
/n or$er to %aDe JES start at )oot ti%e si%p'y execte!
sudo update-rc'd /etc/init'd/jeserver de(aults )* +*
-he 40 ?0 *igres are si%p'y a reco%%en$ation.
-he Ceserver script exectes the Ces.sh script. -his t#o are to )e se$ in
conCction n$er the ass%ptions 'ai$ ot in this section. See section
G(nning JES sing Ces.sh in <nix 'iDesG *or %ore in*o.
/n any other case!
;aDe sre the %ai'.sh script in the )in $ir is execta)'e.
(ea$ section G(nning JES sing %ai'.)at in 2in$o#s " %ai'.sh in <nix 'iDesG
*or changes nee$e$ )e*ore ca''ing the script.
E$it the %ai'.x%', ser.con* (i* sing the 1i'e )acDen$ option), 'og4C.properties
" C$D14.properties (optiona''y), #rapper.con* *i'es as nee$e$. See section
entit'e$ GSetting p JES *or the *irst ti%eG.
.ave the nee$e$ pass#or$s avai'a)'e in the Gpass#or$G *i'e in the secrity
$irectory. Ca'' a script as root #ith a start arg%ent or restart the syste%.
Java 2rapper (i* se$) %st )e con*igre$ *or proper JES operation. See
section A.2.
Recommendation
Remem,er to read the rest o( this document thoroughly when you have the
time or should you encounter any issues ,e(ore posting to the project-s
mailing list' .ost issues are covered ,y the documentation'
/. Additional otes
/.' Settin# up JES for t"e first time
,o specia' changes are nee$e$ *or the optiona' 'og4C.properties " C$D14.properties except
ena)'ing the SocDet&ppen$er " SocDet.an$'er an$ setting the (e%ote.ost an$ 3ort to )e
se$ )y C.&/,S&2 (or any app'ication setp to 'isten *or events on the speci*ie$ net#orD
a$$ress"port). 6o can a'so $e*ine the $e*a't 'ogging 'eve' (in*o, $e)g etc.) *or any o* the
'oggers. /* yo p'an to se a $i**erent 'ogging *aci'ity set it p accor$ing'y.
/.'.' 0sin# a files1stem as a bac&end
-he %ai'.x%' con*igration *i'e nee$s very *e# changes *or initia' sage. 0ne sch is
a$$ing at 'east one 'oca' $o%ain to G)acDen$"1i'e"$o%ainsG an$ optiona''y a $e*a't ser to
G)acDen$"1i'e"$e*a't;ai')oxG that ;<S- )e a %e%)er o* the $o%ain $e*ine$ in $o%ains.
/* yo 9re satis*ie$ #ith the $e*a't options there are no %ore changes nee$e$ to %ai'.x%'.
See entries in the con*igration *i'e *or in*or%ation concerning their sage.
.aving a$$e$ a 'oca' $o%ain to %ai'.x%' to )e a$%inistere$ )y JES, sers (a'ong #ith
their pass#or$) )e'onging to the a*ore%entione$ $o%ain are entere$ into *i'e ser.con*. &t
'east one ser sho'$ )e registere$ #ith JES. See ser.con* *or $etai's concerning the
*or%at o* entries in that *i'e.
/.'.* 0sin# a database as a bac&end
-he sers.con* an$ rea'%s.con* as #e'' as the entries K$o%ainsL an$ K$e*a't;ai')oxL in
%ai'.x%' are ignore$. &'' entries pertaining to $o%ains"sers"rea'%s are han$'e$ via the
$ata)ase. ,o $o%ains"sers"rea'%s are nee$e$ to )oot JES in this %o$e. &'' sch entries
are passe$ to the $ata)ase throgh the Connection5ase$Con*igrator. -here*ore yo
must ena)'e it )y setting the $esire$ va'es *or the Kc)c"'isten&$$ressL an$ Kc)c"portL
entries in %ai'.x%'. /nstrctions on ho# to se the C5C can )e *on$ in section 4.
/.* Java Service ,rapper
-he Java Service 2rapper 'i)rary is o**ere$ as a %eans o* starting JES. /n or$er *or JES to
execte proper'y a %o$i*ication has to )e app'ie$ to #rapper.con*. & va'e has to )e
$e*ine$ *or the *o''o#ing entry!
wrapper'app'parameter'/$
-his option correspon$s to the *irst arg%ent o* the JES %ain c'ass #hich the %ai' server
consi$ers to )e the JES insta'' $ir. /t is strong'y reco%%en$e$ that an a)so'te path is
provi$e$ (e.g. c!MCes on #in$o#s or "sr"'oca'"Ces on 'inx). &$$itiona''y, *or each Car that
i%p'e%ents a speci*ic externa' %o$'e, an entry ;<S- )e present in #rapper.con* that
%atches the co%p'ete Car path. Sch an entry can, *or instance, )e!
wrapper'java'classpath'0$''/e&ternal/JES-.odule1'jar
/./ Runnin# JES usin# 2es.s" in 0ni+ li&es
-his script is on'y to )e se$ (#ithot %o$i*ications) n$er the ass%ption that a syste%
ser is create$ as $escri)e$ in the nix insta''ation process in s)section 2.2. 8inx ports
n$er 1024 are privi'ege$ there*ore on'y the root %ay se the%. &*ter setting p the ports,
JES s#itches to the non privi'ege$ Ceserver ser. Do not try to rn this script #ithot
*o''o#ing the process $ictate$ in s)section 2.2. <se %ai'.sh i* yo are not #orrie$ a)ot
syste% secrity. (-hanDs 8o'o)
/.3 Runnin# JES usin# mail.bat in ,indo-s 4 mail.s" in 0ni+ li&es
/n or$er to proper'y execte JES *ro% the co%%an$ pro%pt sing %ai'.)at"%ai'.sh the sai$
)atch *i'e has to )e %o$i*ie$. J&4&HE:EC nee$ not )e a'tere$ i* the $e*a't insta''e$ J&4&
rnti%e is accepta)'e to )e se$ #ith JES. JESH.0;E ;<S- )e set to the $irectory JES
#as insta''e$ into. /* yo p'an to se externa' %o$'es #ith JES, the *'' *i'e path %st )e
appen$e$ to the c'asspath (-cp) entry.
-o execte the script, no arg%ents are reNire$ at the co%%an$ 'ine. ,onethe'ess, a
sing'e script arg%ent can )e $e*ine$, to )e interprete$ either as the KtestingL property or
the i$ to $o#ngra$e to. /n the 'atter case, i* JES is rnning on 2in$o#s, the property #i''
)e ignore$. /* ho#ever JES is rnning on 8inx an$ can not $o#ngra$e ()ecase the script
#as not execte$ as root) the exection #i'' en$ a)rpt'y.
/.5 JES6DS
JES (starting #ith version 2.8) is sing an in-hose so*t#are 'i)rary to reso've /3 an$ $ns
na%es, in a transparent #ay to the app'ication. ,o specia' han$'ing is nee$e$, nor any
arg%ents are reNire$ to )e entere$ in the start scripts.
-#o *ixe$ arg%ents are crrent'y present in the exection scripts (%ai'.)at, %ai'.sh,
#rapper.con*), na%e'y!
dns'simple$true an$
dns'mode$recursive.
-hese are reNire$ crrent'y, to assre the %ost re'ia)'e se o* JES-D,S. -he 'i)rary is at
this ti%e n$er $eve'op%ent an$ in *tre re'eases, these arg%ents %ay no 'onger )e
necessary.
/n recrsive %o$e (#hich is not the $e*a't JES-D,S %o$e o* operation, iterative is) JES-
D,S ato-$etects 'oca''y avai'a)'e D,S servers. /* speci*ic $ns servers are $esira)'e, or
JES-D,S is na)'e to *in$ D,S servers, a co%%an$ separate$ 'ist o* /3 a$$resses o*
na%e servers (or reso'vers) can )e spp'ie$ via the $ns.servers arg%ent.
1or %ore in*or%ation concerning JES-D,S an$ *rther con*igration options, p'ease
cons't the JES-D,S $oc%entation.
/.6 Java Cr1pto#rap"ic 7e1 Stren#t" .olic1
Java $oesn9t spport the entire range o* cryptographic Dey strengths ot o* the )ox $e to
<S po'icy export restrictions i%pose$ on the $istri)te$ Cava )n$'es. & separate $o#n'oa$
#hich can )e retrieve$ *ro%!
http!""###.orac'e.co%"technet#orD"Cava"Cavase"$o#n'oa$s"in$ex.ht%'
ca''e$ Java Cryptography Extension (JCE) <n'i%ite$ Strength Jris$iction 3o'icy 1i'es
exists, that a''o#s Java to n'eash *'' Dey strength spport. 1o''o# the instrctions
containe$ in the $o#n'oa$e$ archive to insta'' it. 1or the (-1; cha''enge$, one si%p'y
nee$s to copy
local2policy'jar
3S2e&port2policy'jar
*ro% the $o#n'oa$e$ archive to the Ise$-Cre-insta''-pathJM'i)Msecrity $irectory rep'acing
the *i'es o* the sa%e na%e.
/;30(-&,- ,0-/CE! Sho'$ yo $eci$e not to insta'' the JCE, JES2 #i'' rn Cst *ine
#ith t#o (2) secrity exceptions! -he ena)'e$ -8S"SS8 ciphers #i'' )e restricte$ to
&ESH128 an$ DES an$ JES va't #i'' )e encrypte$ #ith a 128)it &ES Dey.
/.7 Developin# 4 c"ec&in# out JES under et%eans 4 Eclipse
/.7.' 0sin# et%eans IDE
(egar$'ess o* si%p'y npacDing a sorce $istri)tion o* JES or checDing ot the
sorce*orge S4, repository, ,et5eans /DE has everything pre-insta''e$ (even the )asic
Java SE $o#n'oa$ )n$'e) so no a$$itiona' actions are reNire$.
/.7.* 0sin# Eclipse IDE
& *e# p'gins nee$ to )e insta''e$ in Ec'ipse in or$er to *''y spport JES. &t *irst the
s)c'ipse p'gin (http!""s)c'ipse.tigris.org") %st )e insta''e$ in or$er to a$$ S4, spport
to Ec'ipse. ;aven spport %st then )e a$$e$. %2e (http!""ec'ipse.org"%2e") is the
reco%%en$e$ p'gin. -here is a Dno#n )enign )g in %2e that %ani*ests itse'* #henever
execting a %aven co%%an$ throgh the /DE. -o overco%e )g A8@0?4, *o''o# the
instrctions in Co%%ent O12. -his appears to )e the c'eanest so'tion.
/.( %uild Instructions for version *.(.+ and "i#"er
5i'$ing JES *ro% sorce reNires ;aven (version A.0.x is se$ an$ reco%%en$e$).
JES can )e )i't )y invoDing the mvn pac4age or mvn clean pac4age co%%an$s. 0n'y nit
testing taDes p'ace in this case. /* the %ore e'a)orate si%'ation rns are $esire$, the
co%%an$ to invoDe is mvn integration-test' -he nit tests can a'so )e rn $irect'y ()y
invoDing mvn test at a co%%an$ pro%pt"ter%ina').
-he Cars JES-D,S-1.0.Car, JES-D,S-1.0.Car an$ nix-</D-1.0.Car %st )e %ana''y
insta''e$ in the 'oca' repo. -hey are inc'$e$ in the re'ease Cars an$ the sorce*orge svn
repository.
-here is the option o* speci*ying the $irectory to #here a testing insta''ation o* JES resi$es,
so that a copy o* the ne#'y )i't Ces.Car *i'e can )e ato%atica''y trans*ere$ to. &'' that is
reNire$ is the presence o* a properties *i'e entit'e$ copy-o.properties in the root $irectory
o* the JES proCect. & sing'e entry pointing to the $esire$ $irectory, #ith the Dey Ktest.$irL
an$ the correspon$ing va'e, %st )e inc'$e$.
/.! Securit1 polic1 entries t"at need manual editin#
-he c%)erso%e an$ error prone proce$re o* %ana''y speci*ying po'icy.*i'e entries has
)een $roppe$, in *avor o* an ato%ate$ po'icy.*i'e generation sche%e.
/.'8 Issues -it" 9)ree: E6mail Services
1or so%e ti%e no#, hot%ai', g%ai', yahoo an$ %ost 'iDe'y other %ai' servers (*ree or not)
have )een sing spa%has9 358 to reCect nathenticate$ %ai' *ro% reNests originating
*ro% servers rnning on $yna%ic /3s. -here*ore, the reverseD,S strategy so'tion
previos'y e%p'oye$ has )een ren$ere$ ine**ective. -he %ost via)'e so'tion at this ti%e is
to *orce the se o* a s%arthost. -he #ay to $o this is )y a$$ing one or %ore hosts in the
K%ai'"otgoingS;-3Server"serverL e'e%ent o* %ai'.x%' to point to yor /S39s %ai' server or
a co%%ercia''y avai'a)'e s%arthost.
/.'' Lo##in# )acilit1
JES a''o#s co%%ons-'ogging to $eter%ine the 'ogging syste% to )e se$. 2hi'e 'og4C is
inc'$e$ in the spporting 'i)raries, it is on'y speci*ie$ externa''y via #rapper.con* or
%ai'.)at. ,o har$ co$e$ entry in the %ani*est *i'e exists.
-#o settings are se$ to achieve this in case 'og4C is se$!
org'apache'commons'logging'5og$org'apache'commons'logging'impl'5og)J5ogger
log)j'con(iguration$(ile:''/con(/log)j'properties
-he secon$ sho'$ point to a va'i$ <(8 (as speci*ie$ in Cava).
Since the 'ogging syste%9s 'i)raries have to )e 'ocate$ in the c'asspath an entry has to )e
present in %ai'.)at!
-cp <other entries>67JES2#8.E79li,9log)j-1'/'1:'jar
an$"or #rappers.con*!
wrapper'java'classpath')$''/li,/log)j-1'/'1:'jar
5y $e*a't, JES ses 'og4C ot o* the )ox #ith no ser intervention, )y %eans o* the
a*ore%entione$ settings. /* a $i*errent version an$"or *i'e 'ocation o* 'og4C is to )e se$, the
'og4C.con*igration setting an$ the c'asspath entry have to )e a'tere$ accor$ing'y.
Starting #ith JES 2.B.x the native Java 'ogging *aci'ity, co%%on'y Dno#n as the C$D14
'ogger, can )e se$ a'%ost ot o* the )ox. & *e# %o$i*ications to the starting scripts is a''
that is nee$e$. ,ote, that in %ai'.)at an$ %ai'.sh they are a'rea$y in p'ace. &'' that is
reNire$ is to co%%ent ot the 'og4C exection entry an$ nco%%ent the C$D14 entry.
(egar$'ess, the script entries are 'iste$ next.
org'apache'commons'logging'5og$org'apache'commons'logging'impl'Jd41)5ogger
java'util'logging'con(ig'class$com'ericdaugherty'mail'server'logging'jd41)'5ogging;on(ig5oader
java'util'logging'con(ig'(ile$<JES2#8.E/con(/jd41)'properties or 7JES2#8.E7/con(/jd41)'properties
jes'install'directory$<JES2#8.E or 7JES2#8.E7
Sho'$ a $i**erent 'ogging sit version or $i**erent settings *or any 'ogging %e$i% )e
$esire$, co%%ons-'ogging an$ the 'ogging *aci'ity o* choice %st )e exp'icit'y con*igre$.
0* specia' note is the *act that *or its o#n testing prposes, JES exp'icit'y ses 'og4C, so a
$epen$ency is present in the po% )t is restricte$ to the test scope.
/.'* &erberos 5 .rincipals
/n or$er to se one or %ore Der)eros B principa's one nee$s not on'y $e*ine the re'ative
settings in %ai'.x%' )t a'so e$it a *e# entries in the secrity po'icy *i'e. De*a't entries are
a'rea$y inc'$e$ in the po'icy *i'e that have to )e a'tere$.
Speci*ica''y!
.ave the entry per%ission IICava.net.SocDet3er%ission G+.exa%p'e.co%!88GJJ point to
a speci*ic host that the D$c is rnning on, setting a port other than 88 i* necessary.
1or each principa' t#o entries are reNire$!
<<permission java&'security'auth'!uthermission
=create5ogin;onte&t'com'ericdaughery'mail'server'auth'GSSServer.ode<protocol>=>>
<<permission java&'security'auth'4er,eros'Serviceermission
=<protocol>/host'e&ample'com>E?!.5E';8.=@ =accept=>>
S)stitte Iprotoco'J #ith the na%e o* the protoco' *or the principa' in Nestion. (ep'ace
host.exa%p'e.co% #ith the host na%e o* the server the service is rnning on. (ena%e
E:&;38E.C0; to the rea'% na%e o* choice sing pper case.
/.'/ $i#ration Tool
-o *aci'itate an expe$ite$ transition to version 2 a S;-3 %essage an$ pass#or$
conversion ti'ity is inc'$e$ in pacDage co%.eric$agherty.%ai'.server.ti's. -o se it
si%p'y type at a co%%an$ pro%pt!
java -cp <path to>/jes'jar com'ericdaugherty'mail'server'utils'.igrate arg1 arg/
#here!
arg1 is the $irectory #here JES 1.?.1 resi$es.
arg2 is a te%porary $irectory #here the converte$ s%tp %essages an$ the ser.con* *i'e
are to )e persiste$. -he %igration ti'ity #i'' create this $irectory i* it $oes not yet exist. /*
yo p'an to se a $) as the )acDen$ (version 2.1.x an$ over) the ser pass#or$s nee$ to
)e respeci*ie$ since the pass#or$ generation process is $i**erent to that o* version 2.0.x
an$ ear'ier.
/.'3 Testin# t"e pro2ect usin# $aven
-he testing *aci'ity has )oth a nit an$ a co%ponent integration testing aspect. -he nit
tests are execte$ $ring the test 'i*ecyc'e %aven phase. -he integration tests (si%'ation
rns) taDe p'ace a*ter JES has )een pacDage$ *or $istri)tion an$ on'y execte$ )y
invoDing mvn integration-test
/
. -he si%'ation rns can )e con*igre$ sing the tests.x%'
*i'e 'ocate$ in the src"test"resorce $irectory.
-he ne# si%'ation testing *aci'ity expan$s on its pre$ecessor )y a''o#ing a $yna%ic an$
easi'y con*igra)'e testing session. Speci*ica''y, an :;8 *or%atte$ *i'e entit'e$ tests.x%' is
no# 'ocate$ in the src"test"resorces, that a''o#s setting a%ong other things, #hether to
checD the concrrency capa)i'ities or not. -ests are $e*ine$ #ith a na%e attri)te. 0ne or
%ore tests can )e sDippe$ )y $ec'aring their na%e attri)te in the sDip e'e%ent (sing
either #hitespace, co%%as or $ots as $e'i%iters), instea$ o* re%oving the re'ative no$e(s)
*ro% the x%' tree. -he n%)er o* %essages to )e sent )y each ser, as #e'' as a per ser
repetition cont can )e set. -he D/7ES--;DB re'ate$ (E&8;S entry in the Cava;ai'
e'e%ent a''o#s *or t#o constant va'es or a speci*ic rea'% na%e. -he t#o constants are
KnoneL #hich trans'ates to sing the server e'e%ent va'e as the rea'% an$ K$e*a'tL #hich
$e*a'ts to the realms s)-e'e%ent va'e o* the de(aults e'e%ent to #hich the server va'e
is appen$e$.
-he sa%p'e tests.x%' *i'e inc'$e$ in the appen$ix correspon$s to a 'arge $egree to the 10
tests that #ere execte$ )y previos versions o* JES. -he test cases to )e execte$ )y
invoDing K%vn integration-testL are setting p te%porary instances o* the server )y creating
insta''ation *o'$ers in the syste% $e*ine$ te%porary *o'$er #hose 'ocation is retrieve$
throgh the syste% property KCava.io.t%p$irL. 2hen a'' the cases co%p'ete sccess*''y the
*o'$ers sho'$ )e $e'ete$. .o#ever, i* at 'east one test is $e*ine$ #ith a $) as the
)acDen$, the $er)y instance never rea''y shts $o#n #hen the server.sht$o#n() %etho$
is invoDe$. 0n'y #hen the enve'oping J4; shts $o#n $oes $er)y sht$o#n an$ re'ease
a'' the a''ocate$ resorces. -he i%p'ication is t#o *o'$. &ny tests execte$ a*ter the initia'
one (the *irst to se a $) as the )acDen$) acta''y se the $er)y instance create$ )y this
test. ;oreover, *i'e han$'es are not re'ease$, so #hen the si%'ation rn *inishes a sing'e
*o'$er containing the $er)y instance re%ains in the syste% te%p *o'$er. -his *o'$er sho'$
)e %ana''y $e'ete$.
,ote! a n%)er o* *o'$ers %ay a'so re%ain in case o* a test *ai're.
,e# #ith version 2.8! a ne# D) test rn (11) to veri*y C5C co%%an$s reception an$
exection. &'so, t#o (sDippe$ )y $e*a't) tests (na%e'y d,2memory2pro(iler an$
(ile2memory2pro(iler) %eant to test *or %e%ory 'eaDs have )een a$$e$.
* %r any phase later in the maven build lifecycle, e.g. install.
/.'5 0sin# a recipient polic1 to "andle messa#e recipients
<n$er certain server sage scenarios, it %ay )e $esira)'e to restrict the $o%ains a''o#e$
as %essage recipients either g'o)a''y, or *or a n%)er o* 'oca''y a$%inistere$ $o%ains.
-o#ar$s this en$ a recipient po'icy *i'e has )een p'ace$ in the con*igration $irectory.
Cons't this *i'e9s hea$er *or instrctions on ho# to setp the po'icy.
/.'6 JSSE &e1store pass-ord and4or &erberos 5 principal pass-ords
/n or$er to se a SS8"-8S certi*icate either to spport the S-&(--8S S;-3"303A
extension or to secre the C5C connection the certi*icate has to )e retrieve$ *ro% a
Deystore. -he Deystore pass#or$ has to )e spp'ie$ to JES. -he %eans to $o so is )y
sing a *i'e na%e$ Kpass#or$L
A
create$ in the secrity *o'$er. -he *i'e %st )e pop'ate$
#ith a 'ine that has the Dey"va'e pair KDeystorePpass#or$L. /* the pass#or$ proves
incorrect then a popp #i'' )e $isp'aye$ reNesting it> or a rnti%e exception #i'' )e thro#n
i* the Cv% is gi-'ess.
Fer)eros B pass#or$s are o)taine$ in a si%i'ar *ashion. -he pass#or$ *i'e can again )e
se$. &n entry Kservice,a%ePservice3ass#or$L is reNire$ *or the (each) principa'. /* se
o* a Deyta) is se'ecte$ an$ the Deyta) 'ocation is set then the principa' Dey is retrieve$
*ro% it. /* Dey retrieva' *ai's then the pass#or$ *i'e is 'ooDe$ p. Sho'$ that *ai' the
pass#or$ is reNeste$ sing a popp.
/.'7 JES ;ault and t"e master pass-ord
Starting #ith re'ease 2.B JES s#itches to an scrypt )ase$ syste% to persist a'' secrity
sensitive in*or%ation (Deystore pass#or$, Der)eros B principa'(s) pass#or$(s), the $)
)acDen$ cre$entia's etc).
-he syste% generate$ %aster pass#or$ has )een rep'ace$ )y a ser spp'ie$ one via
either the pass#or$ *i'e or a popp. /t is no 'onger persiste$ )y $e*a't an$ has to )e
spp'ie$ to the syste% at every startp. -he pass#or$ *i'e entry ses the *o''o#ing *or%at!
pass#or$P
-he pass#or$ is there*ore the Dey an$ there is no va'e.
-here is an i%portant note concerning the a)i'ity o* JES to restart. &*ter )eing reNeste$ to
a'ter at 'east one o* its non $yna%ica''y p$ate$ settings, JES sht$o#ns an$ restarts.
Dring the restart process, an$ in or$er not to n''i*y the option o* re%ote'y a$%inistering
JES, access to the %aster pass#or$ is o**ere$ #ithot ser intervention.
- The password file must be encoded in UTF,., should any character be outside the U&,/&0!! range. !f a Unicode
1%2 '34, 14, UTF,.( is present, it is parsed and the encoding is set accordingly.
/.'7.' 0pdatin# t"e master pass-ord
& ne# %aster pass#or$ can on'y )e spp'ie$ )y sing the pass#or$ *i'e. 5oth the o'$ an$
ne# pass#or$ nee$ to )e entere$ an$ have this *or%at!
pass#or$P
ne#.pass#or$P
-he ne# pass#or$ entry has a 'ea$ing Kne#.L part. -he o'$ pass#or$ is nee$e$ *or
veri*ication.
/.'7.* $aster pass-ord stren#t"
/n or$er to %axi%iQe the entropy o* the spp'ie$ %aster pass#or$ a *e# restrictions are
en*orce$. -hese are (in no partic'ar or$er)!
& %ini%% o* 10 'etters"n%)ers"sy%)o's
,o &SC// i''ega' (non printa)'e) characters
&t %ost 2 n%)ers )acD to )acD
&t %ost A (sa%e case) 'etters )acD to )acD
&t %ost 2 ('e*t to right"right to 'e*t) =2E(-6 (<S 'ayot) Dey)oar$
'etters"n%)ers"sy%)o's )acD to )acD
&t %ost 2 repeating $igits or neigh)oring ones (the $i**erence o* their nico$e
co$epoint %st have an a)so'te va'e 'arger than 1).
&t 'east 2 pper case &SC// 'etters on (case-in$i**erent) non-&SC// 'etters "
n%)ers"sy%)o's
,o partic'ar or$er is reNire$, )t avoi$ing sy%)o's"n%)ers at the )eginning or"an$
en$ing is encorage$. 2hen a popp pro%pts *or the %aster pass#or$ a rea' ti%e
strength checDer is provi$e$.
/.'( 0pdatin# t"e bound S$T.4.<./ ports on a runnin# JES instance
-he S;-3"303A ports can )e change$ #hi'e JES is rnning, #ithot restarting it. -his
operation is ho#ever 0S $epen$ent. 0n 2in there is no concept o* privi'ege$ ports,
there*ore any port in the stan$ar$ range (1-?BBAB) can )e se'ecte$. 0n 8inx ho#ever, the
'o#er 1024 ports are $ee%e$ privi'ege$ an$ are se'ecta)'e on'y #hen JES is execte$ )y
the root ser that #as not s)seNent'y $o#ngra$e$. 2hen this con$ition is not he'$ an$ a
privi'ege$ port is in$ee$ se'ecte$, a ran$o% port n%)er s)stittes the port in Nestion.
1rther checDs are a'so carrie$ ot #ith the intent o* avoi$ing port con*'ict ()oth #ith other
JES 'istening processes an$ non-JES ones).
3. T"e Confi#uration $ana#er %ac&End
3.' Introduction
Starting #ith version 2.1.x JES provi$es the option o* persisting the $o%ains, sers an$
$igest-;DB rea'%s either to the *i'esyste% (as #as p to version 2.0.x) or an interna''y
instantiate$ $ata)ase. 1ro% version 2.8.x on#ar$s, certain arg%ents %st )e passe$ in
as JS0, o)Cects"arrays.
0nce the server has )een rn *or the *irst ti%e sing either o* the t#o options there is )t
one #ay to s#itch to the other> %ana''y insert the $o%ain(s)"ser(s)"rea'%(s) to the other
)acDen$.
-he choice has to )e #eighte$ )ase$ on t#o varia)'es! sca'a)i'ity an$ %e%ory
%anage%ent. -he *i'esyste% )acDen$ 'oa$s a'' the $o%ains, sers an$ rea'%s at startp
in the %e%ory. 1or a s%a'' n%)er o* entries it is the i$ea' choice. 5t sho'$ the ser
)ase gro# s)stantia''y, sca'a)i'ity an$ %e%ory isses #i'' %ost $e*inite'y arise. &
$ata)ase )acDen$ #o'$ )e the proper choice in sch an occasion.
/* %e%ory is restricte$ on the syste% one sho'$ consi$er the *act that sing the $ata)ase
)acDen$ increases the %e%ory *ootprint )y at 'east 20 ;i5.
3.* Apac"e derb1
&t the ti%e o* this #riting apache $er)y has )een se'ecte$ as the $ata)ase o* choice.
2hi'st the e%)e$$e$ *'avor #o'$ see% the pre*era)'e choice, it presente$ it se'* #ith a
$i'e%%a to consi$er. -here is no o)vios %anner )y #hich the $ata)ase can )e accesse$
otsi$e the instance J4;. -here*ore the net#orD version o* $er)y has )een se'ecte$.
0n'y a sing'e ser has *'' access to the $ata)ase. -his ser is a'so the $ata)ase creator.
-here can )e on'y one %ore ser $e*ine$ an$ this ser9s access is restricte$ to rea$-on'y.
3.*.' Database "ostin#
-here are on'y three attri)tes reNire$ to )e $e*ine$ in s)section A, o* section ,ac4end
in %ai'.x%' so that $er)y is setp an$ rnning ()arring the secure attri)te speci*ie$ in
section )acDen$ that *orces channe' encryption -see the next s)section- an$ the ser
cre$entia's spp'ie$ via the pass#or$ *i'e-section 4.B). See %ai'.x%' (or %ai'.xs$) *or a
$escription o* these attri)tes.
3.*.* TLS secured connection
5y $e*a't the $ata)ase is a''o#e$ to )e accesse$ *ro% a 'oop)acD, site'oca' or the Qero-
)ase$ a$$ress #ithot any secrity %easres. <nrestricte$ re%ote access is grante$ onl1
)y ren$ering the $ata)ase access secre. /n this case the co%% channe' gets -8S
encrypte$.
Sho'$ the C5C )e se'ecte$ to )e secre, the $ata)ase access is *orce$ to )e secre as
#e''. -he secrity sche%e reNires that the c'ient a'so athenticates itse'*.
3./ Connection%asedConfi#urator
-he ag%ente$ *nctiona'ity o* the C5C a''o#s anyone accessing it to *''y a$%inister the
$o%ains, sers an$ $igest-;DB rea'%s. See the appen$ix *or a *'' 'ist o* the co%%an$s.
3./.' TLS secured connection
5y $e*a't the C5C is a''o#e$ to )e accesse$ *ro% either the 'oca'host or the site 'oca'
a$$ress o* the host #ithot any secrity %easres. <nrestricte$ re%ote access is grante$
onl1 )y ren$ering the C5C secre. /n this case the co%% channe' gets -8S encrypte$.
Sho'$ $ata)ase access )e se'ecte$ to )e secre, access to the C5C is *orci)'y secre as
#e''. -he secrity sche%e reNires that the c'ient a'so athenticates itse'*. -here is no
setting to circ%vent this process. ,o cre$entia's are necessary to connect to the C5C nor
is there a checD on a s)Cect&'t,a%e. (ather, the JES a$%inistrator %st have a C&
certi*icate in the JES trststore that #i'' )e se$ to va'i$ate the c'ient9s certi*icate. Since
any va'i$ certi*icate (that is a c'ient certi*icate isse$ )y a C& #hose trste$ certi*icate is
'ocate$ in the JES trststore) is grante$ access to the C5C an$ )y extension to the
$ata)ase itse'*, the JES a$%inistrator is tasDe$ #ith preventing nathenticate$ access.
-he )est #ay to go a)ot this is to setp a private C& then have it isse an$ sign the JES
server an$ the connecting c'ient9s certi*icates. -he openss' 5SD 'icense$ SS8 site is i$ea'
*or this tasD. & n%)er o* scripts to ato%ate this process (isse a se'*-signe$ C&
certi*icate, *o''o#e$ )y the issing an$ signing o* a server an$ c'ient certi*icates) are
'ocate$ in the openss' *o'$er n$er the JES insta'' $ir. -hese scripts have )een teste$ #ith
)nt9s openss' 0.E8R version. -hese can )e easi'y a$apte$ to rn n$er any 'inx $istro.
-hey can a'so serve as a gi$e to sing openss'9s #in$o#s port.
3.3 Securit1 updates in t"e source
/n or$er to prevent nathoriQe$ access to the C5C, a secrity access checD is per*or%e$
to an inco%ing connection to the C5C 'isten a$$ress that veri*ies that the connecting
a$$ress %atches the a$$ress on #hich the C5C is 'istening to. Sho'$ the a$$ress $i**er a
secrity exception is thro#n. /n a$$ition, the restriction that the con*igration 'istening
a$$ress can on'y )e the 'oca'host or a site-'oca' a$$ress the Ces host can )in$ to (no
$o%ain na%e is a''o#e$) %eans that on'y the host co%pter can access the C5C. -his
stringent approach o)vios'y )'ocDs (or at 'east tries to )'ocD) any re%ote access to the
C5C *or the o)vios reasons. -his approach is a'so Csti*ie$ )y the *act that the C5C at
this ti%e $oesn9t reNire ser cre$entia's in or$er to ena)'e access to the $ata)ase.
3.5 0ser access to derb1
0n'y t#o sers are speci*ie$ #ith access to the $). -he one, #hich is a'so the $) creator,
is grante$ *'' access to the $). -he other, is on'y a''o#e$ rea$ access to the $) an$ as the
entry in %ai'.x%' i%p'ies is to )e se$ )y a gi. Cre$entia's are va'i$ate$ sing a csto%
$er)y athenticator. -hese are spp'ie$ on'y via the <jes-install path>/security/password
*i'e. -he entries are!
)acDen$.$).serna%ePpassword an$ gi.$).serna%ePpassword.
3.5.' 0pdatin# t"e db user credentials
-he $) creator p'ays a niNe ro'e in $er)y ths the speci*ie$ serna%e cannot )e a'tere$.
-he pass#or$ ho#ever can )e change$. 5oth the o'$ an$ ne# cre$entia's nee$ to )e
spp'ie$ an$ the #ay to $o it is to spp'y the o'$ cre$entia's in the sa' %anner
()acDen$.$).serna%ePpass#or$) an$ the ne# ones 'iDe so!
ne#.)acDen$.$).serna%ePnewpassword
,ote the 'ea$ing Kne#.L part in the Dey. -he serna%e has to )e the sa%e.
-he gi ser can )e a'tere$ entire'y. -he t#o entries are!
gi.$).serna%ePpassword
ne#. gi.$).(ne#)serna%ePnewpassword
&gain the Dey part *or the (possi)'y) ne# ser has a 'ea$ing Kne#.L part. -he serna%e
nee$ not )e the sa%e (n'iDe the $) creator case).
3.6 Settin#s not available via t"e C%C
& n%)er o* settings can not )e retrieve$ or %o$i*ie$ sing the C5C *aci'ity, %ost'y on
secrity gron$s. -hese are the settings *or the C5C itse'*, the Cava2rapper section, as
#e'' as the a''o#(e%ote(estart an$ 'egacy1i'e/0;o$e attri)tes in s)section secrity
n$er the genera' section. 1ina''y, no %eans o* speci*ying the )acDen$ type exists, other
than $irect'y %o$i*ying %ai'.x%'.
5. )inal notes
Extensive $oc%entation is provi$e$ #ithin the con*igration *i'es. -ry to gain as %ch
insight into the inner #orDings o* JES )y care*''y rea$ing the%. Don9t )e a*rai$ to asD
Nestions )y posting to the ser %ai'ing 'ist (a s)scription is reNire$). &')eit it sho'$ )e
a 'ast resort.
Appendi+
I. C%C Commands
Ia. C%C Commands in Db mode
-he C5C $oes not *o''o# the co%%an$-rep'y approach as se$ *or instance )y the
s%tp protoco'. (ather, the connecting c'ient isses a co%%an$ *o''o#e$ optiona''y )y the
ite%s that are to )e inserte$ " p$ate$ " $e'ete$ " retrieve$ an$ *ina''y a reNire$ perio$.
Each 'ine o* co%%an$ is ter%inate$ #ith C(81. -here are no restrictions on 'ine 'ength.
-he are t#o genera' syntaxes.
-he *irst one concerns entries in the $ata)ase ($o%ains, sers, rea'%s)!
command<;R5B>
item1:entry1@entry/@entry0<;R5B>
item/:entry)@entryC<;R5B>
itemn:entrym<;R5B>
'<;R5B>
-he secon$ one $ea's #ith the JES con*igration!
apply-or-retrieve con(iguration command<;R5B>
con(iguration-section su,command<;R5B>
DEnew-con(iguration-settings<;R5B>F
'<;R5B>
-he C5C s)%its the reNest *or process. /* the reNest reNires a rep'y that
contains $ata to )e processe$ )y the s)%itter o* the co%%an$ that $ata is appen$e$ *irst
as a JS0, o)Cect in a sing'e 'ine. 0ther#ise a contro' %essage is appen$e$, in$icating
either sccess or *ai're. 1ina''y, a sing'e perio$ is trans%itte$ an$ C5C $rops the
connection.
-he specia' notationa' ite%s +, S an$ T (co'on) are trans'ate$ to! Qero or %ore ite%s,
one or no ite%s an$ exact'y one o* the ite%s respective'y.
& *e# co%%an$s a''o# %'tip'e exections, either as sing'e entries or pairs. -he
specia' R=...> notation is se$ in the K(eNire$ entry isL entry to in$icate that sch an entry
is a''o#e$ to appear %ore than once in a co%%an$. !dding a domain (a) is an exa%p'e o*
%'tip'e exections *or a given co%%an$ an$ Removing Borward !ddresses (h) is a paire$
exa%p'e.
-he *'' co%%an$ 'ist is as *o''o#s!
a. Addin# a domain
-he co%%an$ is insertDomain
(eNire$ entry is R= domain: JS0,&rray o* Udomain2nameV >
Exa%p'e!
insertAomain
domain:EGmydomain1H@ Gmydomain/H@ Gmydomain0HF
domain:EGmydomain)H@ GmydomainCH@ Gmydomain+HF
'
b. Deletin# a domain
-he co%%an$ is deleteDomain
(eNire$ entry is R= domainId: JS0,&rray o* Udomain2idV >
Exa%p'e!
deleteAomain
domainId:E1@/@0F
domainId:E)@C@+@:F
'
c. Settin# t"e default domain
-he co%%an$ is setDefaultDomain
(eNire$ entry is domainId:domain2id
Exa%p'e!
setAe(aultAomain
domainId:1
'
d. Addin# a user
-he co%%an$ is insertUser
(eNire$ entries are R= JS0,0)Cect o* W
username:user2name
password:password
domainId:domain2id
0ptiona' entry is realm:JS0,&rray o* UrealmVX >
Exa%p'e 1 (no rea'%s speci*ie$)!
insert3ser
JGusernameH:Huser1H@ GpasswordH:Hpass1H@ GdomainIdH:1K
JGusernameH:Huser/H@ GpasswordH:Hpass/H@ GdomainIdH:/K
'
Exa%p'e 2!
insert3ser
JGusernameH:Huser1H@ GpasswordH:Hpass1H@ GdomainIdH:1@ GrealmH:EGrealm1H@
Grealm/HFK
'
e. Deletin# a user
-he co%%an$ is deleteUser
(eNire$ entry is %= userId:JS0,&rray o* Uuser2idV >
Exa%p'e!
delete3ser
userId:E1@1/0@)CF
userId:E/C@0LF
'
f. Settin# t"e user pass-ord
-he co%%an$ is setUserPassword
(eNire$ entries are %= userId:JS0,&rray o* Uuser2idV
password:JS0,&rray o* UpasswordV >
'
Exa%p'e!
set3serassword
userId:E1/0@)C@+)F
password:EuserpassC@userpass:@ userpass)F
userId:E/C@0LF
password:Euserpass0@userpassMF
'
#. Addin# for-ard addresses
"he command is addForwardAddress
(eNire$ entries are %= userId:JS0,&rray o* Uuser2idV
forwardAddress:JS0,&rray o* UJS0,&rray o* UaddressVV >
Exa%p'e!
addBorward!ddress
userId:E1@1/0@)CF
(orward!ddress:EEGaddress1H@Gaddress+HF@EHaddressMHF@EHaddress//HFF
'
". Removin# for-ard addresses
-he co%%an$ is removeForwardAddress
(eNire$ entries are %= userId:JS0,&rray o* Uuser2idV
forwardAddressId:JS0,&rray o* Uaddress2idV >
Exa%p'e!
removeBorward!ddress
userId:E1@1/0@)CF
(orward!ddressId:EEaddress12id@address+2idF@EaddressM2idF@Eaddress//2idFF
userId:E+)F
(orward!ddressId:EEaddress0)2idFF
'
i. Settin# t"e default mailbo+
-he co%%an$ is setDefaultMailBox
(eNire$ entries are %= domainId:JS0,&rray o* U$o%ainHi$V
userId:JS0,&rrayo* Uuser2idV >
Exa%p'e!
setAe(ault.ailNo&
domainId:E1CF
userId:EMCF
'
2. Insertin# realms
-he co%%an$ is insertRealm
(eNire$ entries are %= domainId: JS0,&rray o* Udomain2idV
realm:JS0,&rray o* UJS0,&rray o* Urea'%VV >
Exa%p'e!
insertRealm
domainId:E1C@/)F
realm:EEGrealm/H@Hrealm1+HF@Hrealm11HF
.
&. Deletin# realms
-he co%%an$ is deleteRealm
ReOuired entry is %= realmId:JS0,&rray o* Urea'%/$V >
Exa%p'e!
deleteRealm
realmId:E1C@/)F
.
l. Addin# users to realms
-he co%%an$ is addUserToRealm
(eNire$ entries are R= JS0,0)Cect o* W
username:user2name
userId:user2id
domainId:domain2id
password:password
realm:JS0,&rray o* UrealmVX >
Exa%p'e!
add3ser"oRealm
JGusernameH:Huser11H@ GuserIdH::L@ GdomainIdH:00@ GpasswordH:HpassCH@
GrealmH:EGrealm/H@Grealm1+H@Hrealm)CHFK
JGusernameH:Huser1/H@ GuserIdH::M@ GdomainIdH:0)@ GpasswordH:Hpass+H@
GrealmH:EGrealm0H@Grealm1:H@Hrealm)+HFK
'
m. Removin# users from realms
-he co%%an$ is removeUserFromRealm
(eNire$ entries are R=userId:JS0,&rray o* Uuser2idV
realmId:JS0,&rray o* UJS0,&rray o* Urealm2IdVV >
Exa%p'e!
remove3serBromRealm
userId:E:L@C+F
realmId:EE/0@)CF@E1+@)CFF
'
n. Retrieve confi#uration section settin#s
-he co%%an$ is retrieveConfi
(eNire$ entry is !Confi"eneral # ConfiBac$end # ConfiMail #
ConfiDirectories # ConfiAmavis%dnew # Confi&t'er(
Exa%p'e!
retrieve;on(ig
;on(igNac4end
'
o. Appl1 confi#uration section settin#s
-he co%%an$ is appl)Confi
(eNire$ entries are !Confi"eneral # ConfiBac$end # ConfiMail #
ConfiDirectories # ConfiAmavis%dnew # Confi&t'er(
*+,&- &./ect0
Exa%p'e!
apply;on(ig
;on(igNac4end
<JS8P 8,ject>
'
Ib. C%C Commands in )ile mode
<n'iDe in C5C %o$e, #here a *'' set o* contro' co%%an$s exists, there is on'y the
option o* a$$ing a sing'e ser #ith an optiona' rea'%. -hat co%%an$ is!
a. Addin# a user
,ote!"he username is reOuired to contain the domain
-he co%%an$ is add user
(eNire$ entries are R= JS0,0)Cect o*
Wusername:user2name>domain2name
password:password
0ptiona' entry is realm:realmK >
Exa%p'e!
insert3ser
JGusernameH:Huser1>domain1H@HpasswordH:Hpass1H@HrealmH:Hrealm1HK
JGusernameH:Huser/>domain/H@HpasswordH:Hpass/HK
'
II. .ass-ord file entries and t"eir respective 9&e14value: format
'. ;aster pass#or$! pass#or$P
(the ser9s pass#or$ is acta''y se$ as a Dey an$ the va'e is e%pty)
*. Fer)eros B principa'! service,a%ePservice3ass#or$
/. JSSE Dey Deystore! DeystorePpass#or$
(the KDeystoreL #or$ is se$ as a Dey an$ the pass#or$ is the va'e)
3. )acDen$.$).entries! )acDen$.$).serna%ePpass#or$
gi.$).serna%ePpass#or$
III. Sample tests.+ml file
ISx%' versionPG1.0G enco$ingPG<-1-8GSJ
ItestsJ
IsDipJ1I"sDipJ
I$e*a'tsJ
IsettingsJ
%ai'"S;-3>portP1@02B

%ai'"S;-3"athentication"/30verri$e!12@.0.0.1

%ai'"S;-3"athentication"3035e*oreS;-3>
ena)'ePtre
%ai'"S;-3"extensions>.E80P*a'se
%ai'"303A>portP1@110
I"settingsJ
Irea'%sJ
sers
I"rea'%sJ
I"$e*a'tsJ
Itest na%ePG1GJ
I%essages3er<serJ2I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
ICava;ai'J
S&S8PD/7ES--;DB
(E&8;Pnone
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"ath;echs"D/7ES--;DB>ena)'ePtre
I"settingsJ
I"testJ
Itest na%ePG2GJ
I%essages3er<serJ1I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
ICava;ai'J
S&S8PD/7ES--;DB
(E&8;P$e*a't
S-&(--8SPtre
3(0-0C08P-8Sv1
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"S;-3"$e'ivery>interva'P1
%ai'"S;-3"secreChanne'>ena)'ePtre
%ai'"S;-3"athentication>
a''o#C'ear-extPencrypte$0n'y
%ai'"303A"secreChanne'>ena)'ePtre
%ai'"303A"athentication>
a''o#C'ear-extPencrypte$0n'y
%ai'"ath;echs"D/7ES--;DB>ena)'ePtre
I"settingsJ
I"testJ
Itest na%ePGAGJ
I%essages3er<serJ1I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
ICava;ai'J
S&S8P38&/,
S-&(--8SPtre
3(0-0C08P-8Sv1
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"S;-3"secreChanne'>ena)'ePtre
%ai'"S;-3"extensions>pipe'iningPtre
%ai'"303A"secreChanne'>ena)'ePtre
I"settingsJ
I"testJ
Itest na%ePG4GJ
I%essages3er<serJ?I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
I%'tithrea$e$"J
ICava;ai'J
S&S8P38&/,
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"S;-3"$e'ivery>interva'P1
I"settingsJ
I"testJ
Itest na%ePGBGJ
I%essages3er<serJ?I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
I%'tithrea$e$"J
ICava;ai'J
S&S8P38&/,
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"S;-3"$e'ivery>interva'P1
I"settingsJ
I"testJ
Itest na%ePG?GJ
I%essages3er<serJ?I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
I%'tithrea$e$"J
ICava;ai'J
S&S8PD/7ES--;DB
(E&8;P$e*a't
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"S;-3"$e'ivery>interva'P1
%ai'"ath;echs"D/7ES--;DB>ena)'ePtre
I"settingsJ
I"testJ
Itest na%ePG@GJ
I%essages3er<serJ?I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
I%'tithrea$e$"J
ICava;ai'J
S&S8P38&/,
S-&(--8SPtre
3(0-0C08P-8Sv1
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"1i'e"$o%ains!'oca'host

)acDen$"1i'e"$e*a't;ai')ox!an$reasY'oca'host
%ai'"S;-3"$e'ivery>interva'P1
%ai'"S;-3"secreChanne'>ena)'ePtre
%ai'"303A"secreChanne'>ena)'ePtre
I"settingsJ
I"testJ
Itest na%ePG8GJ
I%essages3er<serJ8I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
ICava;ai'J
S&S8P38&/,
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"D)>hostP'oca'host>portP1@B2@
%ai'"S;-3"$e'ivery>interva'P1
%ai'"S;-3"secreChanne'>ena)'ePtre
%ai'"303A"secreChanne'>ena)'ePtre
c)c>ena)'ePtre>portP41002
I"settingsJ
I"testJ
Itest na%ePGEGJ
I%essages3er<serJ?I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
I%'tithrea$e$"J
ICava;ai'J
S&S8P38&/,
S-&(--8SPtre
3(0-0C08P-8Sv1
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"D)>hostP'oca'host>portP1@B2@
%ai'"S;-3"$e'ivery>interva'P1
%ai'"S;-3"secreChanne'>ena)'ePtre
%ai'"303A"secreChanne'>ena)'ePtre
c)c>ena)'ePtre>portP41002
I"settingsJ
I"testJ
Itest na%ePG10GJ
I%essages3er<serJ?I"%essages3er<serJ
Irns3er<serJ1I"rns3er<serJ
I%'tithrea$e$"J
ICava;ai'J
S&S8P38&/,
S-&(--8SPtre
3(0-0C08P-8Sv1
I"Cava;ai'J
IserverJ'oca'hostI"serverJ
IsettingsJ
)acDen$"D)>hostP'oca'host>portP1@B2@
%ai'"S;-3"$e'ivery>interva'P1
%ai'"S;-3"secreChanne'>ena)'ePtre
%ai'"S;-3"athentication>
a''o#C'ear-extPencrypte$0n'y
%ai'"303A"secreChanne'>ena)'ePtre
%ai'"303A"athentication>
a''o#C'ear-extPencrypte$0n'y
%ai'"threa$s>n%)erP8
c)c>ena)'ePtre>portP41002
I"settingsJ
I"testJ
I"testsJ
I;. Supported Aut"entication $ec"anisms 9per operation mode:
JES spports a variety o* athentication %echanis%s. -he co%p'ete 'ist *o''o#s!
Aut"entication $ec"anism S$T. Server S$T. Client?? .<./ Server TLS4SSL???
S&S8 38&/,
Z Z Z (eNire$ )y (1C, ser $e*ine$
807/,
Z Z Z ser $e*ine$
S&S8 C(&;-+
Z Z (;DB on'y) Z optiona'
S&S8 D/7ES--;DB
Z Z Z optiona'
S&S8 SC(&;-S.&-+
Z

Z optiona'
S&S8 7SS&3/
Z

Z optiona'
+ 2hi'e there is no (1C that speci*ies a C(&; %echanis% other than C(&;-;DB, it is
rea''y straight*or#ar$ to se other ;&Cs. -hese are! S.&-1, S.&-2B?, S.&-A84, S.&-
B12. /n the SC(&;-S.&-+ case, (1C B802 a''o#s *or other ;&Cs )esi$es S.&-1. -hese
are! S.&-2B?, S.&-A84, S.&-B12.
++ S;-3 c'ient %o$e is i%p'e%ente$ as S;-3(e%oteSen$er. -he athentication
%echanis%s are %eant to )e se$ #hen the servicing /S3 reNires a'' otgoing %ai' to )e
rote$ throgh its o#n %ai' server an$ ser athentication is %an$atory.
+++ 3'aintext pass#or$s are express'y *or)i$$en )y crrent (1C no%enc'atre n'ess a
-8S"SS8 secrity 'ayer is *irst esta)'ishe$. ,onethe'ess, there is an option ('a)e'e$
a''o#C'ear-ext) in %ai'.x%' that a''o#s their se #ithot a secrity 'ayer.
I;. JES e+ecution ar#uments
JES is 'anche$ )y invoDing the static %etho$ instantiate(StringUV args) *ro% a rnning Cv%
instance or *ro% the co%%an$ 'ine in typica' *ashion (e.g. Cava [
co%.eric$agherty.%ai'.server.;ai' Ispace separate$ arg%ent 'istJ). -here are a n%)er
o* arg%ents that sho'$"can )e passe$ to the app'ication!
&rg%ent 1! JES insta''ation $irectory (reNire$, a)so'te path)
&rg%ent 2-A! -he #or$ KtestingL or a n%)er (#here 0 IP x) that correspon$s to the
$esire$ i$. -he position o* these t#o arg%ents is interchangea)'e.