Use Management UI to Manage Existing In-Service Directory Servers

Products

• CA Directory

Issue/Introduction

There may be time when an enterprise wants to start using the CA Directory Management UI to help manage the deployment of the existing in-service directory servers. In addition to the common CA Directory/LDAP Services use cases, there are actually several Broadcom software solutions that either embed or encourage the customers to use CA Directory to provide the LDAP services these solutions need. To name a few:

• SiteMinder offers significant support on using CA Directory as its Policy Store, Session Store and even User Directory
• Symantec IGA uses CA Directory extensively
• CA EEM that provides authorization access for a number of Broadcom software solutions has CA Directory embedded

while none of these solutions explicitly suggest using the CA Directory Management UI.

Environment

Release 14.1
Component: CA Directory

Resolution

CA Directory Management UI Introduction

Management UI is also known as Directory Manager. It is a web application that allows us to monitor, configure, and control Directory Servers and DSAs. See

Directory Manager

for more information. It is also worthwhile to point out that the Management UI comes with a RestAPI interface that the administrators can use through either a built-in Swagger Web UI or custom RestAPI based command-line scripts.

As a quick introduction, after login to the management UI using a modern Web Browser to connect to a URL similar to:

https://example.com:3000

the user ID (default admin) and its password, specified during the installation, one will first create an Environment and then add a host from its Manage dropdown menu. A host is referring to a DXagent where it is configured using a DXagent name, a host name, a port number, a certificate authority cert, a client cert and a client key that are specified/generated at the time the DXagent component was installed typically during the installation of a Directory server.

For a new Directory server that has not been populated with any DSA, DSAs can then be created/configured/removed/controlled remotely through the web-based Management UI directly.

Management UI Repository

CA Directory Management UI has two Data DSAs. The DSA uses name in the format of <HOSTNAME>-management-ui is the repository that stores the Environment, the DXagent registrations, and most of the DSAs' definitions.

Avoid Manually Editing Configuration Files of the DSAs that are Managed Using Management UI

Even though Management UI uses its own repository, it still creates/maintains the traditional configuration files on the Directory servers. However, there is no bi-directional tight link between the configuration files and the data in the Management UI. This design allows a Directory server DSA continues to function even when the Management UI and/or the DXagent is offline.

Since no bi-drectional link exists between the Management UI and the physical configuration files on the Directory servers, it is generally advised not to change the configuration files without going through the Management UI once a Directory server is registered in a Management UI through its DXagent to avoid discrepancy between the two.

No Other DSAs on Production Management UI Servers

Two Data DSAs are created on the Management UI server during its installation. However, it is worthwhile to point out that the Management UI is designed not to manage these two DSAs even though the DXagent component is installed on the server too. To provide the functionality of the two DSAs, it is reasonable to see that the Directory Server component is also on a Management UI server as well.

It is suggested not to create other DSAs on the production Management UI servers regardless of how the DSAs are being managed. This suggestion is generally based on the management and performance considerations.

DXagent Introduction

A DXagent is usually installed during the installation of a Directory Server. During the installation, there is a need to specify the desired port to use, default 9443, a client certificate name that needs to be different from the hostname of the server, a password to protect the client certificate p12 file that is to be generated. Upon its successful installation, a CA certificate, a client PEM file, and a client key will be available to be used during the registration of a host within a Management UI Environment.

Please note that during the registration of a host within a Management UI Environment, the host name is the name of the hostname command output. It cannot be the IP address of the host. The reason is that this name needs to match up with the CN part of the certificate Subject DN that is providing secured communication between the Management UI and the DXagent.

Managing an Existing In-Service Directory Server Using Management UI

Even though immediately after a new Directory server through its DXagent has been added to a Management UI Environment, we can start using the Web UI to manage the deployment of the DSAs, the fact is that for an untrained CA Directory administrator, it could be a bit overwhelming to start creating a DSA from scratch.

Since the Management UI is relatively a newcomer, the percentage of administrators who use the Management UI is relatively small. Further, administrators who use CA Directory entitlement out of other Broadcom software many are not even aware of the Management UI component. For some, adding the CA Directory Management UI to their infrastructure is even considered another overhead one who choses not to take on as many of the administrators have been overwhelmed with the complexity of today's technology stack they have to work with day in and out. Nevertheless, the following features of the Management UI can greatly benefit the management of the deployment of the CA Directory DSAs:

