Download ECP2.1 Upgrade Node Linux

CWE
Energy Communication Platform
ECP Upgrade Guide
Node on Linux – from 1.5.6 to 2.1
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
Un ic or n S ys t em s © 2 01 1 – Un ic or n S ys tem s a .s .
J ank o vc o va 10 3 7/ 4 9, Pr ah a 7 , CZ - 17 0 0 0
Title:
CWE
Energy Communication Platform
Upgrade Guide
Author(s):
Version:
Date:
Jiří Dudek
1.2
7.2.2011
Contact:
E-mail: [email protected]
Tel.: (+420) 221 400 111
>2<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
REVISION HISTORY
Version
Date
Author
Description
1.0
29.1.2011
Jiří Dudek
Created.
1.1
30.1.2011
Martin Kazda
Revised
1.2
7.2.2011
Jiří Neuman
Added procedure for changing collation on
MySQL and MSSQL databases.
>3<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
TABLE OF CONTENTS
Revision History.................................................................................................................................................. 3
Table of Contents ............................................................................................................................................... 4
1.
UPGRADE INSTALLATION ..................................................................................................................... 5
1.1
Overview ........................................................................................................................................... 5
1.2
Content of ECP Upgrade Package ................................................................................................... 5
1.3
Upgrade Steps .................................................................................................................................. 5
2.
1.3.1
Backup of ECP ......................................................................................................................... 5
1.3.2
Upgrade of ECP ....................................................................................................................... 6
1.3.3
ECP Configuration .................................................................................................................... 8
1.3.4
Startup Upgraded ECP............................................................................................................. 8
Update of Database to Use Case-sensitive Search ................................................................................ 9
2.1
Motivation .......................................................................................................................................... 9
2.2
Procedure overview .......................................................................................................................... 9
2.3
MySQL database .............................................................................................................................. 9
2.4
MSSQL database ............................................................................................................................ 10
3.
Upgrade Recovery ................................................................................................................................. 11
4.
References ............................................................................................................................................. 12
>4<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
1.
UPGRADE INSTALLATION
1.1 Overview
This document describes upgrade of ECP application for ECP Node deployed on Linux.
1.2 Content of ECP Upgrade Package
Provided ECP upgrade package contains structure described in the following table.
Folder
Description
/doc
Directory with current upgrade documentation.
/install
Directory with ECP upgrade.
/thirdparty
Directory with thirdparty packages.
1.3 Upgrade Steps
The upgrade consists of following steps:
1. Backup of ECP
2. ECP upgrade
3. ECP configuration
4. Startup upgraded ECP
1.3.1 Backup of ECP
The upgrade makes changes into the database, keystore and application. It is required to backup the all
these sources to recover after possible failure. The backup has to be performed manually by application
administrator.
Following resources has to be backed up:
> Database – The database backup should be performed using specific tool for each database.
> Keystore – Keystore file can be located using “Module.localkeystore.path” property from module
configuration (module.properties).
> Application - Application file can be located according to the server where the ECP is deployed
- JBoss - $JBOSS_HOME/server/$SERVER_PROFILE/deploy/ECP_MODULE.ear
- Tomcat - $TOMCAT_HOME/webapps/ECP_MODULE.war
>5<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
1.3.2 Upgrade of ECP
ECP upgrade package is distributed in archive file. Before the upgrade, you will have to unzip provided
archive file by following next steps.
1. Create temporary directory for upgrade (e.g. /tmp/ecpupgrade) on the server with deployed
ECP application.
2. Copy delivered upgrade archive to the temporary directory created in the previous step.
3. Unzip the archive (in next steps the path to the unzipped upgrade directory will be called
$UPGRADE_HOME).
4. If you are using MySQL or MSSQL database, update to case-sensitive collation (see chapter 2
Update of Database to Use Case-sensitive Search).
5. Update $UPGRADE_HOME/install/upgrade_ecp_node.sh file values according to your current
system setting. Pay attention only to following attributes.
- installation_path – Path to web application container deploy directory
6. Update $UPGRADE_HOME/install/upgrade_node.properties file according to your ECP Node.
Update following properties :
Property
Description
Database
The configuration of this parameter is described in [AdminGuide] chapter
ECP module configuration parameters part Connection to database.
Database.Driver
The configuration of this parameter is described in [AdminGuide] chapter
ECP module configuration parameters part Connection to database.
Database.Dialect
The configuration of this parameter is described in [AdminGuide] chapter
ECP module configuration parameters part Connection to database.
Database.Password
The configuration of this parameter is described in [AdminGuide] chapter
ECP module configuration parameters part Connection to database.
Database.Type
Specify database type. Upgrade script chooses the right sql files
according to it. Use one from following values :
> MySql
> MSSql
> Oracle
> PostgreSql
Database.Schema
The name of database or database schema.
Database.Root.User
Database user with the administration privileges.
Database.Root.Password
Password of database user with the administration privileges.
>6<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
Property
Description
ECP.Deployment.Type
Choose one from following values :
> “jboss” - ECP node is deployed as EAR inside the JBoss AS.
> “tomcat” - ECP node is deployed as WAR inside the Tomcat
Endpoint.Code
Code of the Endpoint component of the upgraded node.
Gateway.Code
Code of the Gateway component of the upgraded node.
Node.Code
Code of the Node component of the upgraded node.
Node.PrimaryUrl
Upgraded node primary URL.
Node.SecondaryUrl
Upgraded node secondary URL. The secondary URL don’t have to be
filled if node has no geographical replication.
Node.Organization
Name of organization which node belongs to.
Node.Person
Contact person.
Node.Email
Email of contact person.
Node.Phone
Phone of contact person.
Node.Enviroment
Operation system where node is running. Use “LINUX”.
Endpoint.ActorRole
Actor role of the upgraded endpoint component.
Endpoint.ActorCode
Actor code of the upgrade endpoint component.
Keystore.Path
Patch to the keystore of ECP Node.
Keystore.Password
Password to the keystore of ECP Node.
Keystore.IntegratedCA.K
Password to the ECP integrated certificate authority private key. It
should be the same as keystore Keystore.Password.
ey.Password
Keystore.EncryptionCert
ificate.Password
Keystore.SigningCertifi
cate.Password
Keystore.Authentication
Certificate.Password
Module.Keystore.Encrypt
ion.KeyFile
Password to the encryption certificate private key. It should be the
same as keystore Keystore.Password.
Password to the signing certificate private key. It should be the same
as keystore Keystore.Password.
Password to the authentication certificate private key. Is should be the
same as keystore Keystore.Password.
Path to the resource which contains database encryption key. This key
is used to encrypt and decrypt all private keys stored into the database.
For more details please see [AdminGuide].
The value has to be in following format :
file:[absolute path to the encryption file]
If you want to use default encryption file then the value should be :
file:$UPGRADE_HOME/install/defaultEncryptionKey
>7<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
7. Stop running application server (JBoss or tomcat) with deployed ECP.
8. Check if application server is not running (using command ‘ps aux | grep java’).
9. Backup and delete the ECP log files placed in log directory according to your logger settings in
module.properties.
10. Change directory to $UPGRADE_HOME/install.
11. Execute script “upgrade_ecp_node.sh”.
Please check that script has ended with “BUILD SUCESSFUL”. In case that the script failed
(ended with “BUILD FAILED”) continue please with the “Upgrade recovery” chapter.
12. In case that you upgrading ECP installed on JBoss please don’t forget to clear following
directories in $JBOSS_HOME/server/$SERVER_PROFILE :
- tmp
- data
- work
1.3.3 ECP Configuration
After the successful installation the ECP configuration needs to be updated. Please note that installed
libraries with used receive and send handlers are upgraded automatically into the new version. Please
perform following steps:
1. Copy
the
node
template
configuration
from
the
($UPGRADE_HOME/install/config/sample/module_node.properties).
upgrade
package
2. Update the template configuration properties according you current configuration and
instructions in [AdminGuide].
3. Put the updated configuration into the ECP package as module.properties (please note that .ear
and .war files are just zip archives with different extension):
- JBoss – ECP_MODULE.ear/ECP_MODULE.war/WEB-INF/classes/module.properties
- Tomcat - ECP_MODULE.war/WEB-INF/classes/module.properties
1.3.4 Startup Upgraded ECP
1. Startup application server with deployed ECP.
2. Check whether the ECP upgrade was successful by displaying the ECP web page and by
sending the test message to your upgraded ECP node’s endpoint.
>8<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
2. UPDATE OF DATABASE TO USE CASE-SENSITIVE
SEARCH
2.1 Motivation
The main reason to change the case sensitivity for MySQL and MSSQL databases is to unify the
behavior of ECP across all the supported databases. Oracle and PostgreSQL use case sensitive search
by default while MySQL and MSSQL are case insensitive. This can lead to some minor issues during
message transportation when the message passes through databases with different case sensitivity.
Taking this into account, it is recommended to switch MySQL and MSSQL databases to the case
sensitive behavior. Following chapters describe briefly the procedure of changing case sensitivity on
these two databases.
2.2 Procedure overview
To make your existing ECP database use case sensitive searches, you have to follow steps described
in this chapter. Please, keep in mind that this procedure can be done only on ECP database version
1.5.*. If you are upgrading from ECP 1.5 to ECP 2.0 make sure to complete this procedure before
upgrading the ECP.
1.
Backup all the data from your ECP database. Use a tool which is distributed with your database
to dump the ECP data to a file.
2.
Re-create the ECP database using provided SQL scripts for clean installation.
3.
Load the data from the backup file to the newly created database.
4.
Verify that the upgrade was successful.
2.3 MySQL database
This chapter describes how to change the case sensitivity on MySQL database.
1. Use mysqldump tool to export data from the ECP database into a file. The resulting file can
grow very large (up to several gigabytes) depending on the size of your database. Make sure
that you have sufficient space on your hard drive.
Following is a sample command with explanation. Feel free to adjust the parameters according
to your system.

