Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The instructions on this page takes you through the steps for upgrading to AS following steps describe how to upgrade WSO2 Application Server from version 5.2.1 version to 5.3.0. To upgrade from a previous AS versionversion older than 5.2.1, start from the documentation that was released immediately after your current release and upgrade incrementallyFor more information on release versions, see the Release Matrix

Info
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 following two upgrades are separately explained in these instructions .

...

on

...

Go to the respective tabs given below to find the relevant instructions.

 

...

titleUpgrading from AS 5.1.0

...

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.

Warning

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:

  • Make a backup of the user and registry databases of AS 5.2.1

...

  • Make a backup of <AS_HOME_5.

...

  • 2.1> folder to backup the product configurations. 

  • Download WSO2 Application Server 5.

...

  • 3.

...

Note

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

 

Upgrading the database

...

  1. Before you upgrade to AS 5.2.1, create a new database and restore the backup of the old database in this new database.

    Note

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

  2. Select the relevant script for the upgrade from here and run it on the new database. Running this script will ensure that the database is upgraded with the additional tables and schemas that are required for AS 5.2.1.

    Note

    There are three migration scripts available: migration­service­provider.sql, migration­identity.sql and migration.sql. However, note that only the migration.sql script is required to be executed for AS 5.2.1.

Once you run the migration scripts on the new database, it becomes the upgraded database for AS 5.2.1.

Migrating the configurations

...

/registry

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. 

Migrating the configurations

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

Table of Contents
maxLevel4
minLevel4

Updating the configuration files

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

...

3.

...

0.

Note

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.

...

  1. 3.

...

  1. 0 to the upgraded database, configure the following files:
    1. Configure the <AS_HOME_5.

...

    1. 3.

...

    1. 0>/repository/conf/datasources/master­datasources.xml file as shown in the following example:

      Code Block
      <datasource>
      user manager</description>
      <name>WSO2_CARBON_DB</name>
      <description>The datasource used for registry and
      <jndiConfig>
      <name>jdbc/WSO2CarbonDB</name>
      </jndiConfig>
      <definition type="RDBMS">
      <configuration>
      <url>jdbc:mysql://localhost:3306/<new_database></url>
      <username>username</username>
      <password>password</password>
      <driverClassName>com.mysql.jdbc.Driver</driverClassName>
      <maxActive>80</maxActive>
      <maxWait>60000</maxWait>
      <minIdle>5</minIdle>
      <testOnBorrow>true</testOnBorrow>
      <validationQuery>SELECT
      1</validationQuery>
      <validationInterval>30000</validationInterval>
      </configuration>
      </definition>
      </datasource>
    2. Go to the <AS _HOME_5.

...

    1. 3.

...

    1. 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”:

      registry.xml

      Code Block
      <dbConfig name="wso2registry">
      <dataSource>jdbc/WSO2CarbonDB</dataSource>
      </dbConfig>

      user­mgt.xml

      Code Block
      <UserManager>
      <Realm>
      <Configuration>
      ...
      <Property
      name="dataSource">jdbc/WSO2CarbonDB</Property>
      </Configuration>
      ...
      </Realm>
      </UserManager>
  1. Data services feature is no longer shipped with WSO2 Application Server. If you need to use the data services hosting feature, you have two options:
    1. Install the Data Services hosting feature from the public p2-repo. See Installing Features for instructions.

    2. Use the WSO2 Data Services Server product which can be downloaded from http://wso2.com/products/data-services-server/. See the About this Release page to check if the latest WSO2 DSS is compatible with the current AS version.

  2. 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 the 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 more details about configuring SaaS applications in AS 5.3.0 from here.
  3. 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.

    Note

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

  4. Check for any other configurations that were done for AS 5.2.1

...

  1. (based on your solutions), and update the configuration files in AS 5.

...

  1. 3.

...

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

