Documentum – Automatic/Silent registration & approval of DFC Clients

In the past several months, I have been working extensively with several other colleagues on a migration of Documentum from VMs to K8s pods. We have been doing/using silent installations for several years already but there were still several manual tasks for the customization of the repository, deployment of some applications, aso… In this blog, I will talk about what can be done to automate the registration and approval of DFC Clients s o it can be done without any manual intervention.

DFC Clients registration & approval is useful in several areas. Some example of where you would need it:

• If you want to use D2 4.7 or above for example, then you will need to register and approve the D2 DFC Client IDs
• If you want to use High Availability on the Content Server, then you will also need to register and approve the DFC Client IDs of the CS&JMS dfc.keystore files. In addition to that, for the HA part, you will also need to add the two options ‘Enables trusted login‘ and ‘Enables trusted server privilege‘
• You could also want to have the trusted options for a custom application so that your code doesn’t require authentication and it could just run on the target repository: obviously you would need to be careful with such things but it is nonetheless possible

To configure a DFC Client, you can simply use Documentum Administrator (Administration > Client Rights Management > Privileged Clients). However, this is always a pain in the *** when you install a new application to retrieve the Client ID from the dfc.keystore, then login to DA, approve the ID, add the options that are needed, doing it for all repositories needed, aso…

So, how is a DFC Client ID managed inside the repository? Well, when a new dfc.keystore is created, it should register itself, on the first use, with the Global Registry repository defined in the associated dfc.properties file. What this does is that it adds a new row/entry inside the ‘dm_client_registration‘ table of the GR repository only. In DA, when you open the “Manage Clients” page (File > Manage Clients) and add a DFC Client ID to the list of Privileged Clients (right side), it will create a new row/entry in the ‘dm_client_rights‘ table as well as in the ‘dm_public_key_certificate‘ table (if it’s not already present). You can do that for the GR repository obviously but you can also do it for a normal repository. In both cases, the list of DFC Clients that you see on the “Manage Clients” page of DA is actually the list of the entries from the ‘dm_client_registration‘ of the GR repository.

Permissions related to a specific DFC Client ID are then managed directly in the ‘dm_client_rights’:

• Approving a DFC Client ID will set the ‘allow_all_priv_modules‘ to true
• Adding the ‘Enables trusted login‘ will set the ‘principal_auth_priv‘ to true
• Adding the ‘Enables trusted server privilege‘ will set the ‘server_trust_priv‘ to true

So, it seems to be simple to automate, right? Well, not really… The thing is that when you are trying to automate things, you need to be sure that the behavior is consistent. There is also the issue that what DA is doing on the “Manage Clients” page (add entry to the Privileged Clients list and therefore creation of rows/entries in the ‘dm_client_rights‘ + ‘dm_public_key_certificate‘) isn’t public. We tried to ask OpenText about what is DA actually doing in the background but the feedback we got is that they cannot tell us.

