Documentation for JIRA 4.2. Documentation for other versions of JIRA is available too.

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

The content on this page relates to platforms which are not supported by JIRA. Consequently, Atlassian can not 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.

This page describes how to configure Microsoft's IIS web server and JIRA such that IIS forwards requests on to JIRA, and responses back to the user. This is useful if you already have IIS running serving web pages (e.g. http://mycompany.com), and wish to integrate JIRA as just another URL (e.g. http://mycompany.com/jira).

JIRA is written in Java, and needs a Java Application Server (servlet container) to run. As IIS does not provide services of a Java Application Server, it is not possible to deploy JIRA directly into IIS. It is possible, however, to configure IIS to proxy requests for JIRA to an application server where JIRA is deployed. Therefore, if your main website is running in IIS, it is possible to integrate JIRA into this website.

If you need to integrate JIRA with IIS, JIRA needs to be deployed into a Java Application Server that provides IIS integration capability. Apache Tomcat is one of these application servers. The Standalone distribution of JIRA ships with Apache Tomcat, so if you are using the Standalone distribution or have deployed JIRA WAR into your own Tomcat instance, please follow this document.

If you are not using the Standalone distribution or Apache Tomcat, please consult your application server's documentation to determine whether it is possible to integrate with IIS and how to achieve it.

To integrate JIRA Standalone with IIS you will need to:

  1. Configure JIRA and test that it works on its own
  2. Configure Tomcat to accept proxied requests from IIS
  3. Configure IIS to forward JIRA requests to Tomcat
  4. (Optional) Configure IIS to forward Confluence requests to Tomcat (if you are using both Confluence and JIRA).

