Version 6

    Installing and Configuring Mail Services M2 Release






    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 if running on UNIX

    • run either "./" 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.




    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
    Connected to badmojo.
    Escape character is '^]'.
    220 SMTP Server (JBMAIL SMTP Server version 0.1) ready April 7, 2004 6:02:59 PM EDT


    And for POP:


    > telnet badmojo 110
    Connected to badmojo.
    Escape character is '^]'.+OK POP3 Server (JBMAIL POP3 Server version 0.1)  null


    Set up the local domains





    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. 





    Find this sniplet:


      <mbean code="org.jboss.mail.domaingroup.DomainGroup"
         <attribute name="Domains">


    This means that mail services will handle mail for any address with localhost, or as the part of address after the "@" sign.  if we omit the second domain then "me@localhost" would work, "" would work, but "" would not.  You can decide which behaviors you want.  Add your domains to this list and remove the sample domains.


    Set up mailboxes




    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 and so forth.  You define these mailboxes for the users you want in the same descriptor. 




    Just below the local DomainGroup you should find this sniplet:


      <mbean code="org.jboss.mail.userrepository.StaticUserRepository"
         <attribute name="Users">


    Add the users that you want and remove the example users.  The above means that "", "" and "test@localhost" would all go to the test user's mailbox.  It also means that "testpw" is the password for this user.




    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: and, Mail Services would answer port 25 and 110 on BOTH addresses as well as your loopback address:  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 = all or localhost means only the localhost  -->
         <attribute name="Address"></attribute>


    Change the 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 = all or localhost means only the localhost  -->
         <attribute name="Address"></attribute>


    Change 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=""
           <arg type="java.lang.String" value="Mail+SSL"></arg>
        <attribute name="KeyStoreURL">mailservice.keystore</attribute>
        <attribute name="KeyStorePass">rmi+ssl</attribute>


    Change the value of the KeyStoreURL attribute to the name of your keystore file, and set KeyStorePass to the password of your keystore.



    To enable TLS for SMTP modify the SMTPProtocol entry in jboss-service.xml. Find the following sniplet:

      <mbean code="org.jboss.mail.smtp.SMTPProtocol"


    Under this you should see the following:


       <attribute name="SecurityDomain">java:/jaas/Mail+SSL</attribute>

    make sure it is uncommented. A bit further down you will find the following lines:

        <!-- change to true for TLS support -->


    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).



    To enable TLS for POP you modify the POP3Protocol entry in jboss-service.xml. Find this sniplet:

      <mbean code="org.jboss.mail.pop3.POP3Protocol"


    Under this you should see this line:

      <attribute name="SecurityDomain">java:/jaas/Mail+SSL</attribute>

    Make sure it is uncommented. A bit further down you will find the following line:


    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. 




    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.