This chapter explains how to upgrade your existing system to the latest release of Oracle Communications Contacts Server.
Note:
If you are migrating Contacts Server deployment from GlassFish Server to WebLogic Server, perform the following steps:Ensure to upgrade your existing Contacts Server deployed on GlassFish Server to Contacts Server version 8.x (the recommended version is, 8.0.0.4.0).
Set up WebLogic Server on a new server with Contacts Server version 8.0.0.5.0 or above which has WebLogic container support.
Ensure to configure your Contacts Server on WebLogic Server deployment with your required backend server accordingly when migration is completed.
If your deployment uses document stores, upgrading requires you to also upgrade those document stores at the same time, as described in this chapter.
When performing an upgrade of Contacts Server, you must upgrade all front-end hosts and remote document store hosts (if applicable) to the same version. That is, you cannot have a deployment of mixed Contacts Server versions. Contacts Server upgrades may introduce back-end database schema changes, or the front-end hosts may access the database in a different way. Thus, all hosts must be at the same version.
Each Contacts Server patch or release might require an upgrade to the database schema or structure. For example, a database table might be altered, or data in the database might be changed. This type of upgrade differs from a MySQL Server or Oracle Database version upgrade. If a Contacts Server database schema or structure upgrade is required, allow additional time for the overall Contacts Server upgrade, as the database upgrade can take a while, especially if the database is large.
Topics in this section:
Each database schema and structure has a Contacts Server back-end version number recorded in the database. Each Contacts Server version only runs with a single database schema version.
You cannot reverse or downgrade a database schema version to a previous version. Thus, always ensure that you take a full database backup prior to upgrading. Once a database is upgraded, if you attempt to revert to a previous Contacts Server version, the previous Contacts Server version does not recognize the newly upgraded database. However, not all Contacts Server versions involve a database schema upgrade. When this is the case, you can revert to a previous Contacts Server version without invalidating the databases. Use Table 10-1, "Database Schema Version Changes for Contacts Server" to understand which Contacts Server versions use the same database schema.
When Contacts Server starts up in the application server container, it connects to each back-end database for which it is configured, one at a time, and attempts to open the database for normal operation.
During this initial opening of each database, Contacts Server checks the database schema version. Contacts Server has the option to either automatically upgrade the database immediately, or issue a logging message in the errors.0 log file explaining the database cannot be opened and needs to be upgraded.
Caution:
Never interrupt or stop either Contacts Server or application server while the database is being upgraded.Contacts Server logs messages in the errors.0 log file when the database was opened but not that it was being upgraded. If the database has a large amount of data, the upgrade can take a long time and appear to resemble a database hang. See "Database Schema Upgrade Patches and Releases" for more information on Contacts Server versions that require a database upgrade.
You cannot reverse a database schema and structure upgrade once it has been performed. This is why, when performing a Contacts Server upgrade, you must make a backup before starting the upgrade process. Once a database is upgraded, it no longer works with a previous Contacts Server version. Use Table 10-1 to understand the Contacts Server database changes that have occurred.
How a database performs during an upgrade depends on data size and hardware. Some database operations, such as copying the entire table, are intensive operations and can take a long time to complete. When a database has 4 million rows or 40 gigabytes of data, study the database performance to better understand potential upgrade times.
MySQL Server and Oracle Database have relevant buffer cache settings that can increase performance. Additionally, if the database can fit in the cache completely with extra space, then operations might run faster.
If the database and temporary table operations exceed the database cache, then the disk IO throughput becomes very relevant. Disk IO is also significant when there is plenty of cache because the cache must be loaded at times.
MySQL Server also has memory and cache parameters such as innodb_buffer_pool_size, while Oracle Database has parameters such as sga_target. Refer to the MySQL Server and Oracle Database documentation for more information on performance tuning.
In general, upgrading the database schema should not take a long time. However, there are some exceptions. See Table 10-1, "Database Schema Version Changes for Contacts Server" for more information. Additionally, as explained in "Database Performance During Upgrade", other factors can impact the time required to upgrade the database schema, and thus the overall Calendar Server upgrade time.
To increase database upgrade functionality and flexibility, you can use the davadmin db schema_fullupgrade and davadmin db schema_preupgrade commands. Table 10-2 describes these two commands.
Table 10-2 Comparison of schema_fullupgrade and schema_preupgrade
| Description of schema_fullupgrade | Description of schema_preupgrade |
|---|---|
|
The schema_fullupgrade command fully upgrades the back-end database schema. The schema_fullupgrade command performs all upgrade functions on the database, including upgrading the presence and all database tables for charset. The schema_fullupgrade command is the same as starting a new Contacts Server instance, which upgrades the database. Use this command to upgrade multiple back-end databases in parallel instead of one at a time, as happens during the normal Contacts Server upgrade process. For example, if your deployment consists of four back-end databases, instead of going through the normal upgrade process where upgrading a front-end host then initiates the back-end database upgrade, one at a time, you can upgrade the front-end hosts then upgrade all back-end databases in parallel by using the schema_fullupgrade option. After running the schema_fullupgrade command and the database schema upgrade completes, you cannot revert to the previous schema. In addition, Contacts Server front-end hosts that run a prior software version are not able to communicate with the database that has had its schema upgraded. |
The schema_preupgrade command enables you to perform online database DDL changes, as well as a partial offline upgrade, as long as the release contains database schema updates. (Not all releases update the database schema, so schema_preupgrade might not apply.) For example, if your deployment contains a large amount of data, you can save time by pre-upgrading the database schema in advance of the formal Contacts Server software upgrade. The schema_preupgrade command does not change the database schema version, and therefore, Contacts Server front-end hosts continue to be able to communicate with the pre-upgraded database without having to be upgraded themselves. You specify the function to upgrade by using with the -z preupgradefunction option. See Table 10-3 for a list of functions by release. For example, if a Contacts Server upgrade adds a new column to the database, you can run the schema_preupgrade command to add that column to the current database. The Contacts Server front-end hosts, which have not yet been upgraded themselves, continue to have the capability to run with the pre-upgraded database version. When you later perform the formal Contacts Server software upgrade, the schema update has already been done, and so you save time on completing the overall upgrade process. |
See the davadmin db schema_fullupgrade and davadmin db schema_preupgrade commands in "Contacts Server Command-Line Utilities" in Contacts Server System Administrator's Guide for more information.
The davadmin db schema_preupgrade -z preupgradefunction command enables you to specify which pre-upgrade function(s) to run on the database. Table 10-3 describes the available functions by release.
This section describes how to upgrade to Contacts Server 8.0.0.x. Depending on your current Contacts Server version, some steps are not required.
Download the Contacts Server software and Directory Server setup script, comm_dssetup (if a newer version is required), either as part of a media pack, or as a patch.
Download the media pack from the Oracle software delivery website.
Download a Contacts Server patch or Directory Server setup patch from My Oracle Support. Contacts Server 8.0.0.x currently requires at least version 6.4-26.01 of comm_dssetup.
Place the Contacts Server software on the appropriate Contacts Server hosts, and the Directory Server setup script software on the appropriate Directory Server hosts.
On Contacts Server front-end hosts, and, if applicable, remote document store hosts, create a temporary directory (for example, /temp/CS8), and extract the Contacts Server media pack zip file or Contacts Server patch zip file in this directory.
The purpose of backing up the database is in case you must restore the previous Contacts Server version and database. However, database backups are not compatible across releases because backups include database internals specific to the version.
For more information, see the topic on backing up and restoring files and data in Contacts Server System Administrator's Guide.
You may be able to upgrade parts of the database schema as a separate step, outside of and in advance of, the formal Contacts Server upgrade process, if pre-upgrade functions exist for the release. (Not all Contacts Server versions update the database schema, so this capability might not apply.) Before upgrading the database schema, ensure that you understand the implications as described in "About Upgrading the Database Schema". Also, review Table 10-1, "Database Schema Version Changes for Contacts Server" to confirm if the Contacts Server version upgrades the database schema. See the topic on the davadmin db schema_preupgrade command in Contacts Server System Administrator's Guide for more information.
Make sure you have run the required version of the comm_dssetup.pl script against your Directory Server hosts.
To run comm_dssetup.pl:
On each Directory Server host, run commpkg install (or commpkg upgrade if comm_dssetup.pl exists already on the host), and select only Comms DSsetup 6.4.
On each Directory Server host, run the comm_dssetup.pl script to apply the schema updates.
For example:
/opt/sun/comms/dssetup/sbin/comm_dssetup.pl
Respond to the prompts.
For more information, see "commpkg Reference".
This section assumes that you have previously put the Contacts Server software onto each Contacts Server front-end host and remote document store host, if applicable. If instead you are performing an upgrade of the Contacts Server software by applying a patch, see the instructions in "Installing Patches" then return to this chapter to resume the upgrade process.
On the Contacts Server front-end hosts, run commpkg upgrade and select the Contacts Server component.
For more information, see "upgrade Verb Syntax".
If the upgrade detects a problem during the pre-upgrade phase, correct the problem and re-run the upgrade.
If you have remote document stores, continue with the next section.
When upgrading Contacts Server front-end hosts, you must also upgrade the remote document store hosts at the same time. These instructions describe both how to upgrade document stores that are not configured to use SSL, and how to add SSL if you choose. These instructions also assume that you have downloaded and extracted the Contacts Server software zip file or Contacts Server patch zip file onto the remote document store hosts.
Topics:
To upgrade a document store that is not configured for SSL:
Perform the following steps on the remote document store host.
Stop the document store server.
cd ContactsServer_home/sbin
stop-as
Upgrade the Contacts Server software by launching the Communications Suite Installer and choosing Contacts Server. If you are applying a patch, see the instructions in "Installing Patches" then return to this chapter to resume the upgrade process.
commpkg upgrade
Configure the document store and set the password.
cd ContactsServer_home/sbin configure-as Do you want to set the document store password (y/n)? [n] y Enter the document store password: password Reenter the document store password: password Do you want to set the document store SSL passwords (y/n)? n Please check the values in /var/opt/sun/comms/nabserver/config/ashttpd.properties are correct before starting the server with start-as To stop the server, run stop-as
Start the document store server.
cd ContactsServer_home/sbin
start-as
Perform the following steps on the Contacts Server front-end host after you have upgraded the Contacts Server software.
Set the same document store password that you used during the configuration on the document store host.
cd ContactsServer_home/sbin davadmin passfile modify Enter Admin password: password Enter the Password File password: password Do you want to set the app server admin user password (y/n)? [n] Do you want to set the database password (y/n)? [n] Do you want to set the migration server user password (y/n)? [n] Do you want to set the document store password (y/n)? [n] y Enter the document store password: <Enter the same password that you used when running the configure-as command on the document store host.> Reenter the document store password: password Do you want to set the document store SSL passwords (y/n)? [n] n Set new value for store.document.password.
Restart the application server.
To upgrade a non-SSL document store to SSL:
Perform the following steps on the remote document store host.
Stop the document store server.
cd ContactServer_home/sbin
stop-as
Upgrade the Contacts Server software by launching the Communications Suite Installer and choosing Contacts Server. If you are applying a patch, see the instructions in "Installing Patches" then return to this chapter to resume the upgrade process.
commpkg upgrade
Create a self-signed certificate.
keytool -genkeypair -alias alias -keyalg RSA -validity 365 -keysize 2048 -keystore path/keystore_name.jks
Export the certificate and copy it to the Contacts Server host.
keytool -export -alias alias -keystore path/keystore_name.jks -rfc -file path/certificate.cert
Configure the document store.
cd ContactsServer_home/sbin configure-as Do you want to set the document store password (y/n)? [n] y Enter the document store password: password Reenter the document store password: password Do you want to set the document store SSL passwords (y/n)? [n] y Enter the document store SSL keystore password: <Enter the same password that you used when creating the self-signed certificate, that is, the keystore password> Reenter the document store SSL keystore password: password Enter the document store SSL certificate password: <Enter the same password that you used when creating the self-signed certificate, that is, the keystore password> Reenter the document store SSL certificate password: password Please check the values in /var/opt/sun/comms/nabserver/config/ashttpd.properties are correct before starting the server with start-as To stop the server, run stop-as Document Store server is now configured
Add the following lines to the ashttpd.properties file.
store.usessl=true store.sslkeystorepath=path/keystore_name.jks
Start the document store.
Perform the following steps on the Contacts Server front-end host after you have upgraded the Contacts Server software.
Import the certificate (the certificate that you copied from the document store host) into the TrustStore on the application server host where you have deployed Contacts Server.
keytool -importcert -alias alias -file path/certificate.cert -keystore /opt/glassfish3/glassfish/domains/domain1/config/cacerts.jks
List the KeyStore to ensure that the alias exists.
keytool -list -keystore /opt/glassfish3/glassfish/domains/domain1/config/cacerts.jks -alias alias
Set the same document store password that you set during the document store configuration.
davadmin passfile modify Enter Admin password: password Enter the Password File password: password Do you want to set the app server admin user password (y/n)? [n] Do you want to set the database password (y/n)? [n] Do you want to set the migration server user password (y/n)? [n] Do you want to set the document store password (y/n)? [n] y Enter the document store password: <Enter the same password that you gave during configure-as on document store host> Reenter the document store password: password Do you want to set the document store SSL passwords (y/n)? [n] n Set new value for store.document.password. A server restart is required for this change to take effect.
Set the store.document.usessl configuration parameter to true.
davadmin config modify -o store.document.usessl -v true
Enter Admin password: password
Set new value for store.document.usessl. A server restart is required for this change to take effect.
Restart the application server.
To perform the configuration:
Run the init-config script to enter the current deployment configuration values.
Run the merge-config script to merge in any other changes that were done to the configuration after the initial configuration, and that are not controlled by the init-config script.
For example, you might have customized configuration parameters in the davserver.properties file.
If necessary, resolve any problems.
If the upgrade detects a problem during the post-upgrade phase with merging configuration files, reconcile the merged files.
The davadmin account upgrade operation sets the next presence triggers for all existing events in the future. You must run davadmin account upgrade after upgrading Contacts Server to set the presence triggers for existing future events.
To set presence triggers after upgrading:
davadmin acount upgrade
Currently, davadmin account upgrade does not print a message either while it is running or when it completes. The davadmin account upgrade command could take some time to complete, so allow it to finish. While davadmin account upgrade is running, it does not impact any Contacts Server functionality.