Documentation for JIRA 6.4 (This documentation includes the project navigation sidebar). Not using this? See below:
(JIRA 6.4 without sidebar documentation | JIRA 6.3.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

Atlassian applications allow the use of reverse-proxies within our products, however Atlassian Support does not provide assistance for configuring them. Consequently, Atlassian can not guarantee providing any support for them.

If assistance with configuration is required, please raise a question on Atlassian Answers.

This page describes how to integrate Apache HTTP Server (also referred to as httpd) with JIRA, utilising mod_proxy & mod_ssl so that Apache operates as a reverse-proxy over HTTPS. If a HTTP configuration is required, please see our Integrating JIRA with Apache documentation. Configuring Apache allows for running JIRA on non-standard HTTP port (such as 8080) and users will be able to access JIRA over standard HTTPS as their traffic will be routed through the proxy and encrypted outside of the network.

Apache can be configured to allow access to JIRA in any of the following methods:

This means the SSL certificate will be managed within Apache and not Tomcat, additionally the connection between Apache and Tomcat will not be encrypted. However, the connection between the browser and the outside network will be encrypted. This is suitable for configurations where the JIRA server is within the same network as the Apache server and is illustrated below:

Client Browser -> HTTPS -> Apache Proxy -> HTTP -> Tomcat (JIRA)

This is a common configuration for networks with multiple SSL certificates and/or web applications as they are all managed in one location (Apache).

If a more complicated solution is required, refer to the Apache HTTP Server Version Documentation, consult with the Apache SME within your organisation and if need be raise a question on Atlassian Answers or look at getting in touch with one of our Atlassian Experts.

 Expand for an example of a common Apache configuration
  1. JIRA is running on port 8080 on a server within the LAN that cannot be accessed externally (the router/firewall is not forwarding port 8080 to it).
  2. Apache is set up on another server (or the same server as JIRA) that can be accessed externally on HTTPS (443).
  3. Apache is then accessed over HTTPS on the appropriate URL (VirtualHost), routing the traffic to and from the JIRA server.

Before you begin

(warning) It is expected that the SSL certificate has been signed by a CA and is in the PEM format prior to configuring Apache. For assistance preparing and generating SSL certificates, please consult with a SSL Vendor (for example, GoDaddy, Verisign, RapidSSL).

Identifying whether to use a domain, subdomain or context path largely depends on the type of SSL certificate provided and also any business rules around website configurations. For SSL to function without error, the domain must match the Common Name (CN) of the certificate.

 Expand for further information on configuring the FQDN to match the certificate's CN

This table indicates which URLs will work with the certificate CN and also makes a recommendation on the URL to use.

A certificate that has a CN with an asterisk (*) in it is a wildcard certificate and can support any subdomain of that domain. If you are uncertain about the URL to use, please consult with your System Administrator and the SSL vendor that provided the certificate.

Step 1: Configure Tomcat

  1. Stop JIRA.
  2. (Optional: If JIRA does not require a context path, skip this step.)

    Edit Tomcat's server.xml to include the required JIRA context path. The below example uses path="jira" - this means JIRA is accessible on http://jiraserver:8080/jira given the default JIRA port is used.

    (info) Ensure the path value is set with a prepending forward slash (/) . For example, path="/jira" rather than path="jira".

  3. Edit Tomcat's server.xml to include a separate connector to proxy the requests. This requires the schemeproxyName, proxyPort & secure attributes. Replace them with the appropriate domain and port of the proxy, as in the below example:

    (info) The proxyName parameter should be set to the FQDN that the JIRA server will be accessed on - for example jira.example.com if accessing it on https://jira.example.com or example.com if accessing it on https://www.example.com/jira. It should not include the context path.

  4. Disable any redirections within Tomcat to HTTPS if they have been enabled - for example the changes to WEB-INF/web.xml in Running JIRA over SSL or HTTPS will cause errors when using the standard HTTP connector as it does not and should not have secure="true" set.
  5. Start JIRA.
  6. Test that JIRA is accessible on the normal connector, using a context path if applicable - for example http://jiraserver:8081/jira.
  7. Test that the new connector is working by accessing JIRA on the appropriate proxy connector, for example http://jiraserver:8080/. This should redirect to the proxy FQDN (in this example, https://jira.atlassian.com), which will fail as the proxy is not yet configured. The test is to ensure Tomcat is set up to correctly redirect to the proxy.

We use two different Tomcat connectors so that testing can be done on JIRA, bypassing the proxy when needed as this is a useful step when troubleshooting. It is expected that the standard connector will not be allowed external access from outside the network (the firewall will not forward any ports to it).

Step 2: Configure Apache HTTP Server

The installation of Apache and configuration of a DNS is not covered in this documentation. Additionally, it is assumed that Apache 2.2 has been installed and DNS entries have been configured for the JIRA domain. As Apache's configuration is specific to the operation system that is used, only some distributions and their configurations are currently documented.

2.1 Enable the Proxy Modules

Debian/Ubuntu
 Expand to see Debian/Ubuntu instructions
  1. Enable the module with the following:

  2. Restart Apache.
Windows/Other OS
 Expand to see Windows/Other OS instructions
  1. Locate and edit the httpd.conf file, adding the below lines if they do not already exist:

  2. Restart Apache.

2.2. Configure Apache to use those Modules

Debian/Ubuntu
 Expand to see Debian/Ubuntu instructions
  1. Switch into user root.
  2. Backup the existing site or create a new one. Creating a new site is not covered within this documentation (copying the default should be sufficient).
  3. Modify the existing site within $APACHE_INSTALL/sites-available, for example default-ssl.
  4. Add the following inside the VirtualHost, replacing jiraserver with the hostname of the JIRA server and also modifying the port if required.

    On its own domain or subdomain:
    # JIRA Proxy Configuration:
    <Proxy *>
            Order deny,allow
            Allow from all
    </Proxy>
    
    SSLProxyEngine          On
    ProxyRequests           Off
    ProxyPreserveHost       On
    ProxyPass               /       http://jiraserver:8080/
    ProxyPassReverse        /       http://jiraserver:8080/

    (info) Missing a forward slash at the end of the URL will cause proxy errors - ensure this is in place!

    Using a context path:
    # JIRA Proxy Configuration:
    <Proxy *>
            Order deny,allow
            Allow from all
    </Proxy>
    
    SSLProxyEngine          On
    ProxyRequests           Off
    ProxyPreserveHost       On
    ProxyPass               /jira       http://jiraserver:8080/jira
    ProxyPassReverse        /jira       http://jiraserver:8080/jira

    (info) The path used must be identical to the Tomcat context path. For example, forwarding /jira to /jira520 cannot be done without considerable rewrite rules that are not always reliable.

  5. Enable the site with the following:

  6. Copy the certificate and private key to the appropriate directories.
  7. Include them in the Apache configuration, within the VirtualHost as below:

    SSLCertificateFile    /etc/ssl/certs/jira.crt
    SSLCertificateKeyFile /etc/ssl/private/jira.key
  8. (OPTIONAL): Configuration of SSLCertificateChainFile will contain the intermediate certificates provided by the CA vendor who signed it. Please follow consult with the CA vendor to verify if this is required.

    SSLCertificateChainFile /etc/ssl/certs/jiraintermediate.crt
  9. Reload the Apache configuration.
  10. Test by accessing JIRA through Apache, for example http://jira.com or http://atlassian.com/jira.
Windows/Other OS
 Expand to see Windows/Other OS instructions
  1. Locate and edit the httpd.conf file.
  2. Add the following inside the VirtualHost, replacing jiraserver with the hostname of the JIRA server and also modifying the port if required.

    On its own domain or subdomain:

    # JIRA Proxy Configuration:
    <Proxy *>
            Order deny,allow
            Allow from all
    </Proxy>
    
    SSLProxyEngine          On
    ProxyRequests           Off
    ProxyPreserveHost       On
    ProxyPass               /       http://jiraserver:8080/
    ProxyPassReverse        /       http://jiraserver:8080/

    (info) Missing a forward slash at the end of the URL will cause proxy errors - ensure this is in place!

    Using a context path:

    # JIRA Proxy Configuration:
    <Proxy *>
            Order deny,allow
            Allow from all
    </Proxy>
    
    SSLProxyEngine          On
    ProxyRequests           Off
    ProxyPreserveHost       On
    ProxyPass               /jira       http://jiraserver:8080/jira
    ProxyPassReverse        /jira       http://jiraserver:8080/jira

    (info) The path used must be identical to the Tomcat context path. For example, forwarding /jira to /jira520 cannot be done without considerable rewrite rules that are not always reliable.

  3. Copy the certificate and private key to the appropriate directories.
  4. Include them in the Apache configuration, within the VirtualHost as below:

    SSLCertificateFile      /etc/ssl/certs/jira.crt
    SSLCertificateKeyFile   /etc/ssl/private/jira.key
  5. (OPTIONAL): Configuration of SSLCertificateChainFile will contain the intermediate certificates provided by the CA vendor who signed it. Please follow consult with the CA vendor to verify if this is required.

    SSLCertificateChainFile /etc/ssl/certs/jiraintermediate.crt
  6. Restart Apache.
  7. Test by accessing JIRA through Apache, for example http://jira.com or http://atlassian.com/jira.

2.3 Redirect HTTP to HTTPS

This can be done with either of the following:

  • Set up the HTTP VirtualHost to forward to the same Tomcat Connector. Tomcat will redirect to HTTPS using the schemeproxyName & proxyPort parameters. This can be done as in our Integrating JIRA with Apache documentation.
  • Using mod_rewrite (this module may require enabling), add the following to the HTTP VirtualHost:

    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}

