Switching between Active and Passive Configurations

DirX Identity high availability supports an “active/passive” scenario (sometimes called a “warm standby” configuration), in which a secondary node or system—the “passive” configuration—acts as the backup for an identical primary system—the “active” configuration. The secondary system is completely installed and configured, but the software components are not running. If a failure occurs on the primary node, the software components are started on the secondary node. The switch is handled manually or is automated by using a failover component. Data is regularly replicated to the secondary system or stored on a shared disk.

DirX Identity high availability provides a tool for switching between active and passive DirX Identity configurations. If you have selected High Availability in the Choose Licensed Feature Set dialog during installation, you will find this tool installed in the directory:

dxi_install_path/ha/tools/switchConfiguration/

This directory contains the following files:

  • activatePassiveConfiguration.bat – the tool for activating the passive configuration.

  • activatePassiveConfigurationOnSample01.bat - an example of how to call the tool.

  • Sample tool configuration files

The activatePassiveConfiguration.bat tool performs the following tasks:

  • Sets the Scheduler flag in LDAP for the target Java-based Server (active/not active)

  • Sets the RequestWorkflow TimoutCheck flag in LDAP for the target Java-based server (active/not active)

  • Switches Tcl scripts from one C++-based Server to the other

  • Sets the Java-based / C++-based Server as inactive (active/not active)

  • Moves the configuration handler from one Java-based Server to the other (active/not active)

  • Adjusts associated servers at connected directories

  • Sets the Status Tracker flag on the C++-based Server (active/not active)

  • Sets the Notes connector on the C++-based Server (active/not active)

  • Start the services C++-based Server, Java-based Server, Message Broker and Tomcat server (optional)

Prerequisites

The tool requires a setup with one active and one passive DirX Identity configuration. The tool must be installed on the host where the passive part of DirX Identity is running, which implies that it must be installed on both systems, since the active configuration will change to a passive configuration when the tool is used.

Command-line Interface

To use the tool, specify the command:

activatePassiveConfiguration.bat parameters

Where parameters are all of the following:

-host hostname – the LDAP server that holds the Connectivity/Provisioning store

-port port – the port number on which the LDAP server is listening

-user ldap_user_dn – the user DN (domain admin)

-pass password – the password for the user DN

-ssl true | false – whether (true) or not (false) an SSL connection is in use

-domain domain - the domain name; for example, My-Company

-c configuration_file – the path and file name of the switching configuration file to use

Always call the tool on the host where you want to activate the configuration.

Here is an example command line:

activatePassiveConfiguration.bat -host jupiter.my-company.com
-port 389 -user cn=domainAdmin,cn=My-Company -pass ****
-domain My-Company -ssl false -c switchHAConfigFromTo.xml

Switching Configuration File

The activatePassiveConfiguration.bat tool uses a switching configuration file to control its operation. Switching configuration file samples are provided in the tool’s installation directory; these files can be changed and/or copied, renamed and relocated according to on-site requirements.

The switching configuration file contains configuration, logging, and process elements. The next sections describe these elements and their attributes.

configuration Element

The configuration element has the following attributes

  • startServices – if set to true, the tool starts the services C++-based Server, Java-based Server, Message Broker and Tomcat server on this host.

  • moveNotesConnector – if set to true, the tool activates the Notes Connector(s) on the new active configuration. If false, Notes connectors are ignored.

logging Element

The attributes of the logging element are similar to the corresponding parameters of Identity Manager in the DirX Identity configuration file dxi.cfg. They are:

  • fileName – the name of the trace file. The absolute or relative path is allowed.

  • level – possible values are:

0 – no trace, no error

1 – error

2-4 – warnings

5-8 – flow trace

9 – debug

Higher levels include the content of lower levels. For example, if you specify 5, errors and warnings are also written.

  • timestampformat – a format string to enable time stamp information to be included before each log entry in the trace file. For example:

timestampformat="EEE MMM d HH:mm:ss.SSS yyyy:"

If the timestampformat attribute is not specified, timestamps are not written into the trace file.

process Element and its mode Attribute

Note: in the descriptions in this section, the server to be activated is called the “to server”. The other server is called the “from server”.

The mode attribute of the process element in the switching configuration file specifies the method the tool is to use to determine the active configuration and which configuration should be activated. The following values are available:

  • auto – the “to server” name is determined by the local hostname.

  • fromto – the “from server” name and the “to server” name are specified explicitly.

  • state – the configuration to be switched to is evaluated by the state/registered attribute of the Java-based and C++-based Servers.

These values are described in more detail in the next sections. The sample configuration files delivered with the tool include examples of all three modes.

auto

