Configuring an Outbound Proxy with Mail Server
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
The content on this page relates to platforms which are not supported for JIRA Applications. Consequently, Atlassian cannot guarantee providing any support for it. Please be aware that this material is provided for your information only and using it is done so at your own risk.
Purpose
This page is a supplement to the KB Configure an outbound proxy for use in Jira server to allow Jira's Java mail functionality to communicate externally through an outbound proxy. This is required to access mail servers outside the network it's hosted in, such as Outlook 365.
If you wish to host JIRA applications behind a reverse-proxy (or inbound proxy), please refer to Integrating JIRA with Apache or Integrating JIRA with Apache using SSL.
For details on configuring Jira http/https requests with an outbound proxy, please refer to Configure an outbound proxy for use in Jira server.
Symptoms
When trying to add an SMTP server through an outbound proxy, the error connect timed out shows up, with no further details, despite turning on mail debugging.
/secure/admin/VerifyPopServerConnection!add.jspa [c.a.j.p.mail.webwork.VerifyMailServer] Unable to connect to the server at outlook.office365.com due to the following exception: java.net.SocketTimeoutException: connect timed outSolution
Java mail has specific JVM parameters when using a mail server through an outbound proxy.
Adding JVM properties
All properties discussed in this article are Java Virtual Machine (JVM) parameters. This article covers the properties needed for proxy configurations, but not where to put them.
JVM properties are set in setenv scripts
To add the parameters to Jira's JVM:
- Modify the relevant startup script (setenv.sh/setenv.bat)
- Restart Jira
For complete instructions on the process of adding properties to the JVM on startup, please see our Setting Properties and Options on Startup documentation. This documentation also explains how to verify the settings have taken effect.
Proxy configuration
Proxy Support is configured in JIRA applications by passing certain system properties to the Java Virtual Machine (JVM) on startup. These properties follow the conventions defined by Javamail/Jakartamail:
- mail.<protocol>.proxy.host
- mail.<protocol>.proxy.port
As an example, the additional arguments to make use of proxy proxy.example.org on port 25000 for SMTP would look like:
-Dmail.imap.proxy.host=proxy.example.org -Dmail.imap.proxy.port=25000