How to Install JBoss Mail Server 1.0M4
versions: 1.0M4
First Steps
In order to install JBMS 1.0M4-pre1 you of course need to download it. You have two options:
go to the Java Web Start install of JBoss Mail Server 1.0m4-final (JDK5)
go directly to the download of JBoss Mail server 1.0m4-final (JDK5)
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.0M4 requires:
JDK 5.0 (aka 1.5) - lastest stable build recommended
JBoss 4.03SP1 or later (includes SP1)
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.
note: for the 1.0M3 installation all screens were caputred on the OS X platform, for the 1.0M4 release all screenshots are from the Windows platform (2000)
-
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.0m4-pre1.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. Windows users do not need to be concerned with the issue of running as root as Windows does not require special access to control ports.
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 send mail. If you wish to ONLY require TLS for authentication, then select TLS required for authentication.
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 users. For this setup uncheck "authentication allowed". Doing this means that local users will NOT be able to send mail using this SMTP instance. They must used SMTP/SSL (configured next).
It is suggested that you leave verify identity checked or any authenticated user can spoof any other authenticated user.
If you are confused just accept the default settings.
-
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.
If you are confused just accept the default settings.
It is suggested that you leave verify identity checked or any authenticated user can spoof any other authenticated user.
-
SMTP Relaying
If you wish to allow unauthenticated users to send mails to your SMTP server and then have those mails automatically relayed to an external server, you should enable SMTP relaying. JBMS requires you to statically define each host that you will allow relaying to. Although you can define about 2 billion relay domains, the installer only allows you to define 4 (see DefiningAdditionalRelayDomains).
If you do not know what this means, accept the default settings.
-
SMTP Route
If you wish for mails sent to your SMTP server to be routed through a gateway SMTP server, check "Enable SMTP Routing" and define an SMTP gateway host. This will cause all mails to be sent through the defined server unless you check "Route only the below domains" and define the domains you wish to route. Again the installer limits you to four despite the posibility of nearly 2 billion (see DefiningAdditionalRouteDomains). It is common to declare specific routes for mails that you enabled previously in SMTP Relaying. It is also possible to declare multiple gateway servers for different sets of domains (see DefiningAdditionalRouteDomains).
It is unlikely that you need this option. If it confuses you, just accept the default settings.
-
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.
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.
If you are confused, enable this and move on
-
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. If you do not know your DNS server consult this article.
If you are on UNIX and are confused, accept the default options. If you are on Windows and are confused, read the above linked article, learn the ip of your DNS server and specify it here before moving on
-
Server Name Configuration
On the next screen you can configure your local domains. The behavior of local domains has changed from the previous release. Mails are now accepted for any local domain only if there is a user mailbox with an alias which references that domain. List EVERY domain that you wish to allow mails to be sent to (meaning both mail.foo.org and foo.org if you wish to allow mails to me@mail.foo.org and me@foo.org).
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. see EnablingTwoOrMoreIPAddresses) 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".
You must set at least one local domain and your server name. The rest can be accepted but it is strongly recommended that postmaster be postmaster@yourlocaldomain
-
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 unless you are using MySQL or PostgreSQL (which were among the initial packs you could select). In this release we 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 and is already included.
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. This screen does not automatically create mailboxes for each of those accounts. Presently you must do this post-installation. In previous releases an email address and an account were the same where the account was prepended to any of the local domains. This is no longer true. Now accounts will have access to a single mailbox but the mailbox may have multiple aliases (test.user@jboss.org and test.user@jboss.com for instance).
if you are confused create an account called testuser with a password of your choosing and move on
-
Fetchmail configuration
Some users have their mail originate on an outside mail server which they wish to download to their local mailserver. This allows you to configure your JBMS server to regularly poll an external server for mail. Enable this by checking "Enable Fetchmail" and specifying these:
External POP3 server - the remote mail server JBMS should connect to on your behalf (address or IP)
External POP3 port - the port (usually 110)
External POP3 account - the user name you would connect to with a mail client
Password for external POP3 account - the password
Local account email address - the email address of the local mailbox you wish the retrieved mail deposited into.
Leave on external server - generally mail is deleted after retrieval. You might be paranoid the first time you do this so you can allow the mail to be left on the server.
poll frequency in seconds - JBMS will connect and check to see if there are new mails every so often. It is recommended that this number be as large as you can stand so that you don't unduly tax the remote server.
-
Packs installing
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". (Windows instructions below)
You should see JBAS start and deploy the mail server components with no errors:
On Windows replace the above with
"bin\run.bat -c confignamespecifiedabove[enter]"
. NOTE: There is a bug in the run.bat script in this release that will not allow it to be started from the $JBOSS_HOME/bin directory. You must start it from the $JBOSS_HOME directory. This is not an issue on UNIX/Linux.
-
Creating Mailboxes and aliases
In the 1.0M3 release any mail sent to any account on any local domain went to the same mailbox. Meaning if I had two local domains (localhost and localhost.localdomain) then mails sent to andy@localhost and andy@localhost.localdomain would go to the same mailbox retrieved by the account labeled "andy". In 1.0M4 this has changed. Accounts and email aliases are no longer equivilant. Email aliases are associated with mailboxes. Multiple aliases may be assigned to a mailbox but only one account may be assigned to a mailbox.
To create a mailbox open the ] for your JBMS instance. If it is on your localhost it would be found at http://localhost:8080/jmx-console. You should see a screen like this:
Hold down the CTRL key while pressing F (CTRL-F). This will bring up the find dialog. Type "mailboxmanger".
Click on the MailboxManager link and you should see this screen:
Now press CTRL-F again and type createMailbox which will scroll you here:
If you had created an account called "test" then create a mailbox with the alias test by typing it into the field like this:
Click "invoke" and you will see this screen:
This means that you have created a mailbox for the user "test". He still can't get mail, we need to assign email addresses to him.
Press the back button and type CTRL-F and type "getMailboxId":
Type test in that field, click invoke and you should see a screen with a number like this:
This is the actual ID of the mailbox. We need it in order to create an alias. Click back on your browser and press CTRL-F. Then type: "createAlias". Enter the id in the id field and "test@localhost" (for instance) in the alias field.
click invoke and you should see the word true (meaning it was successful):
Now you should be able to send and receive mails for the user "test@localhost". You can actually give the mailbox as many aliases as you like and they will all be retrievable by using a POP client and assigning the user "test". In fact you could give the mailbox the alias "ilikecheese@localhost" and it should work (supposing localhost is a local domain).
Admittedly this process is a bit laborious and the savy user may capture the resulting database activity in scripts (see DatabaseScriptForCreatingAMailboxInJBMS1.0M4) and use those instead. In a future release we will have a graphical administration interface for doing so.
-
Next Steps
HowToConfigureOutlook2000ForUseWithJBossMailServer1.0M4 - Lookout! Here come your mails...careful not to click on those attachements. (seriously, Outlook is a security hole, but if you really really must)
HowToConfigureMozillaThunderbirdForUseWithJBossMailServer1.0M3 - Now you probably want to test or start using JBMS (applies to M4 too).
SecureTheJmxConsole - you don't want everyone on the internet creating mailboxes do you?
HowToRunJBossMailServerWithoutSuperuserAccess - You may not "really" want to run as root eh?
HowToConfigureJAASIntegrationForJBossMailServer1.0M4 - This StaticUserRepository was fun, but LDAP and DBMS-based security are a whole lot more versital.
-
see also: JBMSInstallingM4 for more FAQs a and info
Comments