When the process mode attribute value is auto, the tool assumes the host where it’s running must become the active configuration. The hostname is determined via the Java method InetAddress.getLocalHost().getHostName() and the fully qualified hostname read from the registry.

The tool looks for Java-based and C++-based servers that run on these hosts (one of the hostnames must match). Java-based/C++-based Server found is treated as the “to server”. The other Java-based / C++-based Server is treated as the “from server”. If exactly two Java-based /C++-based Servers are not found, an error is generated.

The file switchHAConfig.xml is a sample configuration file for auto mode.

fromto

When the mode attribute value is fromto, the hostnames for “from server” and “to server” servers are explicitly specified as follows:

<process mode="fromto" >
     <from>fromHostname</from>
     <to>toHostname</to>
</process>

The specified hostnames must match the names stored in LDAP for the Java-based and C++-based Servers. The file switchHAConfigFromTo.xml is a sample configuration file for the fromto mode.

state

When the mode attribute value is state, the tool treats the Java-based Server with the state STOPPED as the “to server” Java-based Server and treats the C++-based Server with an unchecked registered flag as the “to server” C++-based Server.

How the Tool Determines Hostnames from LDAP

The tool determines the hostnames from LDAP as follows:

  • Java-based Server – the last part of the name is used as the hostname (LDAP attribute dxmDisplayname)

  • C++-based Server – the name is used as the hostname (LDAP attribute dxmDisplayname)

Sample Activation

This section shows a sample trace of an activation. The activation occurs on dxi-sample01 (the “to server”). The other host (the “from server”) is dxi-sample03. The domain suffix is iam.sampledomain.net. Before calling the tool, the active configuration is on sample03. The following figure illustrates this configuration:

Active / Passive Configuration
Figure 1. Active / Passive Configuration

Here is the sample trace:

LOG(STG200): SwitchConfiguration called at 18.12.19, 13:48:42 MEZ with the following Parameters:
LOG(STG200):     tracefile: ./testMove.txt
LOG(STG200):     tracelevel: 5
LOG(STG200):     mode: automatic by local hostname
LOG(STG200):     move Notes Connector: true
LOG(STG200):     start Services: true
LOG(STG200):
LOG(STG200):     host: localhost
LOG(STG200):     port: 636
LOG(STG200):     user: cn=admin,dxmc=dirxmetahub
LOG(STG200):     ssl: true
LOG(STG200):     domain: My-Company
LOG(STG200): ------------------------------------------------------
LOG(STG200):
LOG(STG200):  hostname from getHostname: dxi-sample01
LOG(STG200):  fqn hostname from registry: dxi-sample01.iam.sampledomain.net
LOG(STG200): Moving from My-Company-S2-dxi-sample03.iam.sampledomain.net to My-Company-S1-dxi-sample01.iam.sampledomain.net
LOG(STG200): Moving CServer from dxi-sample03.iam.sampledomain.net to dxi-sample01.iam.sampledomain.net
LOG(STG200):
LOG(STG200): --------------------------------------------------------
LOG(STG200):
INF(ADC215): Moving dxmRunsScheduler flag from Server 'My-Company-S2-dxi-sample.iam.sampledomain.net' to Server 'My-Company-S1-dxi-sample01.iam.sampledomain.net'.
INF(ADC216): Moving 'Monitor C++-based Servers' flag from Server 'My-Company-S2-dxi-sample03.iam.sampledomain.net' to Server 'My-Company-S1-dxi-sample01.iam.sampledomain.net'.
INF(ADC200): Moving Primary from Server 'dxi-sample03.iam.sampledoamin.net' to Server 'dxi-sample01.iam.sampledomain.net'
LOG(STG200): Moving ConfigurationHandler.
LOG(STG200): Adjust associated servers at connected directories .
INF(ADC214): Moving Tcl workflows from Server 'dxi-sample03.iam.sampledomain.net' to Server 'dxi-sample01.iam.sampledomain.net'.
INF(ADC200): Moving StatusTracker from Server 'dxi-sample03.iam.sampledomain.net' to Server 'dxi-sample01.iam.sampledoamin.net'
INF(ADC200): Moving Notes connector active flag from Server 'dxi-sample03.iam.sampledoamin.net' to Server 'dxi-sample01.iam.sampledomain.net'
LOG(STG200): ------------------------------------------------------
LOG(STG200):  starting the services
LOG(STG200):
LOG(STG200): starting MessageBroker service : DirX Identity Message Broker 1 returned: 0
LOG(STG200): starting ids-j service : DirX Identity IdS-J-My-Company-S1 returned: 0
LOG(STG200): starting ids-c service returned: 0
LOG(STG200): starting TOMCAT service : Tomcat9 returned: 0
LOG(STG200): Ended with rc: 0