Version 10
Created by acoliver on Aug 10, 2005 10:56 AM. Last modified by acoliver on Jan 30, 2006 5:01 PM.

    How to Install JBoss Mail Server 1.0M3

     

    First Steps

     

    In order to install JBMS 1.0M3 you of course need to download it.  You have two options:

     

     

    The first option is probably best if you are not sure that you have Java installed as your browser will prompt you to get the Java Web Start plugin.  If you get a "corrupted jar" error, this means that your edition of Java Web Start is defective (You're probably on OS X) so grab the download instead.

     

    Requirements

     

    JBMS 1.0M3 requires:

     

    • JDK 1.4.2+ (1.5 aka 5.0 strongly recommended)

    • JBoss 4.03RC1 or later (includes RC2 snapshot)

    • A database and JDBC driver.  PostrgeSQL or Oracle are recommended, MySQL and Hypersonic are supported (read the README regarding issues).  Other databases are supportable but have not been tested and may not work without extra manual configruation.

     

    Next steps

     

    If you have not installed Java, then get it here  If you are running the webstart install, then the installation dialog will automatically pop up.  If you downloaded the installation jar file then locate the directory to which you downloaded it and from a command prompt type:

     

    "java -jar install-jbms-1.0m3-rc1.jar"

     

     

    Installation walthrough

     

    Language

     

    Initially, you will see a language selection dialog.  This release of the installer only supports English but we are planning to provide other languages in future releases.  Select OK.

     

     

    Welcome

     

    From there you'll see a welcome.  Welcome.

     

     

    Read Me

     

    Be sure and read the readme.  There is important information about this release and database driver installation as well as the release notes.

     

     

    License

     

    JBMS is LGPL just like JBoss Application Server.  IANAL, but this means its okay to embed and link to and distribute, but if you change our org.jboss classes or derive your own directly from them and distribute said changes, you must provide us with the source.  For more information on the LGPL consult the Free Software Foundation.  Accept the license and move on.

     

     

    Selecting an installation path

     

    The installer can install a new instance of JBoss Application Server with JBMS embedded or it can install JBMS into an existing instance of JBoss Application Server version 4.03rc1 or later.  Select the JBoss Application Server root directory or where you want the installer to install the JBAS root directory.

     

     

    If you are installing in a new directory (rather than an existing JBAS) you should see this popup:

     

     

    Otherwise, if you are installing in an existing JBAS you should see:

     

     

    Packs

     

    On the next screen you'll be asked what packs you want.  If you are installing over an existing JBoss Application Server instance, do not install (uncheck) JBoss Application Server.  If you are installing in a new location, ensure it is checked.  You should not install JBoss Application Server over an existing instance.  Be sure and read the warning in the readme about securing this instance of JBAS.

     

     

    Configuration Name

     

    You need to specify what configuration of JBAS you want the mail components installed under.  If this is a new instance of JBAS/JBMS then you should accept the "default".  If this is an existing JBAS installation then specify the $JBOSS_HOME/server/xxx subdirectory which contains your "deploy" directory where xxx defaults to "default".  This should be the same value you pass to bin/run.sh -c.  If you do not supply a -c value when starting JBoss then leave it at "default".

     

     

    SMTP Service

     

    If you would like to allow incoming mails to be sent to local users or you would like outgoing mails from local users to be carried over SMTP then enable this service.  The default port is 25; however, on most UNIX based operating systems this will require you to run as root.  See the howto on this topic in order to determine how to run with port 25 as non-superuser.  It is suggested that you leave this as port 25 and run as root for your initial install unless you know enough about things like iptables and more to configure this properly for non-superuser access.

     

    It is suggested that local users should connect via SMTP/SSL (below) or via TLS.  If you wish to allow users to use TLS (basically converts the stream to SSL on demand) then check the TLS Support box.  If you wish to allow incoming mail from the internet then it suggested that you do not Require TLS as that would not allow any mail servers that do not support TLS to sen mail.

     

    There are advanced options to require TLS for authentication that can be configured after installation if you desire.  Or you can consider firewalling port 25 on the local network and only allow port 25 access from the outside network to prevent local users from logging in via clear text and using SMTP/SSL for local userrs.

     

    It is suggested that you leave verify identity checked or any authenticated user can spoof any other authenticated user.

     

     

    SMTP/SSL

     

    SMTP/SSL is not enabled by default.  You may wish to enable it in order to allow local users (defined as users with accounts on this mail server) to send mail to each other and outside over a secure transport.  It is likely the emails will still go out unencrypted when sent over the internet (you do not have control over what other SMTP servers do along the way), but this ensures that the user's account information is secure. 

     

     

    It is suggested that you leave verify identity checked or any authenticated user can spoof any other authenticated user.

     

     

    POP

     

    The next screen allows you to enable POP (POP3) for users to download their email.  While this is the most well supported email protocol for download, it is not very secure.  Because it is ubiquitous and other alternatives are not as well supported it is enabled by default but it is suggested that you do not enable this in favor of POP/SSL (next).

     

    That being said, POP3 can be secure if you enable TLS and require TLS.  However, most email clients (sadly including Mozilla Thunderbird) do not support the STARTTLS command necessary to do this.  Thunderbird supports a "Secure Authentication" option for POP (APOP) that just passes the password encrypted rather than the stream, however it is suggested that it is not actually  very secure and that TLS or SSL is preferred.  We will support APOP in the future but will continue to recommend its disuse.

     

    If you have a mail client that supports it then we recommend TLS/RequireTLS if you enable POP.  If you have a mail client that does not support POP/SSL (Thunderbird does) nor POP+TLS then you may enable this service but realize that passwords are passed in clear text and subject to packet sniffing!

     

     

    POP/SSL

     

    POP/SSL is not enabled by default but is the recommended method for users to download email because it is secure and enjoys wide support.  We suggest that you enable this instead of POP.

     

     

    DNS Configuration

     

    On Windows you must configure at least 1 (2 or 3 are recommended) DNS server to look up mail server ip's and MX records.  On most varieties of UNIX (including OS/X and Linux) you need not supply any (but can at your option) and the default route will be used.

     

     

    Server Name Configuration

     

    On the next screen you can configure your local domains.  Presently mail is accepted for any user with a local account only if the domains you list follow the @ sign in the email address.  Meaning if I put "jboss.org" and "mail.jboss.org" then mail to test@jboss.org or test@mail.jboss.org would BOTH go to that user's account.  If I put test@foobar.jboss.org or test@mail then the mail would be rejected.

     

    Next you should specify the DNS name of your mail server.  The bind address (meaning if you have 2 ips and only want JBMS services to be available on 1 you can specify that IP here.  More advanced combinations are available post-installation.) and the postmaster's address.

     

    If you are just testing then you can probably use the values in the screenshot below. However in general you should have a DNS matching the server name and an MX record for each "local domain".

     

     

    Datastore Configuration

     

    On the next screen, you can configure your datastore.  JBMS is designed to be used with a database and considerable effort has gone into optimizing it as such.  The installer can configure a new datasource or you can specify an existing datasource.  If you leave it at the defaults then it will use (unless you have reconfigured it) the DefaultDS distributed with JBoss which is a simple in-memory database called Hypersonic.  We do not recommend that datasource for production use. 

     

    If you configure it to use an existing datasource then ensure the "generate" is unchecked.  If you want to use one of the databases below and want the installer to generate the datasource (basically a description to the appserver required to connect to that databse) then check the option to generate the database and select from the radio buttons below.  For this release you will still need to copy your JDBC driver (distributed by your vendor) in the $JBOSS_HOME/server/$CONFIGNAME/lib directory by hand.  In the next release we will distribute the PostgreSQL and MySQL JDBC drivers (we cannot distribute the Oracle JDBC driver due to licensing restrictions).  If you use Hypersonic, its driver comes with JBoss.

     

    If you're just testing, then accept the defaults.

     

     

    Keystore

     

    JBMS requires a keystore/certificate for the SSL and TLS services.  This screen will allow you to generate a self signed certificate.  While this is fine for small organization and internal users, it will cause a warning to come up telling them that the certificate is not trusted.  We suggest that ultimately you should buy a certificate from Verisign or Thawte (Verisign is a JBoss customer/partner and they own Thawte so use one of those cause they are our friend :-D), however, it will work with the self-signed cert. 

     

    Keystore generation is specified by default.  You can always change this manually post-installation, but you MUST have a keystore/cert to use SSL/TLS services.

     

     

    Accounts

     

    By default the installer uses a static XML UserRepository requiring restart of JBMS (but not JBAS) to add/change user security information.  While this is fine for testing, more advanced options are available post-install (see the main installation page for options under HOWTOs). 

     

    This screen allows you to define a few starter accounts, you can configure more accounts manually post installation.

     

     

    Pack installation

     

    Next, you should see this screen.  If any errors pop up, please speak up in the forum

     

     

    Success

     

    Finally you should see this:

     

     

    At present the "generate an automatic installation script" is not functional due to bugs in izPack.  We will fix this for a future release.

     

    Starting

     

    Change directory to your JBOSS_HOME (where you selected as the installation directory).  Type sudo bin/run.sh -c confignamespecifiedabove (or sudo bin/run.sh with no option for the "default" config).  If you run as root you do not need "sudo". 

     

     

    You should see JBAS start and deploy the mail server components with no errors:

     

     

    On windows replace the above with "cd bin[Enter|enter]", "run.bat -c confignamespecifiedabove[Enter|enter]".

     

    Next Steps

     

     

    4576 Views Categories: Tags: