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 Owner’s 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 <ENCRYPT_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 <Password>

c. Replace the Global Registry Password in the dfc.properties for 6.7 SP2 clients as:

dfc.globalregistry.password=<NEW_ENCRYPT_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 user’s 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 = '<old_hostname and URL>' where base_uri = '<new_hostname and URL>' and servlet_name = 'do_method'

commit;

update dm_sysprocess_config_r set base_uri = '<old_hostname and URL>' where base_uri ='<new_hostname and URL>' 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