...

  • carbon.xml
  • identity.xml
  • log4j.properties
  • user­mgt.xml
  • axis2.xml
  • axis2_client.xml
  • tenant­axis2.xml
  • thrift­agent­config.xml
  • bam.xml
  • cache.xml
  • config­validation.xml
  • launch.ini
  • cloud­services­desc.xml
  • authenticators.xml
  • cipher­text.properties
  • cipher­tool.properties
  • catalina­server.xml
  • webapp­classloading­environments.xml

The following configuration files are newly added to AS 5.2.1:

  • trusted­idp­config.xml
  • logging­bridge.properties

...

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

...

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

...

  1. to AS 5.

...

  1. 3.

...

  1. 0.

  2. If you are using multi­tenancy

...

  1. , copy the <AS_HOME>/repository/tenants

...

  1.  directory from AS 5.2.1

...

  1. Open the metadata files corresponding to the axis services from the following locations:
    1. The metadata files of axis services for the super tenant are stored in the <AS_HOME_5.2.1>/repository/deployment/server/servicemetafiles/ folder.
    2. The metadata files of axis services for each tenant can be found in the <AS_HOME_5.2.1>/repository/tenants/<Tenant_No>/servicemetafiles/ folder.
  2. When you open each metadata file, remove all occurrences of the following:

    Code Block
    <module name="activation" version="2.1.0" type="engagedModules"/

...

  1. For the super tenant, these applications should be moved from the <AS_HOME_5.2.1>/repository/deployment/server/jaxwebapps/ folder to the <AS_HOME_5.2.1>/repository/deployment/server/webapps/ folder.
  2. For other tenants, these applications should be moved from the <AS_HOME_5.2.1>/repository/tenants/<Tenant_No>/jaxwebapps/ folder to the <AS_HOME_5.2.1>/repository/tenants/<Tenant_No>/webapp/ folder.

...

If you have a Composite Application Archive (CAR) file in AS 5.1.0, you can manually deploy using the management console of AS 5.2.1. See the topic on Creating and Deploying Carbon Applications for instructions. Alternatively, without using the management console of AS 5.2.1, you can directly copy the following directories:

...

For super tenant, copy the <AS_HOME_5.1.0>/repository/carbonapps/0/ directory to the <AS_HOME_5.2.1>/repository/deployment/server/carbonapps/ directory.

