If your Confluence instance contains thousands of user accounts and you are experiencing performance issues when searching for users, the following migration guide is for you.

Background

In Confluence 2.1, we introduced a new system for user management inside Confluence (atlassian-user) that was more powerful than the previous system (OSUser). However, to avoid potential upgrade issues, we continued to use OSUser when storing users in the local Confluence database.

The native atlassian-user storage format provides much more efficient searching, and greatly improves the performance of user administration and Confluence's 'user picker' pop-up. We plan on migrating all Confluence instances to the new format around version 2.6 or 2.7, but until then Confluence instances with large numbers of users can still take advantage of these performance improvements by performing the migration manually.

Migration procedure

Do not use this procedure if you have LDAP user management enabled.

This guide assumes that you are using Confluence's local users and groups. If you have already configured Confluence for LDAP user/group management and are experiencing user management slowness, please follow the guide for Requesting External User Management Support.

This guide applies to Confluence 2.1 and later.

Follow these steps to migrate your Confluence instance to atlassian-user:

  1. You will need to find out your Confluence base URL. To check this from Confluence, go to Administration > General Configuration > Base Url. Record this for later in the process.

  2. You must create backups in order to rollback to the old version if the migration is unsuccessful. Make a backup of your:
  3. Right-click on atlassian-user.xml and download it to your confluence/WEB-INF/classes directory (you can overwrite the one that's there).
  4. Are you using Confluence 2.3.x ? If so, right-click on osuser2atluser.jsp and download it to the \confluence\admin subdirectory of your Confluence install. Overwrite the existing osuser2atluser.jsp file.
  5. Restart Confluence. Login as an administrator, and go to this URL: 
    <BASEURL>/admin/osuser2atluser.jsp
    (info) Please ensure you replace <BASEURL> with the URL that you currently use to access Confluence. For example, http://confluence.atlassian.com or http://foobar.com/confluence.

  6. Click the link Begin migration. You will know the migration has been successful if you see the following: 

    Migrating users ... Users migrated successfully!
Migrating propertyset data ... Propertyset data migrated successfully!
Migrating groups ... Groups migrated successfully\!

For installations with groups that contain a large number of users, this may take a few hours to complete.

  1. If you encounter problems, please create a support ticket at http://support.atlassian.com and attach your application server logs.


  2. Stop Confluence.

  3. Remove this line from confluence/WEB-INF/classes/atlassian-user.xml: 
    <osuser key="osuserRepository" name="OSUser Repository"/>


  4. Start up Confluence and check that you can login using the administrator account you first set up when running through the Confluence Setup Wizard. If not, re-examine your steps and repeat from there. If you still cannot login, please create a support ticket at http://support.atlassian.com.