JIRA 4.0 : Configuring JIRA to Send SMTP Mail
This page last changed on Oct 01, 2009 by alui.
To enable JIRA to send notifications about various events, you need to first configure JIRA to send SMTP email. On this page: 1. Define the SMTP Mail Server
2. Specify the Host Name or JNDI LocationThe 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:
To specify the Host Name,Most people configure SMTP details directly in JIRA. The form fields are as follows:
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
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 SSLYou 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" TroubleshootingA useful tip for debugging mail-related problems in JIRA is to set the -Dmail.debug=true property on startup. This will cause protocol-level details of JIRA's email interactions to be logged. Additionally, turning up JIRA's log level will show when the service is running and how mails are processed. Common Problems
Getting HelpIf you cannot resolve a problem yourself, please create a support case in the 'JIRA' project and we will assist. |
![]() |
Document generated by Confluence on Oct 06, 2009 00:25 |