Installing and Configuring Mail Services M2 Release
THIS IS A DRAFT DOCUMENT FOR A RELEASE THAT ISN'T FINISHED YET, IT IS ONLY OF USE FOR THOSE WORKING FROM THE HEAD OR THE GUYS WRITING THE THING
Overview
These instructions describe the basic installation and configuration of the Mail Services on JBoss milestone 2 (M2) 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 second milestone release of Mail Services can be found here. Download the M2 release as well as JBoss 3.2.6. 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
(optional) ensure that the JBOSS_HOME system variable is set
unzip the mail services release zip into a temporary directory
cd into that directory
chmod 755 install.sh if running on UNIX
run either "./install.sh" or "install.bat" (UNIX vs Windows)
answer the questions.
start JBoss (if you hadn't already)
You should be able to start JBoss with mail services now; however, you do have a bit more work to do.
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
The install process does this for you including the server's domain as well as server.domain. If you need to do it yourself you can follow these instructions. Or skip them if that is acceptable.
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
The installation process asked you to set up a few boxes. If you need more, follow these instructions.
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
The installation asked you if you wished to enable TLS support and even generated a keystore. If you wish to enable it later, follow these instructions.
The communication between Mail Services and your mail client is not encrypted if TLS (or SSL) is not enabled. 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 (does not allow public traffic, so it may not be such a hot idea).
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. The installation process asks you if you want POP over SSL.
Configuring to use MySQL
The installation process will set up MySQL bindings if you select MySQL as your datasource type.
Overview
To configuring to use MySQL as a datastore is not particularly difficult. For the purpose of this documentation we will assume that you have at least set up your database with admin permission.
Setting up the datasource
First SetUpAMysqlDatasource.
Comments