Step 3: Configure JIRA

  1. Set Use gzip compression to OFF as in Configuring JIRA Options. GZIP compression is known to cause performance issues using a reverse-proxy, especially if the proxy is also compressing the traffic.
  2. Set the Base URL to be the FQDN that JIRA will be accessed on, for example https://jira.atlassian.com. This is also located in Configuring JIRA Options.
    (warning) JIRA can only be configured to respond to a single URL and the Base URL (as in Configuring JIRA Options) must match the URL end-users are accessing. Misconfiguration of this may cause significant problems within JIRA such as the Activity Stream and Dashboard Gadgets failing to function correctly.
  3. Test by accessing JIRA on the FQDN (e.g.: https://jira.atlassian.com), ensuring that JIRA is accessible and all dashboard gadgets correctly display.

Troubleshooting

Hijacked Sessions

Some users have reported problems with user sessions being hijacked when the mod_cache module is enabled. If these problems are encountered, try disabling the mod_cache module. 
(info) This module is enabled by default in some Apache HTTP Server version 2 distributions.

Permission Denied Errors enabling mod_proxy (and mod_jk) on Linux distros that use SELinux

Users have reported 'permission denied' errors when trying to get mod_proxy (and mod_jk) working. Disabling SELinux (/etc/selinux/config) apparently fixes this.

 

Running Mac OS X

Disable webperfcache, which proxies port 80 by default. A user reported this as the likely cause of JIRA session problems, in the form of users' identities becoming mixed up, as below.
(warning) Additionally we do not recommend using Max OS X as it is not supported, as in our Supported Platforms.

 

The OSX Servers enable webperfcache by default for Virtual Hosts, which for static content would be great, but for dynamic sites (which ALL of ours are) it is Evil and causes many issues. 
Of note recently was the jira session issue. Also see :-
http://developer.apple.com/documentation/Darwin/Reference/ManPages/man8/webperfcache.8.html
Unfortunately even if you disable webperfcache for a site, if there is a single site enabled then all sites will still proxy through webperfcache with resulting session problems.

Too many redirects

Both Tomcat & Apache are redirecting, when only one should be. Disable redirection in Tomcat (revert any changes as in Running JIRA over SSL or HTTPS) and check that there is only one redirection in Apache.

General Problems

  1. Clear the browser cache and try again.
  2. Ensure that JIRA works as expected when running directly from Tomcat and bypassing Apache. For example, accessing http://jiraserver:8080 instead of http://jira.atlassian.com.
  3. Increase the LogLevel for Apache to debug and restart it.
  4. Attempt to access JIRA and check the Apache Log Files for any errors.
  5. Raise a question on Atlassian Answers for assistance.

403 Forbidden error

Add the RequestHeader unset Authorization line to the apache configuration page to disable authorization headers.

See Also

  • No labels

27 Comments

  1. Hi friends

    I'm integrating jira and some others applications (all of them working in the same tomcat 6.0) with an apache 2.2 server over a ssl layer. The jira is mounted like a war-ear application, but i can't make it work.

    If i access the app like http://localhost:8080/jira every works fine, but when someone else access the app from apache I got the next error. UrlSchemeMismatchException: Detected URL scheme, 'http', does not match expected scheme 'https'.

    I know that is necesary do some aditional configuration to make jira work with an ssl layer. I read the documentation but all is focused in the standalone version.

    Can you tell me which are the steps, or where can i found the information???

    Regards. Raul

  2. Hi,

    In case that I didn't use SSL between Apache and Tomcat, do I need to uncomment the Connector 8443 inside server.xml?

    Thanks,

    -Hieu

    1. Hi.

      In case of 4.3.x on Linux and MacOSX, using http (not https) (see reverse proxy setting of apache below) worked fine without problem. In this case, apache takes care all about https and Tomcat (JIRA) do not have know about it. You do not have to duplicate the pem setting. It is a way simpler, therefore better, than that documented above. However, JIRA 4.4 does not allow this. JIRA do not want to show dashboard page because the "scheme" of request is not just what JIRA expected. For me it seems JIRA (design) is becoming no better.

      1. Woops, I just skipped the part "Note: Alternative configuration if HTTPS is terminated on the proxy server". Sorry.

    2. Hi Hieu,

      About your question you don't need to enable the line starting in Connector port="8443" if you don't want SSL between Apache and Tomcat, because it is only to have a safe connection. On the other hand it is highly recommended once you will provide a safe environment for your instance.

       

      Cheers

       

  3. If I want to use Application Links between Confluence and JIRA, both of which are running behind Apache using SSL, does it matter which of the two above methods I use?  Do they both work?

    1. That's exactly what I wanted to do Troy and finally got it working.

      NO, the above method WILL NOT WORK (at least in my experience) for setting up Application Links between Confluence and JIRA with both of them running behind Apache using SSL.

      The method that DID work for me with that scenario was to use the AJP protocol instead of http to communicate between Jira and Confluence.

      This link provided the information I needed to get it working:

      http://confluence.atlassian.com/display/JIRA/Configuring+Apache+Reverse+Proxy+Using+the+AJP+Protocol

      You'll need to enable the proxy_ajp module if it isn't already.  In debian systems this is done via:

      a2enmod proxy_ajp

      It may be the same in other linux distros.

      1. Anonymous

        How do you get confluence to talk to JIRA over AJP?

        When I enable AJP in JIRA and try to enter the application link as ajp://localhost:8009 I get the error message "The application at URL 'http://ajp://localhost:8009/' is not responding. Please confirm that you want to use this URL."  Which of course makes no sense, but it seems to indicate that any connector between Confluence and JIRA requires HTTP and not AJP.

         

        1. I started a response to this about a month ago and then got distracted by something and subsequently never came back to it.  Sorry about that.

          You may have already figured this out by now, but the key to this is having a correct understanding of where Confluence and JIRA sit in the line of communication when connecting to one another via application links (relative to the setup that I linked to that uses the AJP protocol).

          If you're only accessing JIRA and Confluence on the same box where you've got it set up, then you'd use "http://localhost:8009/" for the URL when creating the application link (I think).  But if you're using the Reverse Proxy method as described in the link I provided, but it's more likely that you're having the :8009 port reverse proxy to a sub-directory name.  For example, in my deployment we have Confluence living at http://ourdomainname.com/docs, and our JIRA instance lives at http://ourdomainname.com/projects .

          Here are the reverse proxy rules that I have enabled for apache2 if it helps (/etc/apache2/sites-enabled/proxy):

          This, coupled with the settings changes you make to the server.xml file that are explained in the page I linked to above is what was central to getting it to work for me.

        2. curious if you ever got this sorted out... as I'm facing the same situation now.

          clearly the link needs to be http not ajp ... unless I'm missing something.

          1. Yes Larry, as I said in my post, it is working for me using the approach I outlined above.

  4. Anonymous

    So I have everything set up and working with this configuration: Client Browser --> HTTPS --> Apache proxy --> HTTP --> Tomcat/JIRA.  However, with this setup, JIRA won't be able to serve both SSL & non-SSL incoming requests.  I think that's due to these attributes in tomcat:

    scheme="https"
    proxyName="jira-stage.bscdev.bscal.com"
    proxyPort="443"

    How do I make JIRA to serve both ssl & non-ssl via the apache proxy server?

  5. Anonymous

    I find it strange, that the simplest way of them all is the last one to be listed. The first way is Running JIRA over SSL or HTTPS, which is hell on earth because it requires fiddling with keytool, the worst tool since Lotus Notes, the second one is Integrating JIRA with Apache using SSL which is still hell on on earth, because it requires fiddling with keytool.

    NoteAlternativeconfigurationifHTTPSisterminatedontheproxyserver is integrated in 5 minutes with 4 minutes waiting for the cert to be signed by the public CA.

    1. Anonymous

      I second this post.

      The guide is overly complicated and confusing for beginners. Also ist does not explain terms likeproxyName="<proxy_server>" - for someone who knows how to configure things its obvious that the "proxy_server" is actually the FQDN of the machine which is running apache/terminating https. But would such a person need this guide?

      Also this guide is inconsistent with the documentation for confluence - why not just use the same approach for both products?

      If you can live with a self-signed certificate most linux distributions will even provide you with a working default configuration for ssl after installing apache which you will just have to enable by "a2ensite default-ssl" or similar.

       

      If your goal is to make the JIRA userbase more familiar with advanced administration tasks (such as handling keytool) you certainly did a good job here...

  6. Is there a reason why not to use mod_jk instead of mod_proxy?

    1. Not in particular, no - how you decide to proxy to JIRA is completely up to you. We provide documentation on implementations of mod_proxy and mod_proxy_ajp, as in these docs and also in Configuring Apache Reverse Proxy Using the AJP Protocol.

  7. Anonymous

    Hi Guys,

    I have installed JIRA and Confluence on the same server and installed Apache behind JIRA as follows Client Browser --> HTTPS --> Apache proxy --> HTTP --> Tomcat/JIRA.

    I cannot access JIRA or confluence on the local server with localhost:8080 or the FQDN, as I need to configure application links, also I am only terminating ssl from apache only.

    Any help is appreciated, I have been stuck with this issue for weeks now

    1. Please raise a question on Atlassian Answers and someone will be able to help out. (smile)

  8. Just a note on SELinux, using:

    /usr/bin/setsebool httpd_can_network_connect=1

    fixes permission problems without having to disable SELinux completely.

     

  9. Anonymous

    Hello,

    I think using Redirect rather than rewrite gives for faster performance, both in the server and also the client as it will cache the redirects but not neccessarily the rewrites.  For me I had a simple vhost.conf for http to redirect to https:

    <VirtualHost *:80>
         ServerName      jira.myhost.com
         Redirect permanent      /      https://jira.myhost.com/
    </VirtualHost>

     

    Thanks for a wonderful product (smile)

    1. Redirect isn't just more performant, it's Apache's recommended method.

  10. Anonymous

    Running JIRA 6.1.2 on Ubuntu 12.0.4, the 2 changes that I made which didn't match these instructions are;

    1) Added 3 lines to server.xml - under service name = catalina

                       scheme="https"

                       proxyName="jira-test.ctmsp.com"

                       proxyPort="443"

     2) Adding this rewrite rule (instead of the one on this set of instructions.

                      RewriteEngine On

                      RewriteCond %{HTTP:X-Forwarded-Proto} !https
                      RewriteRule !/status https://%{SERVER_NAME}%{REQUEST_URI} [R]

     

    I hope this helps someone else with a similar environment.

     

  11. Check this nginx SSL proxy users:

    http://www.aip.im/2012/05/how-to-solve-url-scheme-mismatch-when-running-jira-behind-a-reverse-proxy/

    We are using nginx as a reverse proxy, and have an F5 doing the SSL offload, and this dude saved the day for us.

     

  12. I installed JIRA 6.3.13 on Debian/jessie (OpenJDK 1.7.0, Apache 2.4.14 and OpenSSL 1.0.1j) but the problem of mismatch scheme was never resolved.

    Finally this has been fixed by using mod_proxy_ajp instead of mod_proxy_http, however I'm dissatisfied.

    And also, is SSLProxyEngine directive harmful, isn't it? When it's specified, does Apache try to communicate with proxied servers by using TLS protocol?

  13. Setting up image in AWS on CentOS7:

    Used Postgres

    when it came to the decision of SSL we used an ELB for our VPC 

    The configuration was very straightforward but one detail I want to bring to everyone's attention. 

    in the main instructions if you are using SSL  on your gateway you need to use HTTPS as the protocol and port 443. 

    Someday soon I will try and do the complete writeup. 

  14. In Step 1.3 (Configure Tomcat / edit server.xml), the suggestion in adding the standard connector assumes, that you have replaced the original HTTP connector at the top of the file. If you have just added the proxy connector you don't need another "Standard HTTP connector".

    Just add the proxy connector an define a different port (say, if the "non-proxy" connector runs on port 8080, set the "proxy" connector to 8081):

        <Service name="Catalina">

    <!-- standard HTTP connector -->
            <Connector port="8080"

                       maxThreads="150"
                       minSpareThreads="25"
                       connectionTimeout="20000"

                       enableLookups="false"
                       maxHttpHeaderSize="8192"
                       protocol="HTTP/1.1"
                       useBodyEncodingForURI="true"
                       redirectPort="8443"
                       acceptCount="100"
                       disableUploadTimeout="true"/>

    <!-- proxy HTTP connector -->
                  <Connector port="8081"
                             acceptCount="100"
                             connectionTimeout="20000"
                             disableUploadTimeout="true"
                             enableLookups="false"
                             maxHttpHeaderSize="8192"
                             maxThreads="150"
                             minSpareThreads="25"
                             protocol="HTTP/1.1"
                             redirectPort="8443"
                             useBodyEncodingForURI="true"
                             scheme="https"
                             proxyName="jira.example.com"
                             proxyPort="443"
                             secure="true"/>

     

    Overseeing this and defining the same port in the proxy-connector as the connector on top of the server.xml file will make the proxy connector ineffective, because due to the port conflict the proxy connector will not even start.