Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
On this page:
Please follow the instructions in the general upgrading JIRA documentation, as well as the JIRA 4.3-specific instructions in the sections below. The general upgrade guide contains important tasks that are essential for getting your upgraded JIRA instance to work correctly (e.g. merging jira-application.properties
customisations from the old instance to the upgraded instance).
JIRA 4.3 now officially supports 'in-place database upgrades' (when upgrading from JIRA 4.0.0 or later). This method requires much less downtime during the JIRA upgrade process, especially if you operate a large JIRA installation. You no longer need to export your existing JIRA data to an XML backup and then restore this data into your new JIRA version. Instead, we now support simply 'pointing' your new version of JIRA at your existing JIRA database!
jira-application.properties
If you are merging your old and new configuration files, as described in the Upgrade Guide, the following tables list the changes which have been made to the jira-application.properties
file in JIRA 4.3.
The purpose of each new property is documented in the jira-application.properties
file itself.
New properties in |
---|
|
|
seraph-config.xml
and Crowd IntegrationWhen merging your old and new configuration files, as described in the Upgrade Guide, please take extra care with the seraph-config.xml
file, since this file contains a few changed entries in JIRA 4.3.
If you simply copy your old seraph-config.xml
to your new 4.3 installation, then:
seraph-config.xml
), your users may have authentication problems when attempting to log in to JIRA.The following table lists the changes to the seraph-config.xml
file in JIRA 4.3:
Elements in | Change in JIRA 4.3 |
---|---|
<param-name>login.url</param-name> <param-value>/login.jsp?os_destination=${originalurl}</param-value> |
<param-value>/login.jsp?permissionViolation=true&os_destination=${originalurl}</param-value> |
<param-name>invalidate.session.exclude.list</param-name> <param-value>ASESSIONID</param-value> |
<param-value>ASESSIONID,jira.websudo.timestamp</param-value> |
The following section <!-- CROWD:START - If enabling Crowd SSO integration uncomment the following JIRAAuthenticator and comment out the DefaultAuthenticator below --> <!-- <authenticator class= "com.atlassian.crowd.integration.seraph.v22.JIRAAuthenticator"/> --> <!-- CROWD:END --> <!-- CROWD:START - The authenticator below here will need to be commented out for Crowd SSO integration --> <authenticator class= "com.atlassian.jira.security.login.JiraOsUserAuthenticator"/> <!-- CROWD:END --> | Has been changed in JIRA 4.3 to <!-- CROWD:START - If enabling Crowd SSO integration uncomment the following SSOSeraphAuthenticator and comment out the JiraSeraphAuthenticator below --> <!-- <authenticator class= "com.atlassian.jira.security.login.SSOSeraphAuthenticator"/> --> <!-- CROWD:END --> <!-- CROWD:START - The authenticator below here will need to be commented out for Crowd SSO integration --> <authenticator class= "com.atlassian.jira.security.login.JiraSeraphAuthenticator"/> <!-- CROWD:END --> |
| Removed as this |
Due to a security enhancement in JIRA 4.3, any external gadgets (or gadgets that make requests to external URLs) will be disabled until you add the relevant external URLs to your Whitelist.
When you first log in to JIRA 4.3 as an administrator, a message will be displayed at the top of the screen, containing a link to the 'Whitelist' page. This page will also list your external gadgets. You can either delete these gadgets, or confirm that you wish to add the relevant external URLs to your whitelist.
For more details, please see Configuring the Whitelist.
The way users and groups are stored and accessed in JIRA has been totally rewritten in Release 4.3. This has provided a number of additional capabilities, mainly the ability to use an LDAP server (including Microsoft Active Directory) for all user information.
When you start up JIRA 4.3, the upgrade process will automatically upgrade your user data. The sections below describe the upgrade considerations for each supported configuration type.
For users that are not currently connecting to Crowd or LDAP then there are no actions required on upgrade.
If you had previously connected JIRA to an LDAP server for authentication (using the standard method), then this configuration will automatically be acquired by JIRA when upgrading to JIRA 4.3 (or later). However, the following must be observed:
osuser.xml
file was used to configure the connection to an LDAP server. For JIRA 4.3 (or later) to acquire these configurations automatically, your existing osuser.xml
file MUST be available to JIRA 4.3 (or later) before it is started.osuser.xml
file from the atlassian-jira/WEB-INF/classes
directory of your old installation to the atlassian-jira/WEB-INF/classes
directory of the new installation.If you upgrade JIRA without the osuser.xml file in place, then the upgrade will proceed, but will not configure a connection to LDAP and there is no way to connect the migrated users to work with authentication via LDAP, without performing the upgrade again from a backup of JIRA or direct manipulation of the database, which is unsupported by Atlassian.
JIRA 4.3 (or later) will only connect to Crowd 2.1 or higher. If you are using an earlier version of Crowd and wish to use this Crowd configuration in your upgraded JIRA 4.3 (or later) installation, you must upgrade Crowd to version 2.1 before you upgrade JIRA.
After upgrading JIRA, you will need to wait until a synchronisation task has copied your user and group information from Crowd to JIRA's internal cache before you can log in to JIRA. If a JIRA user attempts to log in to JIRA before this synchronisation task has finished, the user's authentication will fail.
If you had previously connected JIRA to a Crowd server (using the standard method), then this configuration will automatically be acquired by JIRA when upgrading to JIRA 4.3 (or later). However, the following must be observed:
osuser.xml
and crowd.properties
files were used to configure the connection to Crowd. For JIRA 4.3 (or later) to acquire these configurations automatically, your existing osuser.xml
and crowd.properties
files MUST be available to JIRA 4.3 (or later) before it is started.osuser.xml
and crowd.properties
files from the atlassian-jira/WEB-INF/classes
directory of your old installation to the atlassian-jira/WEB-INF/classes
directory of the new installation.If you upgrade JIRA without the osuser.xml file in place, then the upgrade will NOT proceed. JIRA has a table, EXTERNAL_ENTITIES, that contains some information regarding users maintained in a Crowd server. If there are entries in this table, but no osuser.xml file present, then the upgrade will stop and write a message to the log file.
If you are a customer with a Confluence installation that uses JIRA for user management, please do not upgrade to JIRA 4.3 until you have first upgraded to Confluence 3.5.
JIRA 4.3 possesses a significantly different database schema and exposes the Crowd REST interface, which Confluence will depend on for continued JIRA user management. If you upgrade to JIRA 4.3 before upgrading to Confluence 3.5, your Confluence users will no longer be able to log in until you upgrade to Confluence 3.5.
Custom directory types are not possible and not supported in JIRA 4.3 and later.
Please see if one of the following solutions will work for you:
If you need to keep the custom directory connection, please consider whether Atlassian Crowd meets your requirements. See the documentation on developing a custom directory connector for Crowd.
If you have a non-standard configuration and the upgrade has stopped, please contact http://support.atlassian.com.
If your JIRA instance has two groups that have the same name, but differ only by case (eg "sydney" and "Sydney"), the JIRA 4.3 upgrade will fail. You need to remove any duplicates in your current JIRA instance before upgrading. That is, you should delete one of the groups and move any users and permissions to the other group or to a new group.
(Note: There will not be a problem if your JIRA instance is connected to an external Crowd instance, and the duplicate groups are in Crowd or in an LDAP directory connected to JIRA via Crowd.)
For customers who have written programs or used other tools that access the JIRA database directly, the tables used to hold user data have changed.
Old table | New table | Information about new table |
---|---|---|
userbase | cwd_user | Holds information about the user. |
groupbase | cwd_group | Hold information about groups. |
membershipbase | cwd_membership |
|
These tables are indexed by directory and contain both details of all local users and groups and also cached details of external users and groups.
In version 4.3, JIRA makes no distinction between two or more usernames that only differ by case. Furthermore, username searches are case-insensitive. These behaviours are in compliance with the LDAP specification.
In version 4.2 and earlier, JIRA's handling of usernames is case-sensitive. While JIRA's user interface prevents the creation of usernames containing upper-case characters, the use of data migration or other tools may lead to a JIRA database containing mixed-case usernames.
During migration, if two users exist whose usernames differ only by case, one user will be dropped and an entry placed in the log file to record this.
JIRA's behaviour has always been undefined when two users had usernames differing only by case. There may be some side effects of the dropping of the second user including:
When a single project is imported (see Restoring a Project from Backup), users who do not exist already in the target system are created. In releases 4.2 and earlier of JIRA, the users' passwords were also set to the passwords in the exported XML file. This is no longer the case. Users will be given randomly allocated passwords and will need to use the 'Forgotten password' link to have their passwords reset.
Note: this only relates to the 'Project Import' feature, that is, when you import a single Project from a second JIRA instance into this JIRA instance. When doing a normal full import (see Restoring Data), the passwords are preserved as usual.
Some customers may wish to migrate to managing their users in LDAP. This may particularly appeal to customers whose JIRA instance is internal, and all users are already managed in the company LDAP Directory or Microsoft Active Directory.
In versions of JIRA prior to 4.3 it was possible to authenticate users against an LDAP directory, but you needed to add the users, groups and memberships manually in JIRA. In JIRA 4.3, support was added that allows you to directly use an LDAP directory for users groups and memberships as well as authentication.
If you were using an LDAP directory for authentication and your osuser.xml configuration file is available to JIRA during the upgrade task then JIRA will create 2 user directory configuration entries:
If the osuser.xml file is not available during the upgrade then JIRA will create 1 user directory configuration entry:
Note: If you wish to continue to use LDAP for authentication only, then ensure the osuser.xml is available during the upgrade.
Ensure the LDAP directory contains the necessary JIRA Groups and Memberships. All users that are going to use JIRA must belong to a group that has JIRA Use permission, typically "jira-users".
If you cannot add Groups and memberships to your LDAP server, then you can still migrate to LDAP but will need to set the privileges to "READ-ONLY with Local Groups". Once you have completed the migration described below, you will then need to manually add all the users to the required groups. See Managing Groups.
Go to Administration/User Directories and see what directories are configured.
The steps are:
Once you have completed testing you may delete the Internal Directory with LDAP authentication.
The steps are:
At this stage all the users will be in both the Internal and LDAP directory. There is no simple mechanism to remove the users from the internal directory at this time. If you wish, you can delete these users by SQL. Manipulating the database with SQL is not supported, and is at your own risk. TAKE A BACKUP FIRST.
Tomcat does not come with some libraries required to run JIRA. These include database libraries that must be in the Tomcat classpath. You will need to add these libraries to your tomcat/lib
directory
tomcat/lib
.commons-logging-.jar
, slf4j.jar
and log4j-1.2.15.jar
are present in Tomcat's /lib/ directory. Also ensure that these files are not present in Tomcat's webapps/jira/WEB-INF/lib directory.tomcat/lib
.If your JIRA installation is connected to a MySQL database that uses the MyISAM database engine (which is not recommended), some table indexes may not be created successfully upon upgrading to JIRA 4.4.x. MyISAM is not recommended for JIRA as its use can lead to serious data corruption — see JRA-24124 for details.
Before upgrading, we recommend switching your MySQL database for JIRA over to the InnoDB database engine.
If you run JIRA on a 64-bit Windows operating system, be aware that the version of Apache Tomcat (6.0.20) bundled with JIRA Standalone cannot run as a Windows service on a 64-bit JDK/JRE (see JRA-12965).
If you need to run JIRA as a Windows service on a 64-bit Windows operating system, we recommend installing the JIRA WAR-EAR distribution on Apache Tomcat version 6.0.26 or greater.
Please be aware that only GreenHopper 5.5 (and later) is compatible with JIRA 4.3.x.
If your existing version of GreenHopper is not compatible with JIRA 4.3.x, perform your GreenHopper upgrade immediately after performing your JIRA upgrade.
If you use the Toolkit Plugin with JIRA, you will need to update it to at least version 0.17 for compatibility with JIRA 4.3.
JIRA 4.2 supports the universal plugin manager. If you installed this plugin into your JIRA 4.2 installation, we recommend removing it from your JIRA Home directory while upgrading to JIRA 4.3 or later, as the presence of this plugin may cause problems when JIRA 4.3 is started.
When upgrading JIRA, remove this plugin before step 3.5 of the 'in-place database upgrade' or migration procedures.
The universal plugin manager plugin is located at:
<JIRA-home-directory>/plugins/installed-plugins/atlassian-universal-plugin-manager-plugin-X.Y.Z.jar
JIRA 4.3 introduces several changes that may break existing plugins which are not bundled with JIRA.
If you have a developed a plugin, then please read the Plugin Developer Notes for JIRA 4.3 guide. This guide describes changes in JIRA 4.3 which may affect the compatibility of your plugin with JIRA 4.3.
If you are using a plugin developed by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.3.
As mentioned on our End of Support Announcements for JIRA page, from JIRA 4.3, we will no longer provide support for the following platforms with JIRA:
Please see the Supported Platforms for a list of supported browsers, databases and application servers.
JIRA does not support running in multitenant mode.
Before you begin the upgrade, please check for known issues. Sometimes we find out about a problem with the latest version of JIRA after we have released the software. In such cases we publish information about the known issues in the JIRA Knowledge Base. Please check for known issues and follow the instructions to apply any necessary patches.
If you encounter a problem during the upgrade and cannot solve it, please create a support ticket and one of our support engineers will help you.
In addition to the points listed above, please read the Important Version-Specific Upgrade Notes for the versions of JIRA you are skipping.
JIRA 4.3 now officially supports 'in-place database upgrades' when upgrading from JIRA 4.0.0 or later. This method requires much less downtime during the JIRA upgrade process, especially if you operate a large JIRA installation. You no longer need to export your existing JIRA data to an XML backup and then restore this data into your new JIRA version. Instead, we now support simply 'pointing' your new version of JIRA at your existing JIRA database!