JIRA 4.3 Upgrade Guide

Still need help?

The Atlassian Community is here for you.

Ask the community

On this page:

Upgrading from JIRA 4.2 to 4.3

General upgrade instructions

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).

'In-place database upgrade' is now the recommended method

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!

Changes in 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.
(info) The purpose of each new property is documented in the jira-application.properties file itself.

New properties in jira-application.properties

jira.websudo.is.disabled = false

jira.websudo.timeout = 10

As a result of changes in JIRA 4.3 to the 'Issue Links' section of the 'view issue' page, the jira.table.cols.linkedissue property is no longer recognised by JIRA. Modifying the value of this property in the jira-application.properties file will not influence the order of columns represented in this section of the 'view issue' page.

Changes in seraph-config.xml and Crowd Integration

When 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:

  • Due to Crowd integration changes in JIRA 4.3 (reflected in seraph-config.xml), your users may have authentication problems when attempting to log in to JIRA.
  • If any user attempts to view a JIRA page URL which they do not have permission to access, JIRA will not explicitly indicate a permission access problem.

The following table lists the changes to the seraph-config.xml file in JIRA 4.3:

Elements in seraph-config.xml prior to JIRA 4.3

Change in JIRA 4.3

<param-name>login.url</param-name>
<param-value>/login.jsp?os_destination=${originalurl}</param-value>

<param-value>/login.jsp?os_destination=${originalurl}</param-value>has been changed to

<param-value>/login.jsp?permissionViolation=true&amp;os_destination=${originalurl}</param-value>
<param-name>invalidate.session.exclude.list</param-name>
<param-value>ASESSIONID</param-value>

<param-value>ASESSIONID</param-value>has been changed to

<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 -->

<interceptor class="com.atlassian.jira.portal.PortalPageInterceptor"/>

Removed as this <interceptor> class entry is no longer required in JIRA 4.3.

Gadgets can only access External URLs that are on the Whitelist

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.

Changes to user management in JIRA

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.

Upgrade considerations

For customers with internally managed users

For users that are not currently connecting to Crowd or LDAP then there are no actions required on upgrade.

For customers using LDAP for authentication

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:

  • Prior to JIRA version 4.3, the 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 the upgrade process is started.
  • If some of your users' passwords are stored in an LDAP directory but other users' passwords are stored in JIRA's internal user directory, you should not upgrade at this time (see JRA-23858). Please wait for JIRA 4.3.1.
  • Regardless of which method you use to upgrade JIRA, when migrating your existing JIRA configurations to your new JIRA installation at the configuration migration step of either the 'in-place database upgrade' or migration procedures, ensure that you copy the 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.

For customers connecting to Crowd for user management

(warning) 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:

  • Prior to JIRA version 4.3, the 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 the upgrade process is started.
  • Regardless of which method you use to upgrade JIRA, when migrating your existing JIRA configurations to your new JIRA installation at the configuration migration step of either the 'in-place database upgrade' or migration procedures, ensure that you copy the 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.

For customers with a pre-Confluence 3.5 installation that uses JIRA for user management (IMPORTANT!)

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.

For customers who have written a custom provider for user management

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 have written a custom provider to provide LDAP support for JIRA 4.2 or earlier, you may no longer need your custom directory connector. Please check the supported LDAP schemas to see if you can use the new LDAP connectors supplied with JIRA 4.3.
  • If you have written a custom provider to support nested groups, you can now use the new directory connectors supplied with JIRA 4.3. See Managing Nested Groups.
  • If you have written a custom provider to connect to your own database, please consider loading the data into JIRA. For target upgrade versions 6.1 and above, you could complete your upgrade and do this using the JIRA REST API. If you need to use an external authentication source, consider migrating to a Seraph authenticator.

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.

For customers with non-standard configurations

If you have a non-standard configuration and the upgrade has stopped, please contact http://support.atlassian.com.

Other considerations

Duplicate groups MUST BE DELETED before upgrading

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.)

Database tables have changed

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.
This now includes full name and email address.

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.

Usernames are not case sensitive

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:

  • A user may not be able to log in because their password was attached to the dropped user. The user will need to reset their password.
Passwords no longer imported when importing a project

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.

Migrating to LDAP user management

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.

Considerations
  • Are user names the same?
    • If users have the same name in the LDAP directory as they do in the internal JIRA directory, then you can simply configure a new LDAP directory and then disable the internal directory. This would also apply if you are currently using LDAP authentication.
    • If users have different names in the LDAP directory to that in JIRA, then you could configure an LDAP directory to be used for new users and leave the internal directory in place for current JIRA users.

Migrating from an Internal Directory with LDAP Authentication to a full LDAP directory.

Background

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.

What happens when upgrading to JIRA 4.3

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:

  • An Internal Directory with Delegated LDAP, this is where all your users will be defined.
  • An Internal Directory, this will not contain any users, but is required. More about this later.

If the osuser.xml file is not available during the upgrade then JIRA will create 1 user directory configuration entry:

  • An Internal Directory, this is where all your users will be defined. Note: The users' passwords in this directory will not be set and no users will not be able to login until you reset the passwords.

Note: If you wish to continue to use LDAP for authentication only, then ensure the osuser.xml is available during the upgrade.

Migrating to full LDAP

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.

Migrating from Internal with LDAP authentication to LDAP

The steps are:

  • Add a user to the Internal Directory that has System Administrator privileges.
    • Reorder the directories so that the Internal Directory is first in the list.
    • Add a new user and give that user System Administrator privileges. New users are always added to the first directory that is not READ-ONLY.
  • Log out and back in to JIRA as the user you just added.
  • Add a new LDAP directory to the list of User Directories.
  • Wait for the LDAP directory to be fully synchronised for the first time. This may take some time depending upon the number of users and speed of the LDAP server and your connection to it.
  • Re-order the directories so that the Internal Directory with LDAP authentication is at the bottom of the list and the new LDAP directory is at the top of the list.
  • Logoff
  • Login as a user with System Administrator privileges.
  • Go to Administration / User Browser and search for the user you logged in as. The user should show as coming from the LDAP directory you just added.
  • Disable the Internal Directory with LDAP authentication.

Once you have completed testing you may delete the Internal Directory with LDAP authentication.

Migrating from Internal Directory to LDAP

The steps are:

  • Log in to JIRA with as a user with System Administrator privileges.
  • Add a new LDAP directory to the list of User Directories.
  • Wait for the LDAP directory to be fully synchronised for the first time. This may take some time depending upon the number of users and speed of the LDAP server and your connection to it.
  • Re-order the directories so that the new LDAP directory is at the top of the list.

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.

Known LDAP issues when upgrading to JIRA 4.3

Additional JARs required when running JIRA WAR on Tomcat

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 5

Tomcat 6

Upgrading JIRA connected to a MySQL database

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.3. 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.

Upgrading JIRA running on a 64-bit Windows operating system

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.

GreenHopper

Please be aware that only GreenHopper 5.5 (and later) is compatible with JIRA 4.3.x.
(tick) If your existing version of GreenHopper is not compatible with JIRA 4.3.x, perform your GreenHopper upgrade immediately after performing your JIRA upgrade.

Updated Toolkit Plugin for JIRA 4.3

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.

Upgrading from JIRA 4.2 with the Universal Plugin Manager installed

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

Other Plugins

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.

Older Browsers are no longer supported

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.

Unsupported Modes

JIRA does not support running in multitenant mode.

Other Known Issues

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.

Upgrading from JIRA 4.1 and Earlier

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!

Last modified on Feb 27, 2014

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.