So, there is no way then? Is this blog useless? Well, of course not but there are some restrictions. The D2 Team actually developed a utility that is available starting with D2 16.4 and that can be used to do exactly that. The problem here is that this utility is linked to D2. It actually doesn’t use any D2 specific classes but only Documentum OOTB ones. However, since it was developed by the D2 Team, it means that you need to have a D2 license to be able to use it. I asked already in a SR (#4299215) for OpenText to consider migrating this utility on the CS side because this is needed as well for High Availability and other purposes. There is no reasons for this to be a D2 only tool, let’s see what they will decide in the future.

The D2 utility can only be used to register the DFC Client ID and add it to the list of the Privileged Clients but it can do it properly for both GR and normal repositories so that’s all we needed. This is how it works:

[weblogic@weblogic-server-0 ~]$ cd $APPLICATIONS
[weblogic@weblogic-server-0 applications]$ 
[weblogic@weblogic-server-0 applications]$ ls -l | grep D2
drwxr-x---.  9 weblogic weblogic      8192 Sep  3 16:05 D2-Config
drwxr-x---. 15 weblogic weblogic      8192 Sep  3 16:10 D2
[weblogic@weblogic-server-0 applications]$ 
[weblogic@weblogic-server-0 applications]$ cd D2/utils/d2privilegedclient/
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ ls -l
total 40
-rw-r-----. 1 weblogic weblogic 18470 May 20 17:23 D2PrivilegedClientUtil-16.5.1.jar
-rw-r-----. 1 weblogic weblogic  1214 May 20 17:23 D2PrivilegedClientUtil.cmd
-rw-r-----. 1 weblogic weblogic  1141 May 20 17:23 D2PrivilegedClientUtil.sh
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ grep "webinfdir" D2PrivilegedClientUtil.sh
webinfdir=../../WEB-INF
    classpath="${utiljar}:${webinfdir}/classes/:${webinfdir}/lib/*"
    classpath="${utiljar};${webinfdir}/classes/;${webinfdir}/lib/*"
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ cat ../../WEB-INF/classes/dfc.properties
#include $APP_DATA/D2/dfc.properties
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ grep -E "keystore|repo" $APP_DATA/D2/dfc.properties
dfc.globalregistry.repository=gr_repo
dfc.security.keystore.file=$APP_DATA/D2/dfc.keystore
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ strings $APP_DATA/D2/dfc.keystore | grep dfc_ | gawk '{print substr($1, 1, length($1) - 1); exit}'
dfc_Lp76piwfz4tpAupiCktfKFfndOAa
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ gr="gr_repo"
[weblogic@weblogic-server-0 d2privilegedclient]$ repo="REPO1"
[weblogic@weblogic-server-0 d2privilegedclient]$ user="dmadmin"
[weblogic@weblogic-server-0 d2privilegedclient]$ pw="P4ssw0rd"
[weblogic@weblogic-server-0 d2privilegedclient]$ 
[weblogic@weblogic-server-0 d2privilegedclient]$ chmod 700 D2PrivilegedClientUtil.sh
[weblogic@weblogic-server-0 d2privilegedclient]$ ./D2PrivilegedClientUtil.sh -d ${gr} -u ${user} -p ${pw} | grep -v "|-"
Running D2PrivilegedClientUtil

2019-09-07 11:17:27,359 UTC [INFO ] (main) - c.e.x.r.c.d.dao.impl.PrivilegeClientDaoImpl   : Checking dm_client_rights for dfc: dfc_Lp76piwfz4tpAupiCktfKFfndOAa
D2_WS1_weblogic-server-0_fndOAa
[weblogic@weblogic-server-0 d2privilegedclient]$
[weblogic@weblogic-server-0 d2privilegedclient]$ ./D2PrivilegedClientUtil.sh -d ${repo} -u ${user} -p ${pw} | grep -v "|-"
Running D2PrivilegedClientUtil

2019-09-07 11:18:05,735 UTC [INFO ] (main) - c.emc.xcp.rest.core.dfc.utils.IpAndRcHelper   : filling in {0} a new record with this persistent certificate:
{1}
2019-09-07 11:18:06,082 UTC [INFO ] (main) - c.e.x.r.c.d.dao.impl.PrivilegeClientDaoImpl   : Checking dm_client_rights for dfc: dfc_Lp76piwfz4tpAupiCktfKFfndOAa
D2_WS1_weblogic-server-0_fndOAa
[weblogic@weblogic-server-0 d2privilegedclient]$

As you can see above, the shell script is setting up the classpath so that it fetches the internal dfc.properties of D2. In my case, this dfc.properties loads an external one. The D2 utility will use the dfc.properties file to fetch information regarding the location of the dfc.keystore as well as information regarding the GR repository.

There are several things wrong with the D2 utility. If you are trying to execute it as shown above without fixing these issues first, then it won’t be working properly. To fix the D2 utility, you can take a look at this blog.

Once the D2 utility has been executed for both the Global Registry repository and all normal repositories that will use D2, then you are done. You don’t need to do anything else for D2.

For the HA configuration of a CS for example, then in addition, you will also need to add the two options ‘Enables trusted login‘ and ‘Enables trusted server privilege‘, as said previously. To do that, I already gave all the needed information since I mentioned the link between what can be done in DA and the effect it has on the repository. Using a CS dfc.keystore for this example:

[dmadmin@content-server-0 ~]$ gr="gr_repo"
[dmadmin@content-server-0 ~]$ repo="REPO1"
[dmadmin@content-server-0 ~]$ 
[dmadmin@content-server-0 ~]$ client_id=`strings $DOCUMENTUM_SHARED/config/dfc.keystore | grep dfc_ | gawk '{print substr($1, 1, length($1) - 1); exit}'`
[dmadmin@content-server-0 ~]$ 
[dmadmin@content-server-0 ~]$ iapi ${gr} -U${USER} -Pxxx <<EOF
> retrieve,c,dm_client_rights where client_id='${client_id}'
> set,c,l,allow_all_roles
> T
> set,c,l,allow_all_priv_modules
> T
> set,c,l,principal_auth_priv
> T
> set,c,l,server_trust_priv
> T
> save,c,l
> EOF


        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2018. OpenText Corporation
        All rights reserved.
        Client Library Release 16.4.0110.0058

Connecting to Server using docbase gr_repo
[DM_SESSION_I_SESSION_START]info:  "Session 010f12345001014e started for user dmadmin."

Connected to OpenText Documentum Server running Release 16.4.0110.0167  Linux64.Oracle
Session id is s0
API> ...
080f1234500005a1
API> SET> ...
OK
API> SET> ...
OK
API> SET> ...
OK
API> SET> ...
OK
API> ...
OK
API> Bye
[dmadmin@content-server-0 ~]$ 
[dmadmin@content-server-0 ~]$ 
[dmadmin@content-server-0 ~]$ iapi ${repo} -U${USER} -Pxxx <<EOF
> retrieve,c,dm_client_rights where client_id='${client_id}'
> set,c,l,allow_all_roles
> T
> set,c,l,allow_all_priv_modules
> T
> set,c,l,principal_auth_priv
> T
> set,c,l,server_trust_priv
> T
> save,c,l
> EOF


        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2018. OpenText Corporation
        All rights reserved.
        Client Library Release 16.4.0110.0058

Connecting to Server using docbase REPO1
[DM_SESSION_I_SESSION_START]info:  "Session 010f2345600069bf started for user dmadmin."

Connected to OpenText Documentum Server running Release 16.4.0110.0167  Linux64.Oracle
Session id is s0
API> ...
080f2345600005be
API> SET> ...
OK
API> SET> ...
OK
API> SET> ...
OK
API> SET> ...
OK
API> ...
OK
API> Bye
[dmadmin@content-server-0 ~]$

With that, you will be able to automate the registration, approval and permissions of all your DFC Client IDs, assuming you have a valid D2 license. Hopefully OpenText will reconsider and make it a OOTB utility.