Planning on In-Place Upgrading a CA Directory Linux Implementation
search cancel

Planning on In-Place Upgrading a CA Directory Linux Implementation

book

Article ID: 390024

calendar_today

Updated On:

Products

CA Directory

Issue/Introduction

Every now and then some of us may be facing a production CA Directory implementation that was done by someone else while no proper documentation of the original implementation was available to help us planning on in-place upgrading such an implementation.

This KB is meant to provide a systematic approach when facing such a project.

Environment

Release: 14.1

Component: CA Directory

Operating System: Linux

Resolution

This KB focuses on a Linux based CA Directory 14.1 implementation. 

Explore What is on a CA Directory Server

To explore the current CA Directory implementation when the documentation of the original implementation is not perfect, we start from the applications the CA Directory implementation is supporting. CA Directory is commonly used to provide an LDAP Service to a software application that uses an LDAP directory. From the applications, we should be able to identify the machine name and/or IP address and LDAP port number (namely LDAP Endpoint) the application is using to connect to the CA Directory implementation.

Using the LDAP Endpoint, we should be able to locate the machine (namely CA Directory Server) that is hosting the LDAP Service and then try to gain access to it.

From the product documentation:

About Directory Components and Packages

we learn that there are three main components of a CA Directory, namely:

  • DXserver,
  • DxAgent, and
  • Management UI

For a Linux machine, once we are able to gain access to the machine, the first thing is to identify the Linux account name the CA Directory components are running under even though the default account name is dsa. We will refer this account name as DSAUSER throughout this KB. The DSAUSER can be identified by the following command and its sample output once you are able to login to the Linux machine:

ps -ef | grep dxserver
dsa         1827       1  0 08:59 ?        00:00:00 dxserver start democorp

Please note that the "DXserver Administrator" needs to be In the User comment field (‘gecos’ attribute in LDAP) to allow other Directory utility to work as designed regardless whether the default value dsa is used. For more information, see Support for User and Group Information Sources.

Since we have assumed that this is a running production system, the output should have some content similar to the "dxserver start democorp" shown above. Here, the dsa is the default DSAUSER value or it could be the account name your implementation chose to use. Then you can identify the running components from the following command and its sample output:

ps -ef | grep dsa
dsa         1839       1  0 08:59 ?        00:00:00 dxserver start xxxxxxxxx-management-ui
dsa         1851       1  0 08:59 ?        00:00:00 dxserver start xxxxxxxxx-monitoring-management-ui
dsa         1944       1  0 09:16 ?        00:00:01 python3 dxagent_cp_engine.py
dsa         2104       1  0 09:21 ?        00:00:00 /opt/CA/Directory/management-ui/node.js/bin/node /opt/CA/Directory/management-ui/node_modules/forever/bin/monitor ./bin/www
dsa         2112    2104  1 09:21 ?        00:00:00 /opt/CA/Directory/management-ui/node.js/bin/node /opt/CA/Directory/management-ui/bin/www

Here, we assume the DSAUSER is dsa while you can replace it with the value your implementation actually uses. The above example shows that the DxAgent is running, per python3 dxagent_cp-engine.py and also the Management UI is running too, per the management-ui/node.js/bin/node, along with the two DSAs, a dxserver instance is commonly referred as a DSA, that are supporting the Management UI. Also, the xxxxxxxx would have been replaced with the machine name of your CA Directory Server.

If you are not seeing the DxAgent and Management UI, a better way to see if they are installed but may not be running will login in as the DSAUSER and use the following command and sample output to confirm:

[dsa@xxxxxxxx ~]$ ls . ..
.:
bin  config  data  dxagent  install  logs  pid  samples  uninstall

..:
cadirmgmt_ui_install_20250115185205.log  dxserver       readme       relnotes
cadirmgmt_ui_install_20250115191722.log  management-ui  readme.html

Here we are assuming you have have logged into the linux using the dsa user and its current directory is the home directory of the CA Directory installation. In this example, you can see ther is the dxagent, dxserver, and management-ui that shows DxAgent and the Management UI are also installed.

Explore Your Whole CA Directory Implementation

To explore your whole CA Directory implementation, you can first start with the set of CA Directory Servers you have identified previously using the suggestions provided in the previous section. Then you will also need to dig into the config subdirectory of each CA Directory Server. There you will start with the config/servers subdirectory to locate the files that  has the dxi file extention. For example, 

[dsa@xxxxxxxx ~]$ ls config/servers/
democorp1.dxi  democorp.dxi  router.dxi  servers.help  unspsc.dxi

Here, we are seeing that there are four DSAs, namely democorp1, democorp, router, and unspsc that currently exist on this CA Directory Server. We then want to take a look at each of the dxi file and looking for information related to knowledge. For example a snippet of this sample router.dxi:

...
# knowledge
clear dsas;
source "../knowledge/sample.dxg";
...

hints that we need to look into the content of the config/knowledge/sample.dxg. As an example, the following is a snippet of what we have on our test system:

