Installing and Configuring Mail Services M1 Release
Overview
These instructions describe the basic installation and configuration of the Mail Services on JBoss milestone 1 (M1) release. This release is primarily for early adopters, beta testers, open source enthusiasts, people who really need it and masochists. This can be considered an alpha quality release and many changes are yet to come. Its intent on roughing out the edges and fascillitating the development of Mail Services, and may have significant bugs and missing features.
These instructions are for a single node mail server not running in a netboot or clustered configuration.
Basic instructions
First things first
The first milestone release of Mail Services can be found here. Download the M1 release as well as JBoss 3.2.4RC1. Note, on most UNIX systems using the default SMTP/POP ports, you'll need to start JBoss as root (ports below 1000 require it). You may also need to ensure sendmail or your default postmaster is not listening on port 25.
Install JBoss in the usual way
ensure that the JBOSS_HOME system variable is set
unzip the mail services release zip or tar.gz into a temporary directory
move or copy recursively the deploy/mail.ear to $JBOSS_HOME/server/default/deploy
You should be able to start JBoss with mail services now; however, you do have a bit more work to do.
The following changes have to be made in $JBOSS_HOME/server/default/deploy/mail.ear/mail.sar/META-INF/jboss-service.xml
Set your server name
SMTP
Find the following sniplet:
<mbean code="org.jboss.mail.smtp.SMTPProtocol" name="jboss.mail:type=MailServices,name=SMTPProtocol">
Under this you should see this line:
<attribute name="Properties"> <properties> <property><name>servername</name><value>localhost.localdomain.com</value></property>
Set this to the full DNS name of your server or its IP address.
POP
Next, find this sniplet:
<mbean code="org.jboss.mail.pop3.POP3Protocol" name="jboss.mail:type=MailServices,name=POP3Protocol">
Under this you should see this line:
<attribute name="Properties"> <properties> <property><name>servername</name><value>localhost.localdomain.com</value></property>
Change it as well.
Testing
Now that you've set the server, you should be able to connect to the SMTP port. Restart JBoss and give it a try (replace badmojo with your servername or ip):
> telnet badmojo 25 Trying 192.168.1.103... Connected to badmojo. Escape character is '^]'. 220 badmojo.superlinksoftware.com SMTP Server (JBMAIL SMTP Server version 0.1) ready April 7, 2004 6:02:59 PM EDT
And for POP:
> telnet badmojo 110 Trying 192.168.1.103... Connected to badmojo. Escape character is '^]'.+OK badmojo.superlinksoftware.com POP3 Server (JBMAIL POP3 Server version 0.1) null
Set up the local domains
Explanation
Mail Services defines "DomainGroups" which are essentially just lists of fully qualified servernames as well as domain names. Presently, Mail Services uses only one DomainGroup to define the "local" domains. Local domains are those domains for which the server will handle mail. Meaning the server will not deliver mail to any address with some other domain after the "@" sign.
Execution
Find this sniplet:
<mbean code="org.jboss.mail.domaingroup.DomainGroup" name="jboss.mail:type=MailServices,name=DomainGroup,group=Local"> <attribute name="Domains"> <domains> <domain>localhost</domain> <domain>localhost.localdomain.com</domain> <domain>localdomain.com</domain> </domains> </attribute> </mbean>
This means that mail services will handle mail for any address with localhost, localhost.localdomain.com or localdomain.com as the part of address after the "@" sign. if we omit the second domain then "me@localhost" would work, "me@localdomain.com" would work, but "me@localhost.localdomain.com" would not. You can decide which behaviors you want. Add your domains to this list and remove the sample domains.
Set up mailboxes
Explanation
Mail Services will eventually allow you to store users in the database, LDAP, etc. For now we require a simple static definition. Eventually we plan to allow multiple users to access a given mailbox and to restrict a user to a given domain. Presently mail to me@localhost goes to the same address as me@localhost.localdomain.com and so forth. You define these mailboxes for the users you want in the same descriptor.
Execution
Just below the local DomainGroup you should find this sniplet:
<mbean code="org.jboss.mail.userrepository.StaticUserRepository" name="jboss.mail:type=MailServices,name=UserRepository,uimanageable=true"> <attribute name="Users"> <users> <user><id>acoliver</id><password>test</password></user> <user><id>test</id><password>testpw</password></user> <user><id>jboss</id><password>jbosspwd</password></user> <user><id>eric</id><password>test</password></user> <user><id>mikea</id><password>test</password></user> <user><id>mikek</id><password>test</password></user> <user><id>kabir</id><password>test</password></user> </users> </attribute> </mbean>
Add the users that you want and remove the example users. The above means that "test@localdomain.com", "test@localhost.localdomain.com" and "test@localhost" would all go to the test user's mailbox. It also means that "testpw" is the password for this user.
Testing
Give it a try! Connect to your server with your favorite mail client.
Advanced instructions
Restricting the bind address
By default SMTP and POP will be listening on every available address for the server. For example, if you have two ethernet cards with the addresses: 192.168.1.1 and 192.168.2.1, Mail Services would answer port 25 and 110 on BOTH addresses as well as your loopback address: 127.0.0.1. This may or may not be what you want. To restrict mail services to one address edit the following:
For STMP
Find this sniplet:
<attribute name="Protocol">jboss.mail:type=MailServices,name=SMTPProtocol</attribute> <!-- port to listen on --> <attribute name="Port">25</attribute> <!-- which addresses to listen on 0.0.0.0 = all or localhost means only the localhost --> <attribute name="Address">0.0.0.0</attribute>
Change the 0.0.0.0 to the address that you want SMTP to answer on!
Remember, you do not need to do this if you want it to listen on all addresses.
For POP
Find this sniplet:
<attribute name="Protocol">jboss.mail:type=MailServices,name=POP3Protocol</attribute> <!-- port to listen on --> <attribute name="Port">9999</attribute> <!-- which addresses to listen on 0.0.0.0 = all or localhost means only the localhost --> <attribute name="Address">0.0.0.0</attribute>
Change 0.0.0.0 to the address that you want POP to answer on!
Remember, you do not need to do this if you want it to listen on all addresses.
TLS Support
By default the communication between Mail Services and your mail client is not encrypted. This is bad as it means any idiot with a packet sniffer can get your password or even just sit and watch what comes accross the wire as you read your mail! Fortunately, Mail Services already supports encryption through TLS and SSL.
First CreateAKeystore with certificates set up for the server names you used under SMTP and POP. Include the keystore file in the root of mail.sar which is contained in mail.ear.
Uncomment the following section of the jboss-service.xml file:
<!-- The SSL domain setup --> <mbean code="org.jboss.security.plugins.JaasSecurityDomain" name="jboss.security:service=JaasSecurityDomain,domain=Mail+SSL"> <constructor> <arg type="java.lang.String" value="Mail+SSL"></arg> </constructor> <attribute name="KeyStoreURL">mailservice.keystore</attribute> <attribute name="KeyStorePass">rmi+ssl</attribute> </mbean>
Change the value of the KeyStoreURL attribute to the name of your keystore file, and set KeyStorePass to the password of your keystore.
SMTP
To enable TLS for SMTP modify the SMTPProtocol entry in jboss-service.xml. Find the following sniplet:
<mbean code="org.jboss.mail.smtp.SMTPProtocol" name="jboss.mail:type=MailServices,name=SMTPProtocol">
Under this you should see the following:
<depends>jboss.security:service=JaasSecurityDomain,domain=Mail+SSL</depends> <attribute name="SecurityDomain">java:/jaas/Mail+SSL</attribute>
make sure it is uncommented. A bit further down you will find the following lines:
<property><name>requireSTARTTLS</name><value>false</value></property> <property><name>requireClientCert</name><value>false</value></property> <!-- change to true for TLS support --> <property><name>tls-enabled</name><value>false</value></property>
To enable TLS, set tls-enabled to true. To make sure that all communcation with the SMTP server takes place via TLS, set requireSTARTTLS to true.
POP
To enable TLS for POP you modify the POP3Protocol entry in jboss-service.xml. Find this sniplet:
<mbean code="org.jboss.mail.pop3.POP3Protocol" name="jboss.mail:type=MailServices,name=POP3Protocol">
Under this you should see this line:
<depends>jboss.security:service=JaasSecurityDomain,domain=Mail+SSL</depends> <attribute name="SecurityDomain">java:/jaas/Mail+SSL</attribute>
Make sure it is uncommented. A bit further down you will find the following line:
<property><name>tls-enabled</name><value>false</value></property>
To enable TLS, set tls-enabled to true.
TLS support in clients is not actually very common for POP. Therefore we also offer SSL support.
TODO: How to enable SSL
Comments