• Remote and Centralized Management - Using Management UI saves administrators from having to login to the Directory servers to perform many of the regular administration tasks once a DXagent has been registered on the Management UI.
• Less Error-Prone Configuration Changes of DSAs - this includes many of the advanced CA Directory configurations, e.g. the multi-write configurations for high availability purposes can be done relatively easy and far less error-prone.
• Configuration Using a Graphical Web-Based User Interface - even though it may be overwhelming when using the Management UI the first time, over time it does expose many CA Directory features/functionality to the administrators.

Initial Population of DSAs Information of Existing In-Service DSAs

One of the best things the Management UI engineering team has done was to bring the traditional text-file based configurations directly into the Management UI repository. When a DXagent is successfully added as a host into a Management UI Environment, it will bring the effective configuration of each DSA exists on the Directory server. With this feature, a CA Directory administrator can easily overcome the initial difficulty when adopting the Management UI. As a quick demonstration, an administrator can run the setup under the samples/democorp to quickly create a demo DSA, then by going through the steps to create a Management UI Environment, add the DXagent into the Environment, then the democorp DSA configuration will be read into the Management UI repository. This will give the administrator a head start to see all the configuration settings that are applied to the democorp DSA and how the settings are grouped under each tab on the DSA configuration screen.

On-going DSA Configuration Management Using Management UI

As mentioned in the Introduction section, administrators need to avoid manually editing the configuration files of DSAs that are managed using the Management UI. Changes that are done to the configuration using the Management UI actually cause configuration files changes written back to the Directory server file system. These configuration file changes no longer follow the traditional configuration file convention. For example, with the current release, the configuration files no longer keep the "set dsa" knowledge configuration using dxc/dxg files under the config/knowledge subdirectory. Rather, the required "set dsa" are now kept in the dxi file under config/servers subdirectory.

Out-of-Band Editing Handling

Even though we have emphasized not to manually editing the DSAs configuration files once they are managed through the Management UI, it is actually not the end of the world as one sometime does run into the situations when such an editing is more desirable or even required. However, please keep in mind that the configuration settings between Management UI and configuration files is one way only, flowing from the Management UI to the configuration files. Hence any editing from the Management UI is going to overwrite all changes that were done on the configuration files manually.

To address the out-of-band editing need, the solution is a bit scary and sometime tedious but actually astonishingly simple. To bring manual editing of the configuration files back to the Management UI repository is a three-step process:

1. make an online backup of theMmanagement UI repository, that is the<HOSTNAME>-management-ui DSA
2. identify and delete the Management UI Environment that involves the impacted DSAs
3. recreate the Management UI Environment and re-register all the DXagents on the same Management UI Environment - this step is just like what is described in the "Initial Population of DSAs Information of Existing In-Service DSAs" section above and will clearly bring all the known DSAs with their effective settings back to the Management UI repository.

Important!! Do not just delete a host (DXagent) from an environment, it may cause existing knowledge group information to disappear and break some of the existing related configurations.

DXagent Maintenance

DXagent is down

When DXagent is down on a Directory Server, on the Management UI, the corresponding host icon on the Managegement UI hows an exclamation with additional messages. The common reasons for this include:

• The DXagent service is actually down.
  When this happens, run the start_dxagent to start on the Directory server to start it and make sure the right configuration is in-place so that when the Directory server is rebooted, the DXagent will also re-started.
• The information that was used to register the DXagent had become updated.
  First confirm the DXagent is actually running. This can then be fixed by editing the dxagent on the management UI with the corrected information including the CA Cert, the Client Cert, and the Client Key

DXagent logs

By default, two log files dxagent.access.log and dxagent.error.log and their daily rollover files are stored under the logs subdirectory under the dxserver.

Certificate Management

Both Management UI and DXagent use certificates to help secure network communications, see product documentation in case any of the certificates become expired:

Creating Directory CA and Client Certificates After Expiration