Infrastructure at your Service

David Diab

Documentum – MigrationUtil – 5 – Change Installation Owner

The Documentum installation owner is the operating system user that owns the server executable and other related files along with the OS process when the server is running. It is originally determined when the server is installed, in fact, it is the logged-in user that performed the Documentum installation. Of course, it is preferable to install Documentum and never change the installation owner. However, sometimes company policy change and dictates that the original installation must be changed, for example, the user name does not conform to a new naming policy.

This blog is the last one of the MigrationUtil blogs serie (please find links of other blogs below), I will show how to change the Installation Owner using the MigrationUtil. If you want to change only the password please read this blog.

The installation owner user is important at the operating system and in the Docbase/Content Server level, it is given the following privileges:

  • Operating System:
    – Rights to start Documentum Services such as Docbase, Docbroker, Java Method Server and other installed Documentum products.
    – Permission to change the Content Server configuration (i.e. upgrade, create, and delete docbases).
    – Folder level permission to view data, configuration, and many log files located under the DOCUMENTUM_HOME directory.
  • Docbase and Content Server:
    – Superuser and System Administrator rights.
    – Set as the r_install_owner value in the dm_server_config object.
    – Set as the operating system user to run several Administrative jobs.

As you can deduce, the change of the installer owner is not a minor change within Documentum, so it is very critical. That’s why you have to prepare very well this operation and determine the best approach to execute it.

Below two change levels to be done:

  • OS Level change:
    – Create the new install owner at the operating system level, it should correspond to the user_os_name of the new docbase user.
  • Docbase level change:
    – Create a new user in the docbase to be the installation owner and reassign the previous installation owner’s objects to the new user. The MigrationUtil will be able to this part.

Preparation

Before any change

  • Clean the environment:
    Run the Consistency Checker job: The report gives you a list of bad data within your system. Cleaning up inconsistent data before making the change will speed up the process.
    Purge all old log files: Changing the installation owner requires updating permissions on Documentum data and log files. The purge will reduce work on “unneeded data” and will greatly speed up the process.
  • Back up:
    – Back up all the impacted environment before performing any major change within Documentum (Content Server files and the Database).

Create new user – OS Level

Add the new installation user at the OS Level, in the same group as the actual installation user :

[[email protected] ~]# useradd -g 1004 dmdocbase1
[[email protected] ~]# passwd dmdocbase1
Changing password for user dmdocbase1.
New password: 
Retype new password: 
passwd: all authentication tokens updated successfully.
[[email protected] ~]# 

To know the group of actual installation user:

[[email protected] ~]# cat /etc/passwd
...
dmadmin:x:1002:1004::/home/dmadmin:/bin/bash

Create new user – Docbase Level

You need to create the user in all docbases, using below dql query :

CREATE dm_user OBJECT
SET user_name = 'dmdocbase1',
SET user_password = 'install164',
SET user_login_name = 'dmdocbase1',
SET user_address = '[email protected]',
SET description = 'This User is the owner of docbase1',
SET user_os_name = 'dmdocbase1',
SET client_capability = 8,
SET user_privileges = 16,
SET user_xprivileges = 56,
SET user_source = 'inline password'

Result:

object_created  
----------------
1101e24080000500

Configure the MigrationUtil

Adapt the MigrationUtil configuration file like below:

[[email protected] ~]$ cat $DM_HOME/install/external_apps/MigrationUtil/config.xml 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>Database connection details</comment>
<entry key="dbms">oracle</entry> <!-- This would be either sqlserver, oracle, db2 or postgres -->
<entry key="tgt_database_server">vmtestdctm01</entry> <!-- Database Server host or IP -->
<entry key="port_number">1521</entry> <!-- Database port number -->
<entry key="InstallOwnerPassword">install164</entry>
<entry key="isRCS">no</entry>    <!-- set it to yes, when running the utility on secondary CS -->

<!-- <comment>List of docbases in the machine</comment> -->
<entry key="DocbaseName.1">docbase1</entry>

<!-- <comment>docbase owner password</comment> -->
<entry key="DocbasePassword.1">install164</entry>

...

<entry key="ChangeInstallOwner">yes</entry>
<entry key="InstallOwner">dmadmin</entry>
<entry key="NewInstallOwner">dmdocbase1</entry>
<entry key="NewInstallOwnerPassword">install164</entry>
...

Migration

Stop Docbase(s) and Docbroker(s)

Before you execute the migration you have to stop the docbase(s) and the docbroker(s).

$DOCUMENTUM/dba/dm_shutdown_Docbase1
$DOCUMENTUM/dba/dm_stop_DocBroker

Execute the migration script

Once every thing stopped, you can execute the migration script:

[[email protected] ~]$ $DM_HOME/install/external_apps/MigrationUtil/MigrationUtil.sh

Welcome... Migration Utility invoked.
 
Skipping Docbase ID Changes...

Skipping Host Name Change...

Changing Install Owner...
Created new log File: /app/dctm/product/16.4/product/16.4/install/external_apps/MigrationUtil/MigrationUtilLogs/InstallOwnerChange.log
Finished changing Install Owner...Please check log file for more details/errors
Finished changing Install Owner...

Skipping Server Name Change...

Skipping Docbase Name Change...

Skipping Docker Seamless Upgrade scenario...

Migration Utility completed.

Have a look on the Migration log:

[[email protected] ~]$ cat /app/dctm/product/16.4/product/16.4/install/external_apps/MigrationUtil/MigrationUtilLogs/InstallOwnerChange.log
Start: 2019-12-12 05:14:37.191
Changing Install Owner
=====================
InstallOwner: dmadmin
New InstallOwner: dmdocbase1
Changing InstallOwner for docbase: Docbase1
Retrieving server.ini path for docbase: Docbase1
Found path: /app/dctm/product/16.4/dba/config/Docbase1/server.ini

