h13028 wp d65sp2 migration d7x
DESCRIPTION
UpgradeTRANSCRIPT
-
White Paper
Abstract
This white paper explains the procedure to migrate Documentum Content Server 6.5 SP2 to Documentum Content Server 7.0 or 7.1. April 2014
D6.5 SP2 TO D7.1 MIGRATION
-
White Paper Title
Copyright 2014 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. VMware is a registered trademark of VMware, Inc. All other trademarks used herein are the property of their respective owners. Part Number h13028
2
-
White Paper Title
Table of Contents
Executive summary.................................................................................................. 4 Audience ............................................................................................................................ 4
Migration Overview.................................................................................................. 5
Prerequisites ........................................................................................................... 8
Migration of Data ..................................................................................................... 9 Database Migration .......................................................................................................... 10
Microsoft SQL Database ............................................................................................... 10 Oracle Database ........................................................................................................... 16 Update Database ......................................................................................................... 18
Transfer of File Store Data ................................................................................................. 20
Installation of Content Server 7.x ........................................................................... 21
Upgrade Repository ............................................................................................... 26
Configuration & Verification ................................................................................... 27
Multiple aek.key / Migrating 6.5 SP2 Repository to an Existing 7.x CS ..................... 30
Content Server in High Availability ......................................................................... 31
Trouble Shooting ................................................................................................... 32
Conclusion ............................................................................................................ 34
References ............................................................................................................ 34
3
-
White Paper Title
Executive summary This whitepaper describes the steps to upgrade an existing EMC Documentum 6.5 SP2 to Documentum 7.0 or 7.1.
The 6.5 SP2 Documentum environment is prepared for migration.
Read the EMC Documentum Environment and System Requirements Guide for details system hardware and software requirements, including supported operating system and database combinations for D7.0 or 7.1 Content Server.
The steps involve installation of new D7.x Content Server binaries and Migrating Database and Data to target [7.x] Content Server environment, where the OS / DB / Hardware combinations which support Documentum 7.x
Specific scenarios for also covered in the whitepaper:
Migrating 6.5 SP2 Repository to existing Documentum 7.0 or 7.1 environment
Migrating Content Server in High Availability
Audience This whitepaper is for intended Documentum Customers, who are upgrading the Documentum system.
4
-
White Paper Title
Migration Overview The high level steps involved in the migration are as below:
Prepare the Source [6.5 SP2] Content Server for migration. Stop the Content Server and the Data Base
Figure 1 Prepare 6.5 SP2 environment for migration
Obtain the required environment for the Target [7.x] Content Server [eg: RDBMS, OS, Hardware]. Migrate the Database from source to target RDBMS machine. Update the table contents with target [7.x] Content Server details. Migrate the data from source to target Filestore machine.
[Note: target filestore should be supported by CS as primary filestore.]
5
-
White Paper Title
Figure 2 Migrate DB & Data to 7.x environment
Install the 7.x Content Server binaries. Create a Repository pointing to the migrated DB on target RDBMS machine. Upgrade the Repository Configure and Verify the 7.x Content Server
6
-
White Paper Title
Figure 3 Create Repository & Upgrade on 7.x CS
7
-
White Paper Title
Prerequisites Obtain the below values from 6.5 SP2 Content Server Environment.
1. Repository Name
2. Repository ID
3. Repository Owners name and password
4. Installation Owner
5. Files Store data path
6. Database Administrator account username and password
While installing and configuring the 7.0 or 7.1 Content Server the same values will be provided.
If you cannot provide the Database Administrator account at this stage, you can perform these actions after the repository configuration is complete:
Create the Data Management System (DMS) user in the database instance.
Grant the DMS user permissions to access the DMS schema tables.
The installation owner must have Full Control permission on the directories into which Content
Server is being installed, including data and share directories.
After all the operations are complete on 6.5 SP2 Content Server, stop the content server.
Take a backup of the data filestore, if the same filestore is used for 7.x environment.
Note: After migrating 6.5 SP2 CS to 7.x the higher encryption feature of CS 7.x is not supported. Content Server will continue to use the same encryption used in CS 6.5 SP2.
8
-
White Paper Title
Migration of Data Migration of Data has 2 phases: 1. Database migration from source [6.5 SP2]RDBMS Machine to target [7.x] RDBMS Machine 2. Transfer of the File Store Data Back up of the Database copies the data or log records from a SQL Server database or its transaction log to a backup device, such as a disk, to create a data backup or log backup. Restore of the Database is a multi-phase process that copies all the data and log pages from a specified SQL Server backup to a specified database, and then rolls forward all the transactions that are logged in the backup by applying logged changes to bring the data forward in time. Database backup and restore in Microsoft SQL Server can be done using Microsoft SQL Server Management Studio. Refer the Oracle / Microsoft support documentation for RDBMS upgrade path.
9
-
White Paper Title
Database Migration
Microsoft SQL Database
On Source [6.5SP2] Microsoft SQL Server Machine 1. Stop the Source [6.5 SP2] Content Server 2. Take back up of database [e.g.: DM_Repo1_docbase] with SQL Administrator (sa).
10
-
White Paper Title
11
-
White Paper Title
On Target [7.x] Microsoft SQL Server Machine 1. Copy the backup file to a location accessible by SQL Administrator. 2. Recover the database on target Microsoft SQL server with SQL Administrator. Give the same Database name.[
e.g.: DM_Repo1_docbase]
12
-
White Paper Title
13
-
White Paper Title
3. Manually create the repository owner account in the target [7.x] database prior to installing Content Server. The repository owner account should have appropriate privileges to perform the following tasks: connect to the database Create tables, views, and indexes in the database Insert records (rows) into the tables Drop tables, views, and indexes Run the below SQL script to create the Repository owner account and assign privileges as database owner.
USE master GO PRINT 'ALTER DATABASE database_name SET READ_COMMITTED_SNAPSHOT ON' GO ALTER DATABASE database_name SET READ_COMMITTED_SNAPSHOT ON GO PRINT 'Processing user repository_user...' GO IF NOT EXISTS (SELECT name FROM master.dbo.syslogins WHERE name = 'repository_user') BEGIN EXEC sp_addlogin 'repository_user','password' END GO PRINT 'sp_defaultdb ''repository_user'', database_name ' GO sp_defaultdb ' repository_user ', database_name GO PRINT 'USE database_name ' GO USE database_name GO PRINT 'sp_changedbowner '' repository_user ''' GO sp_changedbowner ' repository_user ' GO PRINT 'USE master ' GO USE master GO PRINT 'sp_grantdbaccess '' repository_user ''' GO
14
-
White Paper Title
sp_grantdbaccess ' repository_user ' GO PRINT 'Complete.' GO
Note: The dm_CreateTableSpace.sql under $\Documentum\dba\config\repository_name on the 6.5 Content Server machine - can be copied and modified for the above SQL Script.
15
-
White Paper Title
Oracle Database For database migration the high level steps are:
1. Clone Oracle Home
2. Copy Database
3. Upgrade Database
Clone Oracle Home 1. Stop the source [6.5 SP2] Content Server
2. Stop all processed related to Oracle Home on source [6.5 SP2] RDBMS machine
3. Create a Zip file with the Oracle Home directory
E.g.: zip r db_1.zip /u01/app/oracle/product/11.1.0/db_1
4. Copy the zip file to a directory of the target [7.x] RDBMS machine
5. Extract the zip file contents as Oracle User
E.g.: unzip d / db_1.zip
6. On the target [7.x] RDBMS machine [with Oracle 11.2.3 binaries installed]
a. Change Oracle Home to unzipped Oracle home directory.
b. Remove all the the .ora (*.ora) files present in the unzipped $ORACLE_HOME/network/admin directory.
7. From the $ORACLE_HOME/oui/bin directory, as Oracle user - run Oracle Universal Installer in clone mode for the unzipped Oracle home
E.g.: o $ORACLE_HOME/oui/bin/runInstaller -silent -clone ORACLE_HOME="/u01/app/oracle/product/11.1.0/db_1" ORACLE_HOME_NAME="db_1" ORACLE_BASE="/u01/app/oracle"
8. Run root.sh from root user
Copy Database 1. On the target [7.x] RDBMS machine: create new folders under oradata DB. Create folder
flash_recovery_area and folder for the DB [as in 11.1.0 recovery area is referred to flash_recovery_area]
2. On the source [6.5SP2] RDBMS machine :
a. Create a pfile from spfile
Eg: create pfile=pfilecopy.ora from spfile;
b. Shutdown the DB [shutdown immediate;]
c. Copy all files under Oradata to target [7.x] RDBMS machine
3. On the target [7.x] RDBMS machine:
a. Change the ORACLE HOME to 11.1.0
b. In sqlplus, create spfile from pfile=\pfilecopy.ora
c. Startup database
16
-
White Paper Title
Upgrade Database 1. From SQLPlus run @utlu112i.sql with spool on
2. Check the spool file and examine the output of the Upgrade Information Tool
3. Ensure that there are NO INVALID database components/objects in the source database prior to starting the upgrade.
a. @utlrp.sql
b. set pagesize500
c. set linesize 100
d. select substr(comp_name,1,40) comp_name, status, substr(version,1,10) version from dba_registry order by comp_name;
e. select substr(object_name,1,40) object_name,substr(owner,1,15) owner,object_type from dba_objects where status='INVALID' order by owner,object_type;
f. select owner,object_type,count(*) from dba_objects where status='INVALID' group by owner,object_type order by owner,object_type ;
4. PURGE DBA_RECYCLEBIN;
5. EXECUTE dbms_stats.gather_dictionary_stats;
6. Truncate table sys.aud$;
7. Truncate table sys.fga_log$;
8. Restart the database
9. Stop the Listener
10. Upgrade the database using the Database Upgrade Assistant
11. Under the Oracle 11.2.3/bin [eg: /u01/app/oracle/product/11.2.3/db_1/bin] run dbua
12. Start the listener
17
-
White Paper Title
Update Database 1. Use the SQL server and correct the values in the database tables :
a. r_host_name and web_server_loc in dm_server_config_s
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_server_config_s] SET [r_host_name] = 'r_host_name_7.x'
WHERE r_host_name='r_host_name_6.5' GO UPDATE [DM_RepositoryName_docbase].[dbo].[dm_server_config_s]
SET [web_server_loc] = 'web_server_loc_7.x' WHERE web_server_loc='web_server_loc_6.5' GO
Note: r_host_name,web_server_loc,host_name and projection_targets contains the Content Server hostname as value.
b. host_name in dm_mount_point_s
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_mount_point_s] SET [host_name] = 'host_name_7.x' WHERE host_name='host_name_6.5'
GO c. target_server in dm_job_s
Target_server contains the target Content server as value. It is in the syntax RepositoryName.ContentServerName@ContentServerHostName.
Eg: Repo1.Repo1@CS1
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_job_s] SET [target_server] = 'target_server_7.x' WHERE target_server='target_server_6.5' GO
d. projection_targets in dm_server_config_r
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_server_config_r] SET [projection_targets] = 'projection_targets_7.x' WHERE projection_targets='projection_target_6.5' GO
18
-
White Paper Title
e. acs_base_url in dm_acs_config_r
acs_base_url is in the form : http://CSMachine:9080/ACS/servlet/ACS (where 9080 is the default port on which ACS is running.)
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_acs_config_r] SET [acs_base_url] = 'acs_url_7.x' WHERE acs_base_url='acs_url_6.5' GO
f. file_system_path in dm_location_s
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_location_s] SET [file_system_path] = file_system_path_7.x WHERE file_system_path = file_system_path_6.5
2. Set the server to rebuild the Documentum views with this SQL Server statement:
UPDATE [DM_RepositoryName_docbase].[dbo].[dm_type_s] SET [views_valid] = 0 GO
19
-
White Paper Title
Transfer of File Store Data 1. Copy the Data folder from the source to destination.
2. If the data folder path is not same, update file_system_path in dm_location_s
3. If the data Filestore is same, then take a backup of the data Filestore for Roll back
Note: The same steps are followed for encrypted file store as well.
20
-
White Paper Title
Installation of Content Server 7.x 1. Database client on the Content server machine is as per recommendation in EMC Documentum Content Server Version 7.x Installation Guide 2. Install the Content Server. 3. Copy the $DOCUMENTUM/dba/secure/aek.key file from the 6.5 SP2 to the same location on the 7.x repository host 4. Run the Server configuration program. Create a new repository
a. Select Add a new Repository
21
-
White Paper Title
b. Same Data folder path as 6.5 SP2 Repository.
22
-
White Paper Title
c. Same Repository name and ID as 6.5 SP2.
23
-
White Paper Title
d. Database select use existing user and database.
24
-
White Paper Title
e. Provide the database user password. [Same as 6.5 SP2 database user password]. Query databases to verify connection. Proceed and complete the Repository creation.
5. Server startup fails in the end of creation. This is expected as the crypto_mode in 6.5 SP2 and 7.x are
different. 6. Modify the crypto_mode and crypto_keystore fields in server.ini. Start the server. Verify the server log for
successful startup. a. crypto_keystore=Local b. crypto_mode=3DES_RSA1024_SHA256
25
-
White Paper Title
Upgrade Repository After the Migration of Repository from 6.5 to 7.x, Upgrade the Repository.
1. Run the Server Configuration Program. Select Repository. Select the Repository and run upgrade.
2. Restart the Content server machine.
26
-
White Paper Title
Configuration & Verification 1. The Content server projections: Dump the serverconfig object from Iapi and verify the Projection targets. If the
projections are incorrect, using Iapi correct the values. Iapi command: dump,c,serverconfig
2. Through Documentum Administrator, under Client Rights Management Privileged Clients, verify the DFCs
related to target [7.x] Content servers have client rights.
27
-
White Paper Title
3. Run DocBroker Query Tool to verify the Docbroker Information and Server Map dmqdocbroker -t contentserverIP -p docbrokerPort -a -c getservermap repositoryName. It should return the Docbroker Information and Server Map.
Example:
dmqdocbroker -t 10.10.10.10 -p 1489 -a -c getservermap Repo1
dmqdocbroker: A DocBroker Query Tool dmqdocbroker: Documentum Client Library Version: 7.X.XXX.XXXX Using specified port: 1489 ************************************************** ** D O C B R O K E R I N F O ** ************************************************** Docbroker host : CS27upgrade Docbroker port : 1490 Docbroker network address : INET_ADDR: 02 5d2 0a1f4506 CS27upgrade 10.10.10.10 Docbroker version : 7.X.XXX.XXXX Win64 ************************************************** ** S E R V E R M A P ** ************************************************** Docbase NewPreUpgradeREPO has 1 servers: -------------------------------------------- server name : CS27UPGRADEACS1 server host : CS27upgrade server status : Open client proximity : 1 server version : 7.X.XXX.XXXX server process id : 11 last ckpt time : 9/25/2013 4:13:38 AM next ckpt time : 9/25/2013 4:18:38 AM connect protocol : TCP_RPC connection addr : 0 keep entry interval : 30 docbase id : 98765 server dormancy status : ACTIVE --------------------------------------------
4. Verify the Distributed Content Configurations and Distributed Transfer settings through Documentum
Administrator. 5. Delete the old Acs Configuration object using Iapi command destroy,c,acs_config_id
Note: In case asynchronous write is turned on in an environment, the DFC deployed in the application context sends a message to DMS instructing it to store the content parked in BOCS. The size of the message is directly proportional to the number of ACS server configuration objects as well as to the number of base URLs in the ACS config objects. If the number of configuration objects or URLs exceeds 2, there can be a database truncation of the message while storing it in DMS's database. This is not advisable. So such configuration of ACS configuration object(s) should be avoided.
6. Verify the dm_jms_config object :- base_uri and projection_target is pointing to correct jms instance.
28
-
White Paper Title
7. To log in to Documentum 7.x Content Server repository using Documentum 6.7 SP2 clients, follow these steps:
Note: These steps help resolve compatibility issues between 6.7 SP2 clients and Content Server 7.x.
a. Decrypt the Global Registry Password mentioned in dfc.properties of Content Server 7.x using the following command in the Documentum Foundation Classes 7.x environment:
java com.documentum.fc.tools.RegistryPasswordUpgradeTool -decrypt_password This command generates a plain text password.
b. Encrypt the plain text password in a Documentum 6.7SP2 environment using the following command: java -cp "%DOCUMENTUM_SHARED%\dfc.jar" com.documentum.fc.tools.RegistryPasswordUtils
c. Replace the Global Registry Password in the dfc.properties for 6.7 SP2 clients as:
dfc.globalregistry.password=
29
-
White Paper Title
Multiple aek.key / Migrating 6.5 SP2 Repository to an Existing 7.x CS 1. Migrate the database from source to target RDBMS machine 2. Transfer the Filestore data 3. Rename the already existing aek.key file [eg: aek_repo1.key] 4. Copy the aek.key from source [6.5 SP2] Content Server machine 5. Follow the same steps for installation of CS from Step 3 to 5 6. Upgrade the repository 7. Now to shutdown both the repositories [i.e. already existing and newly migrated repository] 8. Rename the aek.key file copied from source CS [6.5 SP2] [eg: aek_repo2.key] 9. Startup both the repositories using the below script
a. set dm_crypto_file=$Documentum\dba\secure\aek_repo1.key b. start $\Documentum\product\7.x\bin\documentum.exe -docbase_name Repo1_name -security acl -
init_file $\Documentum\dba\config\Repo1_name\server.ini -install_owner Administrator -logfile $\Documentum\dba\log\Repo1_name.log
c. set dm_crypto_file=$\Documentum\dba\secure\aek_repo2.key d. start $\Documentum\product\7.x\bin\documentum.exe -docbase_name Repo2_name -security acl -
init_file $\Documentum\dba\config\Repo2_name\server.ini -install_owner Administrator -logfile $\Documentum\dba\log\Repo2_name.log
10. Proceed with Configuration and Verification of upgrade
30
-
White Paper Title
Content Server in High Availability 1. Migrate and upgrade the Primary Content Server.
2. Update the database replacing 6.5 second Content server details with 7.x Content Server details [follow Update Database steps]
3. Update the projections targets appropriately
4. As the Second Content Server would share the same database, proceed with installing and configuring second content server.
5. Install Content Server on second machine.
6. Run the CFSConfiguration utility on second machine
7. Follow the EMC Documentum Content Server Version 7.x Installation Guide for Configuring Content Server in HA
8. Follow the configuration and verification steps.
31
-
White Paper Title
Trouble Shooting 1. During repository creation, if you face issue with connection with Database, reconfigure the ODBC
connection.
2. During upgrade the head start scripts fails. Errors related to dropping certain tables or creating new views reported in logs. This is faced when Database is not migrated completely with all the data and log pages. Migrating database with back and restore is recommended as stored views and indexes will be intact.
3. During upgrade of Repository, if you face the below error:
[DM_CRYPTO_E_PASSWORD_DECRYPTION_FAILED] error: "Decryption of password present in file $\Documentum\dba\config\repositoryName\ldap_xxxxxxx.cnt failed, status - 2" Resolution:
Copy the ldap_xxxxxxx.cnt file from 6.5 SP2 machine $\Documentum\dba\config\repositoryName to 7.x Content server machine.
4. After performing an upgrade, you may see the following error in the docbase log upon docbase startup: "[DM_SESSION_E_INIT_FAILURE1] error: "Failure to complete Distributed Content Digital Signatures initialization.""
This is likely seen in an environment that has been cloned or copied from another environment.
The ACS crypto key is referencing the cloned system.
Resolution:
The remove the public/private ACS keys from Database. Make sure you have a backup before you make any direct modifications against the database in SQLPlus.
STEPS:
a. Stop the repository. Run the below SQL commands.
b. delete dm_sysobject_s where r_object_id = (Select r_object_id from dm_public_key_certificate_s where key_type = 1);
c. delete dm_sysobject_r where r_object_id = (Select r_object_id from dm_public_key_certificate_s where key_type = 1);
d. delete dm_public_key_certificate_s where key_type = 1; e. delete dm_sysobject_s where r_object_id = (Select r_object_id
from dm_cryptographic_key_s where key_type = 1); f. delete dm_sysobject_r where r_object_id = (Select r_object_id
from dm_cryptographic_key_s where key_type = 1); g. delete dm_cryptographic_key_s where key_type = 1; h. Restart your repository. The error should no longer appear in the docbase log and the
docbase should start up normally now.
32
-
White Paper Title
5. If the docbase logs has a warning message as below:- DFC_API_W_ATTEMPT_TO_USE_DEPRECATED_CRYPTO_API] WARNING: Program attempts to use deprecated non-FIPS compliant cryptography API
Resolution:
Generate the Global Registry user password manually using the SH1 encryption algorithm
a. On the DFC host, navigate to $DOCUMENTUM/config (Linux) or %DOCUMENTUM%\config (Windows).
b. From a command prompt, execute the following command to generate the encrypted form of the global registry users password:
java -cp dfc.jar com.documentum.fc.tools.RegistryPasswordUtils password_of_user
where password_of_user is the clear-text password of the global registry user
c. Open the dfc.properties file in a text editor and modify the following attributes:
dfc.globalregistry.repository=global_registry_repository_name
dfc.globalregistry.username=user_login_name
dfc.globalregistry.password=encryped_password_of_user
where encryped_password_of_user is the encrypted password you generated in step 2
d. Save the dfc.properties file.
6. Roll Back:
a. Start the docbroker and repository
b. Bring the database online
c. Restore the data Filestore with backup (in case same filestore was used)
7. Update the dm_sysprocess_config_r object
select * from dm_sysprocess_config_r; update dm_sysprocess_config_r set base_uri = '' where base_uri = '' and servlet_name = 'do_method' commit; update dm_sysprocess_config_r set base_uri = '' where base_uri ='' and servlet_name = 'do_mail' commit;
33
-
White Paper Title
Conclusion The Documentum 6.5SP2 is migrated and upgraded to the New Documentum 7.0 or 7.1 environment.
References EMC Documentum System Version 7.0 Upgrade and Migration Guide
EMC Documentum Content Server Version 7.0 Installation Guide
EMC Documentum Content Server Version 7.1 Installation Guide
EMC Documentum Environment and System Requirements Guide
http://technet.microsoft.com/en-us/library/586561fc-dfbb-4842-84f8-204a9100a534
34
Executive summaryAudience
Migration OverviewPrerequisitesMigration of DataDatabase MigrationMicrosoft SQL DatabaseOn Source [6.5SP2] Microsoft SQL Server MachineOn Target [7.x] Microsoft SQL Server Machine
Oracle DatabaseClone Oracle HomeCopy DatabaseUpgrade Database
Update Database
Transfer of File Store Data
Installation of Content Server 7.xUpgrade RepositoryConfiguration & VerificationMultiple aek.key / Migrating 6.5 SP2 Repository to an Existing 7.x CSContent Server in High AvailabilityTrouble ShootingConclusionReferences