The second part of the screen specifies the Server Details of the SMTP server to which JIRA will send mail. There are two ways you can do this. Either:
- specify the Host Name of your mail server;
or:
- specify the JNDI Location — that is, use JNDI to look up a mail server that you have preconfigured in your application server.
This has the following advantages:
- Better security: the mail details are not available to JIRA administrators through the
JIRA administration interface, and are not stored in JIRA backup files.
- More SMTP options: if you want to use SMTP over SSL (see below), you will need to use JNDI.
- Centralised management: mail details are configured in the same place as database
details, and may be configured through your application server administration tools.
To specify the Host Name,
Most people configure SMTP details directly in JIRA. The form fields are as follows:
| Host Name | Hostname or IP address of your SMTP server. Eg. mail.yourcompany.com |
| SMTP Port | The SMTP port, usually 25 |
| Username | Username to connect as, if your SMTP host requires authentication.
(Most company servers require authentication to relay mail to non-local users.) |
| Password | Password for username (if required by your SMTP host). |
Note
If your server's
startup script uses the "
-Dmail" system properties (e.g. "
mail.smtp.host" or
"
mail.smtp.port"), they will override the settings that you specify in the above form.
Additionally, if necessary you can manually specify the host name that JIRA reports itself as to the SMTP
server by setting
-Dmail.smtp.localhost
Once done, click 'Update' and then "Send a Test Email" to test the connection details.
To specify and configure a JNDI Location,
As an alternative to specifying mail details directly in JIRA, you can configure them in your application
server, and then look up a preconfigured mail session via JNDI.
Complete the following form field
| JNDI Location | The JNDI location of a javax.mail.MailSession object to use when
sending email. |
The JNDI Location will depend on your application server and configuration. For example, in Tomcat 5.5 (the default application server that is bundled with
JIRA Standalone), your JNDI Location
would be java:comp/env/mail/JiraMailServer, and you would add the following section in
conf/server.xml, inside the <Context> node:
<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">
....
<Resource name="mail/JiraMailServer"
auth="Container"
type="javax.mail.Session"
mail.smtp.host="mail.yourcompany.com"
mail.smtp.port="25"
mail.transport.protocol="smtp"
mail.smtp.auth="true"
mail.smtp.user="jirauser"
password="mypassword"
/>
</Context>
Or if you don't require authentication (e.g. if you are sending via localhost, or only internally within the company):
<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">
....
<Resource name="mail/JiraMailServer"
auth="Container"
type="javax.mail.Session"
mail.smtp.host="localhost"
mail.smtp.port="25"
mail.transport.protocol="smtp"
/>
</Context>
The format for other application servers will be similar. For details please see the
Transaction Factory documentation.
If you have problems connecting, add a mail.debug="true" parameter, which will let you see
SMTP-level details when testing the connection.
You will also need to ensure that the JavaMail classes are present in your application server's classpath,
and do not conflict with JIRA's copy. Most J2EE application servers (eg. JBoss, Orion, Weblogic,
Websphere) come with JavaMail, and this may conflict with JIRA's copy, resulting in errors
like:
java.lang.NoClassDefFoundError: javax/mail/Authenticator
or:
java.lang.IllegalArgumentException: Mail server at location [java:comp/env/mail/JiraMailServer] is not
of required type javax.mail.Session.
To fix this, remove WEB-INF/lib/javamail-1.3.2.jar and
WEB-INF/lib/activation-1.0.2.jar from the JIRA webapp.
Lighter app servers (Tomcat, Resin, Jetty (but not JettyPlus)) do not come with JavaMail. For these, you should
move WEB-INF/lib/javamail-1.3.2.jar and
WEB-INF/lib/activation-1.0.2.jar into the application server's lib/ directory, eg.
common/lib/ for Tomcat. This is necessary because the application server is establishing the SMTP
connection, not JIRA, and the application server won't see the jars in JIRA's classloader.
SMTP over SSL
You can encrypt email communications between JIRA and your mail server via SSL, provided your mail server supports
SSL.
To do this, edit your mail server connection properties and specify starttls and SSLSocketFactory, e.g.:
<Resource name="mail/GmailSmtpServer"
auth="Container"
type="javax.mail.Session"
mail.smtp.host="smtp.gmail.com"
mail.smtp.port="465"
mail.smtp.auth="true"
mail.smtp.user="myusername@gmail.com"
password="mypassword"
mail.smtp.starttls.enable="true"
mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
/>
Please note that there is a known bug in some versions of Tomcat 5.5.x (please see
JRA-12180).
Additionally, as you are connecting to an SSL service, you will need to import the SMTP server
certificate into a Java keystore. The process is described on the Connecting
to SSL Services page.
For example, on Linux, you could import a certificate as follows:
$JAVA_HOME/jre/bin/keytool -import -alias jiramailserver -keystore ~/.keystore -file /etc/exim/exim.cert
Enter keystore password: changeit
Owner: O=Atlassian, L=Sydney, ST=NSW, C=AU
Issuer: O=Atlassian, L=Sydney, ST=NSW, C=AU
Serial number: 0
Valid from: Wed Dec 29 13:02:52 EST 2004 until: Sat May 15 12:02:52 EST 2032
Certificate fingerprints:
MD5: 91:EC:6E:EA:73:7A:7C:4F:88:92:A2:A0:2B:F7:BC:CC
SHA1: D8:7C:09:8A:8D:D8:7D:59:C2:28:2A:09:85:90:82:46:78:06:38:D5
Trust this certificate? [no]: yes
Certificate was added to keystore
You would also need to tell Tomcat where the keystore file is located by adding the following to bin/setenv.sh:
export JAVA_OPTS="-Djavax.net.ssl.trustStore=$HOME/.keystore"