Database Details:
Database Vendor:oracle
Database Name:dctmdb.local
Databse User:Docbase1
Database URL:jdbc:oracle:thin:@vmtestdctm01:1521/dctmdb.local
Successfully connected to database....

Processing Database Changes for docbase: Docbase1
Created database backup File '/app/dctm/product/16.4/product/16.4/install/external_apps/MigrationUtil/MigrationUtilLogs/InstallOwnerChange_Docbase1_DatabaseRestore.sql'
Processing _s table...
select r_object_id,object_name from dm_sysobject_s where object_name = 'dmadmin'
update dm_sysobject_s set object_name = 'dmdocbase1' where r_object_id = '0c01e24080000105'
select r_object_id,r_install_owner from dm_server_config_s where r_install_owner = 'dmadmin'
update dm_server_config_s set r_install_owner = 'dmdocbase1' where r_object_id = '3d01e24080000102'
select r_object_id,user_name from dm_user_s where user_name = 'dmadmin'
update dm_user_s set user_name = 'dmdocbase1' where r_object_id = '1101e24080000102'
select r_object_id,user_os_name from dm_user_s where user_os_name = 'dmadmin'
update dm_user_s set user_os_name = 'dmdocbase1' where r_object_id = '1101e24080000102'
...
update dm_workflow_r set r_last_performer = 'dmdocbase1' where r_last_performer = 'dmadmin'
update dm_workflow_s set r_creator_name = 'dmdocbase1' where r_creator_name = 'dmadmin'
update dm_workflow_s set supervisor_name = 'dmdocbase1' where supervisor_name = 'dmadmin'
Successfully updated database values...
Committing all database operations...
Finished processing database changes for docbase: Docbase1

Processing server.ini changes for docbase: Docbase1
Backed up '/app/dctm/product/16.4/dba/config/Docbase1/server.ini' to '/app/dctm/product/16.4/dba/config/Docbase1/server.ini_install_dmadmin.backup'
Updated server.ini file:/app/dctm/product/16.4/dba/config/Docbase1/server.ini
Updating acs.properties for docbase: Docbase1
Backed up '/app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/acs.ear/lib/configs.jar/config/acs.properties' to '/app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/acs.ear/lib/configs.jar/config/acs.properties_install_dmadmin.backup'
Updated acs.properties: /app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/acs.ear/lib/configs.jar/config/acs.properties
Backed up '/app/dctm/product/16.4/dba/dm_shutdown_Docbase1' to '/app/dctm/product/16.4/dba/dm_shutdown_Docbase1_install_dmadmin.backup'
Updated shutdown script: /app/dctm/product/16.4/dba/dm_shutdown_Docbase1
...
Processing Services File Changes...
Backed up '/app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/ServerApps.ear/DmMethods.war/WEB-INF/web.xml' to '/app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/ServerApps.ear/DmMethods.war/WEB-INF/web.xml_install_dmadmin.backup'
Updated web.xml: /app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/ServerApps.ear/DmMethods.war/WEB-INF/web.xml
WARNING...File /app/dctm/product/16.4/wildfly9.0.1/server/DctmServer_MethodServer/deployments/bpm.ear/bpm.war/WEB-INF/web.xml doesn't exist
No need to update method server startup script: /app/dctm/product/16.4/wildfly9.0.1/server/startMethodServer.sh
Finished processing File changes...

Finished changing Install Owner...
End: 2019-12-12 05:14:39.815

Change permissions

Change the permissions of all folders and files under DOCUMENTUM_HOME directory, if your content storage directories are not located under the DOCUMENTUM_HOME directory, change the permissions on each content storage directory as well.

[[email protected] ~]$ chown -R dmdocbase1 /app/dctm

Start Docbase(s) and Docbroker(s)

Start the Docbroker and the docbase:

$DOCUMENTUM/dba/dba/dm_launch_DocBroker
$DOCUMENTUM/dba/dba/dm_start_Docbase1

Post Migration

Check the docbase logs:

...
2019-12-12T05:30:09.982774      13301[13301]    0000000000000000        [DM_MQ_I_DAEMON_START]info:  "Message queue daemon (pid : 13570, session 0101e24080000456) is started sucessfully."
2019-12-12T05:30:20.255917      13569[13569]    0101e24080000003        [DM_DOCBROKER_I_PROJECTING]info:  "Sending information to Docbroker located on host (vmtestdctm01) with port (1490).  Information: (Config(Docbase1), Proximity(1), Status(Open), Dormancy Status(Active))."
Wed Dec 12 05:30:32 2019 [INFORMATION] [AGENTEXEC 13628] Detected during program initialization: Version: 16.4.0000.0248  Linux64
Wed Dec 12 05:30:35 2019 [INFORMATION] [AGENTEXEC 13628] Detected during program initialization: Agent Exec connected to server Docbase1:  [DM_SESSION_I_SESSION_START]info:  "Session 0101e24080000500 started for user dmdocbase1."

Try to connect with old installation owner to Docbase1 throw idql:

...
Connecting to Server using docbase Docbase1
Could not connect
[DM_SESSION_E_AUTH_FAIL]error:  "Authentication failed for user dmadmin with docbase Docbase1."

This is the expected behavior, the old installation owner is no more active.

The environment I used to make this test is a very simple one ( with only one Docbase, no HA, no FullText, aso) and created only for this purpose. It worked fine on my environment, but be careful if you have a more complex environment!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

David Diab
David Diab

Consultant