1. Configure JIRA

  1. Follow the JIRA Standalone install guide to install and configure the Standalone distribution of JIRA; or deploy the EAR-WAR distribution into Apache Tomcat. Note that JIRA can be installed on the same machine as IIS, but this is not necessary.
  2. Change the context path of the JIRA web application:
    To allow IIS to proxy requests to JIRA, JIRA web application must be deployed with a context path (e.g. the /jira in http://localhost:8080/jira (http://localhost:8080*/jira*)) in Tomcat. The context path must be set to the path in the URL that IIS will use to proxy requests. For example, if your website is running with address www.example.com in IIS, and you would like to make JIRA available under www.example.com/jira, you will need to set JIRA's context path to "/jira" in Tomcat.
    To do this, edit the conf/server.xml file (if you are using JIRA Standalone) or the jira.xml file (if you are using the EAR-WAR distribution of JIRA). Change the path attribute of the Context element to "/jira". For example, in JIRA Standalone 3.3 and later the Context element would look like: 
                <Context path="/jira" docBase="${catalina.home}/atlassian-jira"
            swallowOutput="true" reloadable="false">
  3. Restart JIRA after changing the context path.
  4. Set the 'Base URL' to include the context path (see Configuring JIRA Options).
  5. Turn JIRA's GZip compression OFF (since there will be no benefit from GZip compression once proxying is implemented).
  6. Test that JIRA works correctly by pointing your web browser directly at Tomcat (e.g. http://localhost:8080/jira) and going through JIRA's Setup Wizard. If you have completed the Setup Wizard previously, try creating an issue or editing one. Please ensure that no errors occur.

2. Configure Tomcat to accept proxied requests

  1. Enable AJP/1.3 Connector in Tomcat: To allow Tomcat to accept requests for JIRA from IIS, edit the conf/server.xml file and ensure that the AJP/1.3 Connector is enabled (i.e. not commented out).To enable the AJP/1.3 Connector in JIRA Standalone, Tomcat 5.5.x or Tomcat 5.0.x, remove the comment symbols (<!- and ->) around the following section in the conf/server.xml file: 
                <Connector port="8009"
            enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />
    If you are using JIRA Standalone 3.2 or earlier or running JIRA in Tomcat 4.1.x the AJP/1.3 Connector definition in the conf/server.xml file looks like: 
                <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
            port="8009" minProcessors="5" maxProcessors="75"
            enableLookups="true" redirectPort="8443"
            acceptCount="10" debug="0" connectionTimeout="0"
            useURIValidationHack="false"
            protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>
    The above example configures Tomcat to listen for proxied IIS requests on port 8009. If this port is already in use on the machine where JIRA is running, please change to another port.
  2. Restart Tomcat and ensure that no errors regarding used ports appear in the logs or in the Tomcat Console.
  3. Ensure that the AJP Connector is listening on the specified port (8009 by default). One way to do this is to use the "netstat -na" command in the command window and see if port 8009 is listed in the output:

3. Configure IIS to forward requests to JIRA

On the machine where IIS is deployed:

  1. Download the ISAPI Redirect DLL from the Apache site. When downloading, choose the version of Windows that IIS is running on (either win32 or win64), and then choose the latest available jk version.

    The file to download is named isapi_redirect_X.X.X.dll, where 'X.X.X' is the version number. You will need to remove the version number from the DLL file (i.e. it needs to be named isapi_redirect.dll).

  2. Place the DLL and the associated properties files in an installation directory. For the purpose of this document, we will assume the directory is C:\tomcat_iis_connector. Place the isapi_redirect.dll in this directory. Then download the isapi_redirect.properties file and place this in the same directory as the isapi_redirect.dll file.
  3. Create a directory called 'conf' in your installation directory (C:\tomcat_iis_connector\conf). Download the files uriworkermap.properties and workers.properties.minimal and place them in the C:\tomcat_iis_connector\conf directory.
  4. Create a directory called 'logs' (C:\tomcat_iis_connector\logs). This is where the logs associated with the isapi_redirect.dll execution will be placed.
  5. In the "C:\tomcat_iis_connector" directory you may need to modify the isapi_redirect.properties file. The isapi_redirect.properties file tells the connector where to find its configuration files and where the DLL can be found in relation to the IIS server. There are 5 properties in this file:
    1. extension_uri — the path to the virtual directory that contains the isapi_redirect.dll
    2. log_file — the path to write the log file to
    3. log_level — the level at which the logs should be generated
    4. worker_file — the path to your workers.properties.minimal file in your installation
    5. worker_mount_file — the path to your uriworkermap.propertiesl file in your installation.
      If you are installing the connector in C:\tomcat_iis_connector and you follow the instructions below about setting up the virtual directory for the isapi_redirect.dll, then you should not have to change any properties in the provided file.
  6. In the "C:\tomcat_iis_connector\conf" directory you may need to modify the uriworkermap.properties and the workers.properties.minimal files.

    The provided files contain the changes mentioned here and should work if you completely follow this document. If you have deviated from this document, then you will need to modify these files as described below.

    The workers.properties.minimal file tells IIS where (IP address and port) Tomcat is running. The uriworkermap.properties tells IIS what requests to proxy to Tomcat.
    To edit these files:
    1. Edit the uriworkermap.properties and ensure that it contains the following mapping for JIRA. You do not need any other mappings. 
                      /jira/*=worker1

      The mapping (e.g. /jira/) *must be the same as the context path that JIRA has been deployed with in Tomcat as described in the Configure JIRA section of this document.

    2. Edit the workers.properties.minimal file and modify the worker.ajp13w.host property if necessary. This property should be set to the host name or the IP address of the machine where Tomcat (with JIRA) is running. If Tomcat is running on the same machine as IIS then you can leave the property set to localhost. If you have specified a host name as the value of this property, please ensure that the IIS machine can correctly resolve it to the appropriate IP address.
    3. If you have modified the port for the AJP Connector you will need to modify the worker.ajp13w.port property. Here is an example of the file with Tomcat running on the same machine as IIS and using the default port (8009) for AJP: 
      worker.list=worker1

#
# Defining a worker named worker1 and of type ajp13.
# Note that the name and the type do not have to match.
#
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009
  7. Open Control Panel, then Administrative Tools and open Internet Information Services.
  8. IIS 7.0 only: If you are using IIS 7.0, you will need to install two required service roles, ISAPI Extensions and ISAPI Filters:
    1. Navigate to Start Menu > All Programs > Administration Tools > Service Manager.
    2. Select 'Web Server (IIS)' in Server Manager > Roles.
    3. Click 'Add Role Services' and follow the Wizard.
  9. Add an ISAPI Filter to IIS, as described below:
    • IIS 6.0 or earlier:
      1. Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), and click on Properties.
      2. Click the ISAPI Filters tab.
      3. Check if there is a Filter that points to the isapi_redirect.dll file and that it is in the right location. If not, click Add and create one. Enter tomcat as the Filter Name and enter the location of the isapi_redirect.dll file for the executable.
      4. Click Apply and then OK.
    • IIS 7.0:
      1. Click the Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), and click on ISAPI Filters.
      2. Click the ISAPI Filters icon.
      3. Check if there is a Filter that points to the isapi_redirect.dll file and that it is in the right location. If not, click Add and create one. Enter tomcat as the Filter Name and enter the location of the isapi_redirect.dll file.
      4. Click OK.
  10. Create a virtual directory for JIRA in IIS.
    1. Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), choose New and then Virtual Directory.
    2. Go through the creation wizard. Set the alias as the value of the Context Path (without slashes) that was set in the Configure JIRA section of this document (see above). In our example this is jira .
    3. This can point to any directory.
    4. Complete the wizard.

      The reason for creating a virtual directory is so that requests without the trailing slash still work. For example, if you are deploying JIRA under http://www.example.com/jira/ without the virtual directory, then requests to http://www.example.com/jira will fail.

  11. Create a virtual directory for access to the isapi_redirect.dll in IIS, as described below:
    • IIS 6.0 or earlier:
      1. Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), choose New and then Virtual Directory.
      2. Go through the creation wizard. Set the alias to be jakarta .
      3. This must point to the directory in which the isapi_redirect.dll is installed. In our example this is C:\tomcat_iis_connector.
      4. Complete the wizard, making sure that you grant the 'Execute' permission for the Virtual Directory by checking the 'Execute' checkbox.
    • IIS 7.0:
      1. Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), and choose Add Virtual Directory.
      2. Set the alias to be jakarta .
      3. Physical Path must point to the directory in which the isapi_redirect.dll is installed. In our example this is C:\tomcat_iis_connector.
      4. Click the 'jakarta' Virtual Directory and double-click 'Handler Mappings'.
      5. Click 'Edit Feature Permissions' in the Action panel on the right-hand side.
      6. Check the 'Execute' permission checkbox.

        This Virtual Directory is needed for the connector to work. The alias that you give the directory needs to be the same as the path set in the isapi_redirect.properties file, extension_uri property. In our example this value is: /jakarta/isapi_redirect.dll.

  12. If using IIS 6.0 or 7.0, you will need to add the dll as a Web Service Extension, as described below.
    • IIS 6.0:
      1. Right-click on Web Service Extensions and choose Add a new Web Service Extension...
      2. Enter tomcat for the Extension Name and then add the isapi_redirect.dll file to the required files.
      3. Select the Set extension status to Allowed check-box, then click OK.
    • IIS 7.0:
      1. Navigate to the servers and highlight your server.
      2. Navigate to 'ISAPI and CGI Restrictions'.
      3. Add and allow the isapi_redirect.dll extension.
  13. You will need to restart the IIS Service. To do this, browse to Control Panel, click Administrative Tools, click on Services, find the IIS Admin Service and click restart.
  14. You are done! To test the configuration, point your web browser at IIS and append JIRA's context path to the URL. For example, if your website is running under the address of http://www.example.com and you have deployed JIRA with the context path of jira, point your browser at http://www.example.com/jira.

4. Configure IIS to forward requests to Confluence as well as JIRA

You can configure IIS so that it forwards requests to both JIRA and Confluence.

The following instructions describe how to forward from IIS to separate instances of JIRA and Confluence, running in separate Tomcat servers. The instructions assume that you have already set up IIS to forward to JIRA as described in section 3 above. The instructions also assume that you have already installed Confluence as per the Confluence Installation Guide.

The instructions describe how to make JIRA available under www.example.com/jira as described above, and Confluence available under www.example.com/confluence.

  1. If JIRA and Confluence are running on the same machine, ensure that Confluence is listening on a different port to JIRA:Edit the conf/server.xml file (if you are using Confluence Standalone) or the jira.xml file (if you are using the EAR-WAR distribution of Confluence). At the top of the file, change the port attribute of the Server element to a different port to the value for JIRA. For example, change it from 8005 to 8006.
    Still in the Server element, Change the port attribute of the Connector sub-element to a different port to the value for JIRA. For example, change it from 8080 to 8090 .
  2. Change the Confluence context path:Edit the conf/server.xml file (if you are using Confluence Standalone) or the jira.xml file (if you are using the EAR-WAR distribution of Confluence). Change the path attribute of the Context element to "/confluence".
  3. Restart Confluence after changing the ports and the context path, and test that Confluence works correctly by pointing your web browser at http://localhost:8090/confluence.
  4. Configure Confluence to accept proxied requests:Remove the comments around the AJP/1.3 Connector section in the Confluence conf/server.xml or jira.xml file and change the port attribute to a value different to the value for JIRA. For example, change it from 8009 to 8010.
  5. Restart Confluence and ensure that no errors regarding used ports appear in the logs or in the Tomcat console.
  6. Edit the uriworkermap.properties file and add the following mapping: 
                        /confluence/*=worker2
    The file should now contain the following mappings: 
                        /jira/*=worker1
                    /confluence/*=worker2
  7. Edit the workers.properties.minimal file:
    Change the line starting with worker.list to the following: 
                        worker.list=worker1,worker2
    Add the following lines to the end of the file (assuming the host is on the same machine as IIS and you changed the AJP/1.3 Connector port for Confluence to 8010 ): 
                        worker.worker2.type=ajp13
                    worker.worker2.host=localhost
                    worker.worker2.port=8010
    The workers.properties.minimal file should now look like the following: 
    worker.list=worker1,worker2

#
# Defining a worker named worker1 and of type ajp13.
# Note that the name and the type do not have to match.
#
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009

worker.worker2.type=ajp13
worker.worker2.host=localhost
worker.worker2.port=8010
  8. Create a virtual directory for Confluence in IIS. Set the alias to confluence. It can point to any directory.
  9. Restart the IIS Service.
  10. You are done! Confluence should now be available under www.example.com/confluence, and JIRA should still be available under www.example.com/jira.

Troubleshooting

  • Whenever I go to JIRA in my browser, a login panel pops up. I enter a valid username and password for JIRA, but the panel pops up again.Make sure that you have Anonymous Access set on the jira virtual directory in IIS. It will be set to that if you have followed the above instructions.To check this:
    1. In 'Internet Information Services', right click the jira virtual directory and choose 'Properties'.
    2. Click the 'Directory Security' tab.
    3. Click the 'Edit...' button in the 'Anonymous access and authentication control' section.
    4. Make sure that the 'Anonymous access' tick box is selected, and make sure that nothing is selected in the 'Authenticated access' section. Do not select 'Basic authentication'. Do not select 'Integrated Windows authentication'.
  • Whenever I go to JIRA in Internet Explorer, a login panel pops up. I enter a valid username and password for JIRA, but the panel pops up again. This doesn't happen, however, in another browser such as Firefox or Safari. I can successfully log in to JIRA in those browsers.Make sure that you have Internet Explorer's User Authentication set to Anonymous login. To check this:
    1. In Internet Explorer, click the 'Tools' menu and select 'Internet Options'.
    2. Click the 'Security' tab.
    3. Select the security zone that the JIRA server is in.
    4. Click the 'Custom level...' button.
    5. Scroll right down to the bottom to the 'User Authentication' section.
    6. Select 'Anonymous logon' (if it is not already selected).
    7. Click the 'OK' button on this screen, and again on the next screen.
    8. Restart Internet Explorer.
  • When I try to navigate to my JIRA instance at http://localhost/jira in my browser, it prompts me to download a file with nonsensical information, rather than showing me my JIRA instance.Make sure that you have granted the 'Execute' permission to your Virtual Directory for JIRA in IIS. See step 11 of the '3. Configure IIS to forward requests to JIRA' section in this document for detailed instructions.

Known Issues

  • 64 bit IIS: If you are running a 64 bit OS, please use a 64 bit version of the Tomcat IIS connector.
  • Customer submitted solution: If you must use a 32 bit IIS connector, you can do so by clicking Application Pools > Advanced Settings > Allow 32bit applications.
  • Customer submitted solution: You need to set the ISAPI extension on the website.
  • No labels



Log a request with our support team.



Raise an issue for our developers.



See answers from the community.



Tweet, blog and update our documentation.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.