JIRA 4.3 : JIRA 4.3 Upgrade Guide
This page last changed on Mar 23, 2011 by ggaskell.
On this page:
Upgrading from JIRA 4.2 to 4.3General upgrade instructionsPlease 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 methodJIRA 4.3 now officially supports 'in-place database upgrades'. This method (which is now the recommended approach for upgrading JIRA) 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.propertiesIf 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.
Changes 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:
The following table lists the changes to the seraph-config.xml file in JIRA 4.3:
Gadgets can only access External URLs that are on the WhitelistDue 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 JIRAThe 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 considerationsFor customers with internally managed usersFor users that are not currently connecting to Crowd or LDAP then there are no actions required on upgrade. For customers using LDAP for authenticationIf 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. However, the following must be observed:
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
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. However, the following must be observed:
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 managementCustom 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 Crowdmeets your requirements. See the documentation on developing a custom directory connector for Crowd. For customers with non-standard configurationsIf you have a non-standard configuration and the upgrade has stopped, please contact http://support.atlassian.com. Other considerationsDuplicate groups MUST BE DELETED before upgradingIf 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 changedFor customers who have written programs or used other tools that access the JIRA database directly, the tables used to hold user data have changed.
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 sensitiveIn 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:
Passwords no longer imported when importing a projectWhen 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. com.opensymphony.user.UserManager is deprecatedIn releases 4.2 and earlier of JIRA, the com.opensymphony.user.UserManager is made available in the velocity context for use by email notification templates. The use of this manager is deprecated and will be removed in a future JIRA release. Migrating to LDAP user managementSome 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
Migrating from an Internal Directory with LDAP Authentication to a full LDAP directory.BackgroundIn 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.3If 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. Migrating to full LDAPEnsure 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 LDAPThe steps are:
Once you have completed testing you may delete the Internal Directory with LDAP authentication. Migrating from Internal Directory to LDAPThe 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. Known LDAP issues when upgrading to JIRA 4.3
Additional JARs required when running JIRA WAR on TomcatTomcat 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 databaseIf your JIRA installation is connected to a MySQL database that uses the MyISAM database engine (which is not recommended for JIRA), some table indexes may not be created successfully upon upgrading to JIRA 4.3.x. 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 systemIf 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. GreenHopperPlease be aware that only GreenHopper 5.5 (and later) is compatible with JIRA 4.3. Updated Toolkit Plugin for JIRA 4.3If 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 installedJIRA 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: Other PluginsJIRA 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 supportedAs 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 ModesJIRA does not support running in multitenant mode. Other Known IssuesBefore 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 EarlierIn addition to the points listed above, please read the Important Version-Specific Upgrade Guides for every version 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 (which is now the recommended approach for upgrading JIRA) 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! |
![]() |
Document generated by Confluence on Mar 27, 2011 18:40 |