...

  1. to AS 5.3.0.

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

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

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

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:
    • UM_DOMAIN
    • UM_SYSTEM_USER
    • UM_SYSTEM_ROLE
    • UM_SYSTEM_USER_ROLE
  2. Verify that all the required scenarios are working as expected as shown below. This confirms that the upgrade is successful.

      ...

      titleUpgrading from AS 5.2.0
        1. Start the AS 5.

      ...

      Preparing to upgrade

      The following prerequisites must be completed before upgrading:

      Note

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

      Migrating the configurations

      Since there are no database changes between these two AS versions, you are only required to migrate the configurations and settings from AS 5.2.0 to AS 5.2.1 as explained below.

      Updating the configuration files

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

      Note

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

      ...

      Configure the <AS_HOME_5.2.1>/repository/conf/datasources/master­datasources.xml file as shown in the following example:

      Code Block
      <datasource>
      user manager</description>
      <name>WSO2_CARBON_DB</name>
      <description>The datasource used for registry and
      <jndiConfig>
      <name>jdbc/WSO2CarbonDB</name>
      </jndiConfig>
      <definition type="RDBMS">
      <configuration>
      <url>jdbc:mysql://localhost:3306/<new_database></url>
      <username>username</username>
      <password>password</password>
      <driverClassName>com.mysql.jdbc.Driver</driverClassName>
      <maxActive>80</maxActive>
      <maxWait>60000</maxWait>
      <minIdle>5</minIdle>
      <testOnBorrow>true</testOnBorrow>
      <validationQuery>SELECT
      1</validationQuery>
      <validationInterval>30000</validationInterval>
      </configuration>
      </definition>
      </datasource>

      ...

      Code Block
      <dbConfig name="wso2registry">
      <dataSource>jdbc/WSO2CarbonDB</dataSource>
      </dbConfig>

      user­mgt.xml

      Code Block
      <UserManager>
      <Realm>
      <Configuration>
      ...
      <Property
      name="dataSource">jdbc/WSO2CarbonDB</Property>
      </Configuration>
      ...
      </Realm>
      </UserManager>

      ...

      Migrating the tenant settings and applications

      You can migrate all artifacts etc. relevant to tenants by copying the following directories from the old server to the new server.

      1. To migrate the deployment artifacts, copy the <AS_HOME>/repository/deployment/server/ directory from AS 5.2.0 to AS 5.2.1.
      2. If multi­tenancy is used, copy the <AS_HOME>/repository/tenants/ directory from AS 5.2.0 to AS 5.2.1.
      3. If axis based services are included in the directories that were copied above, you must do the following:
        1. Open the metadata files corresponding to the axis services from the following locations:
          1. The metadata files of axis services for the super tenant are stored in the <AS_HOME_5.2.1>/repository/deployment/server/servicemetafiles/ folder.
          2. The metadata files of axis services for each tenant can be found in the <AS_HOME_5.2.1>/repository/tenants/<Tenant_No>/servicemetafiles/ folder.
        2. When you open each metadata file, remove all occurrences of the following:

          Code Block
          <module name="activation" version="2.1.0" type="engagedModules"/
      4. If any JAXRS and JAXWS applications were copied from the old server (in step 1 and step 2), they must be moved as follows:
        1. For the super tenant, these applications should be moved from the <AS_HOME_5.2.1>/repository/deployment/server/jaxwebapps/ folder to the <AS_HOME_5.2.1>/repository/deployment/server/webapps/ folder.
        2. For other tenants, these applications should be moved from the <AS_HOME_5.2.1>/repository/tenants/<Tenant_No>/jaxwebapps/ folder to the <AS_HOME_5.2.1>/repository/tenants/<Tenant_No>/webapp/ folder.
      5. Start WSO2 Application Server 5.2.1.
      6. If you have a Composite Application Archive (CAR) file in AS 5.1.0, you can manually deploy using the management console of AS 5.2.1. See the topic on Creating and Deploying Carbon Applications for instructions. Alternatively, without using the management console of AS 5.2.1, you can directly copy the following directories:

        1. For super tenant, copy the <AS_HOME_5.1.0>/repository/carbonapps/0/ directory to the <AS_HOME_5.2.1>/repository/deployment/server/carbonapps/ directory.

        2. For other tenants, copy the <AS_HOME_5.1.0>/repository/carbonapps/<Tenant_No>/ directory to the <AS_HOME_5.2.1>/repository/tenants/<Tenant_ID>/carbonapps/ directory.

      Testing the upgrade

      ...

        1. 3.0 server instance once the configurations are done.

        2. Make sure that the server starts up fine without any errors.

        3. Test the deployed artifacts:
          1. Log in to the management console as the super tenant.

          2. Navigate to Main -> Applications -> List.

          3. Verify the web application list shown there.

          4. Invoke a web application to verify that it works.


          5. Then, navigate to Main -> Services -> List.

          6. Verify the services list shown there.

          7. Invoke a service to verify that it works.
             

          8. Then, navigate to Main -> Carbon Applications -> List.

          9. Verify the CApp list shown there.
        4. Verify that the Users and Roles are picked up:

          1. Navigate to Configure -> Accounts & Credentials -> Users and Roles

          2. Verify that the list of users and roles are shown correctly.

          3. View the permissions of a chosen role, and make sure that the permissions are correct.
        5. If you are using multitenancy,

          1. Log in to the management console using the super tenant credentials.

          2. Navigate to Configure -> View Tenants.

          3. Verify the tenant list shown there.

          4. Then, log in to the system as a tenant and make sure that the log in is successful.