mysqldump --no-create-db --no-create-info -u root -peppsql ecp > ecp_dump.sql

“--no-create-db” and “--no-create-info” parameters mean that the database schema is not
part of the export (i.e. only data will be exported, not the database structure). This can’t be
omitted.
>9<
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1

“-u root” specifies the database root user.

“-peppsql” is a password for database user. -p is a parameter name and the eppsql is the
password.

“ecp” is the name of ECP database.

“ecp_dump.sql” is the path to the file where the data will be dumped.
2. Use the installation scripts to setup the case sensitive database. Look for install_15_CS.sql file
in $UPGRADE_PACKAGE_HOME/db-sql/sql/MySql/upgrade directory. Before running the
script, replace @DATABASE@ with the name of your ECP database (e.g. ecp) and @USER@
with ECP database user login (e.g. ecp).
3. Load the data back to the database. You can do this by executing following command:

mysql -u root -peppsql ecp < ecp_dump.sql

“-u root” specifies the database root user.

“-peppsql” is the password for the user. -p is a parameter name and the eppsql is the
password.

“ecp” is the name of ECP database.

“ecp_dump.sql” is path to the file create in the first step.
2.4 MSSQL database
This chapter describes shortly how to change the case sensitivity on MSSQL database.
1. Use the SQL Server Management Studio to export the data. It has a comprehensive export
wizard which leads you through the whole process of generating scripts. Please consult the
manual to the SQL Server Management Studio for more details. Remember to exclude the DDL
statements from the generated script.
2. Use the installation scripts to install the case sensitive database. Look for install_15_CS.sql file
in $UPGRADE_PACKAGE_HOME/db-sql/sql/MSSql/upgrade directory. Before running the
script, replace @DATABASE@ with the name of your ECP database (e.g. ecp) and @USER@
with ECP database user login (e.g. ecp).
3. Run the SQL script created in the first step on the newly created database. You may use the
SQL Server Management Studio for this step as well.
> 10 <
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
3.
UPGRADE RECOVERY
This chapter describes recovery after upgrade failure:
1. Restore database using the restore created in Backup of ECP.
2. Restore keystore using the keystore backup created in Backup of ECP.
3. Restore application using the backup created in Backup of ECP.
After this recovery the ECP is in the same state as before the upgrade. Please check the upgrade logs
located in the $UPGRADE_HOME\update\logs file, correct the upgrade configuration according to
stated errors and re-launch the upgrade again.
> 11 <
CWE
Energy Communication Platform
ECP Upgrade Guide - Node on Linux – from 1.5.6
to 2.1
4.
REFERENCES
[AdminGuide]
ECP Administrator’s Guide, Unicorn
> 12 <