Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

The following steps describe how to upgrade WSO2 Application Server from version 5.2.1 to 5.3.0. To upgrade from a version older than 5.2.1, start from the documentation that was released immediately after your current release and upgrade incrementally. For more information on release versions, see the Release Matrix

If you want to migrate your WSO2 AS configurations from one instance to another (such as when promoting your instance from test to production) using the same AS version, see Migrating the Application Server.

The instructions on this page takes you through the steps for upgrading from AS 5.2.1 to AS 5.3.0. This includes upgrading the database changes as well as the configurations that should follow the upgrade.

You cannot rollback the upgrade process. However, It is possible to restore a backup of the previous database and restart the upgrade progress.

Preparing to upgrade

The following prerequisites must be completed before upgrading:

The downtime is limited to the time taken for switching databases when in the production environment.

Upgrading the database

There are no registry and user database schema changes between AS 5.2.1 and 5.3.0. Therefore, you do not need to do any database schema migration. 

You should NOT connect a new version of WSO2 AS to an older database that has not been upgraded.

Migrating the configurations

The following topics explain the configuration changes that needs to be updated for AS 5.3.0:

Updating the configuration files

The following are the updates that need to be done to the configuration files in AS 5.3.0.

Note that configuration files should not be copied directly between servers.

  1. Create a new database for AS 5.3.0 and restore the backup of the old database in this new database.
  2. To connect AS 5.3.0 to the upgraded database, configure the following files:
    1. Configure the <AS_HOME_5.3.0>/repository/conf/datasources/master­datasources.xml file as shown in the following example:

      user manager</description>
      <description>The datasource used for registry and
      <definition type="RDBMS">
    2. Go to the <AS _HOME_5.3.0>/repository/conf/ directory and update the datasource references in the user-­mgt.xml and registry.xml files to match the updated configurations in the master­datasources.xml file. The following are sample configurations if the datasource is “jdbc/WSO2CarbonDB”:


      <dbConfig name="wso2registry">


  3. The configurations for SaaS web applications has changed in AS 5.3.0. In previous releases, SaaS configurations were enabled in the web.xml file of web application by adding a context-param called carbon.enable.saasIn AS 5.3.0, SaaS is configured via the context.xml file that needs to be placed under the META-INF/ folder of the web application. See the more details about configuring SaaS applications in AS 5.3.0 from here.
  4. Prior to AS 5.3.0, the primary keystore configured in the carbon.xml file was used for securing transports. In AS 5.3.0, the keystore used for transports should be separately configured in the catalina-server.xml file.

    The “RegistryKeyStore” configuration in carbon.xml is removed. See the section on configuring keystores for more information.

  5. Check for any other configurations that were done for AS 5.2.1 (based on your solutions), and update the configuration files in AS 5.3.0 accordingly. For example, external user stores, caching, mounting, etc.

Migrating third party libraries

If there are third party libraries used with AS 5.2.1 that you want to migrate, copy them to the following directories in AS 5.3.0 as applicable.

  1. If you have used JDBC drivers etc, copy them to the <AS_HOME>/repository/components/lib directory.
  2. If you have used OSGi bundles such as SVNKit etc, copy them to the <AS_HOME>/repository/components/dropins directory.   

Migrating the services and artifacts

You can migrate all artifacts relevant to the super tenant as well as the ordinary tenants by copying the following directories from the old server to the new server.

  1. To migrate the super tenant’s artifacts, copy the <AS_HOME>/repository/deployment/server/ directory from AS 5.2.1 to AS 5.3.0.

  2. If you are using multi­tenancy, copy the <AS_HOME>/repository/tenants directory from AS 5.2.1 to AS 5.3.0.

  3. Since the Axis2 Quality of Services UI to apply policies such security has been removed from the management console, users need to use alternative mechanisms and apply the policies for their services. For Axis2 AAR services, the policies can be applied through the services.xml. Refer <link to page on how to apply QoS configuration if any> for more details. 

  4.  In AS 5.3.0, it is not possible to globally engage modules using the management console. Therefore, you need to update the axis2.xml file in the <AS_HOME>/repository/conf/axis2 directory as shown below. You can find more information on engaging modules for axis2 services from here.

    <axisconfig name="AxisJava2.0">
        <module ref=”addressing”/>

Testing the upgrade

  1. When the database upgrade scripts are executed, the following are some of the new tables that will be created in the database:
  2. Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.
  • No labels