Using the JIRA Configuration Tool

The JIRA Configuration Tool is an application (included with all JIRA distributions except JIRA WAR) that offers server-level JIRA configuration through a convenient GUI. This tool allows you to do the following:

On this page:

Please Note:

  • The JIRA Configuration Tool requires a Java platform to be installed and configured on your operating system. If you need to install a Java platform to run this tool, we recommend using a Java platform supported by JIRA — refer to JIRA Requirements for details.
  • If you use the JIRA WAR distribution or have a console-only connection to your JIRA server, you will need to perform these server-level configurations manually.
  • Whenever you configure or reconfigure JIRA's server-level settings using this tool, JIRA must be restarted so it can recognise these changes.

Starting the JIRA Configuration Tool

The JAVA_HOME environment variable must be set to use the JIRA configuration tool. If it has not been set already, follow the instructions in Installing Java to set it.

To start the JIRA configuration tool:

The JIRA configuration tool can be run with a graphical user interface or via a command-line interface using the -c or --console argument. The following sections show the graphical user interface, but the functionality is the same regardless of the interface.

Configuring the JIRA Home Directory

Your JIRA Home Directory allows you to set the folder that JIRA uses to store its various data files.

To set your JIRA Home Directory using the JIRA Configuration Tool:

  1. Click the JIRA Home tab.
  2. In the JIRA Home Directory field, type the full file path into the text field, or click the Browse button to browse for the location of your JIRA Home Directory.
  3. Click the 'Save' button. Your changes are saved to the file located in the <jira-application-dir> subdirectory of your JIRA Installation Directory. For more information, please see Setting your JIRA Home Directory.

Screenshot: JIRA configuration tool — 'JIRA Home' tab

Configuring the database connection

To configure JIRA's database connection using the JIRA configuration tool, follow the appropriate procedure for your database type:

Screenshot: JIRA configuration tool — 'Database' tab

Configuring JIRA's web server

The JIRA configuration tool can also be used to configure JIRA's web server, specifically the TCP ports and the SSL configuration. Follow the relevant instructions linked below:

Screenshot: JIRA configuration tool — 'Web Server' tab

Tuning JIRA's database connections

For more information about the functionality of the Advanced tab, see Tuning Database Connections.

Screenshot: JIRA configuration tool — 'Advanced' tab

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

13 Archived comments

  1. User avatar


    On Windows 2008 (and R2) because of permission rights you have to start an elevated command prompt and then run the config.bat from there. If you do not do that the application will not have write permissions to the config files. It is not enough to run the config.bat as administrator.

    03 Nov 2010
    1. User avatar


      I am having trouble running the config.bat as administrator on Windows Server 2008 R2.

      What exactly does "It is not enough to run the config.bat as administrator" mean? My assumption is that elevated comman prompt is none other than running cmd prompt as administrator. Please provide more details in this refrence.

      The error I see when I try to run is "Files was unexpected at this time".

      Thank You

      15 Aug 2011
      1. User avatar


        The error message is misleading. It occurs because the environmental variable is enclosed in double-quotes, eg:

        JRE_HOME="C:\Program Files (x86)\Atlassian\JIRA\bin"

        If should work OK if you remove the double-quotes, ie:

        SET JRE_HOME="C:\Program Files (x86)\Atlassian\JIRA\bin"

        The Files mentioned in the error is actualy from the string after the first space character !

        29 Aug 2012
        1. User avatar



          SET JRE_HOME=C:\Program Files (x86)\Atlassian\JIRA\bin

          29 Aug 2012
  2. User avatar


    I always have the same error, when running ./ - on Jira 4.2 and 4.3 on my Debian GNU/Linux 5.0 server:

    jira@server:~/bin$ ./
    Exception in thread "main" java.awt.HeadlessException:
    No X11 DISPLAY variable was set, but this program performed an operation which requires it.
            at java.awt.GraphicsEnvironment.checkHeadless(
            at java.awt.Window.<init>(
            at java.awt.Frame.<init>(
            at java.awt.Frame.<init>(
            at javax.swing.JFrame.<init>(
            at com.atlassian.jira.configurator.gui.ConfiguratorFrame.<init>(
            at com.atlassian.jira.configurator.Configurator.startGui(
            at com.atlassian.jira.configurator.Configurator.main(

    14 Mar 2011
    1. User avatar


      You can't run GUI applications through an SSH connection.

      26 Mar 2011
      1. User avatar


        Yes you can!

        If you have a reasonably new ssh and X11 installed on the machine you connect from, use the ssh -Y (or -X) flag.

        E.g. "ssh -Y"

        This works on my OSX Lion with XQuartz installed and should work on all other Unix workstations.

        Have tried with other GUI programs on Windows using some X11 server and PuTTY.

        02 Aug 2011
  3. User avatar

    Yonas Keflemariam

    I am having a lot off difficulty getting the JIRA configuration Tool to authenticate a connection to my SQL Server 2005 default instance. I keep receiving a "Could not connect to the DB: Login timed out." error message. I have tried every combination of values and entries that I could imagine but to no avail. I have also double & triple checked that the steps in "Connecting JIRA to SQL Server 2005" has been configured properly in my environment along with verifying that TCP/IP was enabled (particularly on port 1433) in the SQL Server Configuration Manager. I simply cannot identify what is causing this so any help would be appreciated.I would particularly like advice on where the JIRA Configuration Tool logs its success/failure entries and any suggestions you might have.

    Items to note:

    OS - Windows Server Web SP2 (64 bit)

    13 May 2011
  4. User avatar


    how to open JIRA cofrigation tool

    it is not open by


    29 Oct 2012
    1. User avatar


      Reach the correct folder (e.g. /opt/<MYJIRAINSTANCE>/jira/bin/), then issue the command


      17 Sep 2013
  5. User avatar

    Erdem Sener

    I think this assumes JIRA runs in a server with desktop environment installed and I'm not 100% sure whether this would help using a Godaddy generated CRT with JIRA.

    A big problem is that keytool sees the certificate, displays it properly as trusted and everything, but JIRA says "The referenced certificate could not be found or accessed. Do you want to try again?" (via non-X setup).

    27 May 2013
  6. User avatar

    Dejan Golja

    Is there any alternative to the Configuration tools to setup the HTTPS if you do not have a GUI installed on the server where JIRA is running ?

    22 Oct 2013
    1. User avatar

      Jaufret Demariés

      Yes, you juste have to write:
      #unset DISPLAY

      Tell me if it resolved your problem (smile)

      31 Oct 2013
Powered by Confluence and Scroll Viewport