...
source "router.dxc";
source "democorpldap.dxc";
source "democorp1.dxc";
source "unspsc.dxc";
...

Further, we will be looking for the address lines of these dxc files. A sample command and output shows:

[dsa@xxxxxxxx ~]$ grep address config/knowledge/*dxc
config/knowledge/democorp1.dxc:    address       = tcp "xxxxxxxx" port 20389
config/knowledge/democorp.dxc:    address       = tcp "xxxxxxxx" port 19389
config/knowledge/democorpldap.dxc:    address       = ipv4 "yyyyyyyy" port 19389
config/knowledge/router.dxc:    address       = tcp "xxxxxxxx" port 19289
config/knowledge/unspsc.dxc:     address       = tcp "xxxxxxxx" port 19489

This sample happen to show that the address line used by democorp.dxc which is not part of the sample.dxg. Also, it shows two different machine names, xxxxxxxx and yyyyyyyy. It is an indication that you want to add the server that is hosting the LDAP Endpoint with machine name yyyyyyyy and port number 19389 into your over all CA Directory Servers as potentially it is another server where you have CA Directory installed as well.

Identify Your Management UI Usage

While we are looking for other possible servers to explore, if your DSA deployment is actually managed through the Management UI, you may not be seeing the dxi contains lines similar to 

source "../knowledge/sample.dxg";

Rather you can run the

grep address config/servers/*dxi

to simply retrieve the similar address lines directly from the dxi files. This is where the Management UI usage keeps the knowledge and address information.

If you have no documentation about your Management UI deployment, it could be difficult to locate the servers that host the service. The default port number the Management UI web application is 3000. This is a clue in addition to what have been mentioned above that may help.

Identify the CA Directory Installation Packages

Going back to the product documentation:

About Directory Components and Packages

we can also learn that there are two installation packages to install the CA Directory:

  • Directory Package, and
  • Directory Management UI Package

In addition, when we look at the Linux Installation of the documentation and the table of content on the right side of the page:

Install Directory on Linux

we see that the installation media are actually offered in the following formats:

  • ISO Packages (.iso files),
  • the .tar.gz files for Linux, .exe for Windows as well when you actually visit the CA Directory download area. The .tar.gz and .exe contain only the operating system specific files. The .iso contains both Linux and Windows installation files. And
  • Debian Packages (.deb files), RPM Packages (.rpm files) for Directory Package only

 

Identify and Use the Correct Installation Package for each Directory Server

As mentioned in the previous section, CA Directory offers two installation packages, namely the Directory Package and the Management UI Package, in different media formats. However, when upgrading/refreshing an existing installation, the newer/same version of the same package should be used. In other words, please do not use the Management UI Package to either add the Management UI component or upgrade a server that was done previously using the Directory Package as it will cause confusion in the installation history and actually cause the server to not functioning correctly. This is in part because the Management UI Package does allow you to install the DXserver and DxAgent without installing the Management UI component.

Under the usual circumstances, the correct package can be identified through looking at the "$DXHOME" or "$DXHOME/.." subdirectories for files similar to the following:

  • cadir_install_20250305082116.log -- indicating that it was installed using a Directory Package
  • cadirmgmt_ui_install_20250305091006.log -- indicating that it was installed using a Management UI Package

In-Place Upgrade Using Command Line

With the set of CA Directory Servers identified, each of them can be upgraded using the correct installation package, for the ones that use Directory Package, to upgrade them, one would run

dxsetup.sh

or

dxsetup.sh -dxuser "$DSAUSER"

Please see Install Directory Using Commands on Linux for more details.

For the ones that use Directory Management UI Package, run

dxmgmtuisetup.sh

or

dxmgmtuisetup.sh -dxuser "$DSAUSER"

Please see Install Management UI on Linux for more details.

Other Important Considerations

Since this KB is about planning in-place upgrading a production system, please also consult

Rolling In-Place upgrade

and plan for your upgrade to ensure that you have an upgrade plan that does not cause a production downtime.

As we assume that the CA Directory implementation that is being upgraded may be in an unknown state. It is also important to confrim that all CA Directory components have been functioning correctly before the upgrade is attempted.

Highlights

There are a few highlights in this KB:

  • The DXserver Administrator does not need to be the default value of dsa, regardless of its value, it is recommended to have the "DXserver Administrator" in the User comment field (‘gecos’ attribute in LDAP) 
  • To upgrade a CA Directory Server, a correct package should be used to avoid future support issue. For a system installed using a Directory Package, use the same or newer version of it to upgrade. Likewise, use a Directory Management UI Package to upgrade a system installed using the same type of package too.
  • Do not use a Directory Management UI Package to install the Management UI component onto a system that was installed using Directory Package previously.
  • Plan for using Rolling In-Place Upgrade to allow a no downtime upgrade. 
  • Ensure all known CA Directory components are functioning correctly before an upgrade is attempted.
Powered by Wolken Software