Configuring a Failover Directory Server

If you have the Software AG Directory Server 5.4 or later installed, you can configure a failover Directory Server. If your primary Directory Server fails for some reason, the failover Directory Server can continue providing service to your Directory Server clients.

This document covers the following topics:


Prerequisites

To successfully configure a failover Directory Server, you must be installing or running a Software AG product that supports Software AG's Internal Transport Subsystem (XTS) version 5.4 or later. This version of XTS and its failover Directory Server support is provided with Entire Net-Work 7.3.3 (or later) and with Entire Net-Work Client 1.3 (or later).

How it Works

Two Directory Servers are installed on separate servers with different IP addresses, but sharing the following things:

  • A single configuration file (xtsurl.cfg) in a shared location. This configuration file can be maintained by both Directory Servers.

  • An alias name defined in your network's DNS settings or in the hosts files of the machines acting as Directory Server clients.

  • The port numbers used by both Directory Servers are the same (SAGXTSDSPORT setting).

  • Both Directory Servers are version 5.4 (or later) Directory Servers.

During setup, one of the Directory Servers is assigned to the alias as the primary Directory Server; the second Directory Server installation becomes the failover Directory Server. Software AG Directory Server clients can then access one of the two Directory Servers, whichever is running, using only the alias name. When the Software AG Directory Server receives a service request from a client via the alias name, it first tries to use the primary Directory Server to service the request. If this attempt is unsuccessful, the Software AG Directory Server attempts to use the failover Directory Server to service the request. Since both Directory Servers share the same configuration file, the required directory information is available to either Directory Server at any time.

The following diagram depicts how this works:

graphics/dsfailov.png

Configuration Steps

This section describes the steps you must take to configure a failover Directory Server.

Note:
Both the primary and failover Directory Servers must be version 5.4 Directory Servers.

Step 1: Install the Two Directory Servers and Set Up the Registry and Windows Services for Both

Start of instruction setComplete the following steps:

  1. Install two 5.4 Directory Servers on separate machines, configuring each machine with a static IP address.

  2. Update the DirParms registry settings with the correct location of the shared Directory Server configuration file, xtsurl.cfg. This can be done in one of two ways:

    • Manually update the registry entry HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ADIDirSrv\Parameters\DirParms to read "file=\\host\share\xtsurl.cfg,lclenc=utf8" (where host is the name of the machine on which the configuration file can be found).

    • Run the xtsdssvcadi -dirparms function, specifying the DirParms registry setting as "file=\\host\share\xtsurl.cfg,lclenc=utf8". For example:

      xtsdssvcadi -dirparms file=\\host\share\xtsurl.cfg,lclenc=utf8

    Note:
    There is no need for the xtsurl.cfg to preexist at the location specified in the DirParms registry setting. The first Directory Server that uses it will create it if it does not already exist. If you have an existing xtsurl.cfg file you would prefer to use, copy it from its current to the location identified by the DirParms registry setting.

  3. Verify the Port registry setting for each Directory Server is identical (4952, by default). You can do this using either of the two methods mentioned in the previous step (however, the xtsdssvcadi function would be xtsdssvcadi -port instead).

  4. After the registry settings are updated, access the Windows Services applet for each instance of the Directory Server. For each Directory Server complete the following steps:

    1. Edit the Windows service definition for the Directory Server and select the Log On tab.

    2. On the Log On tab, select the This account radio button.

    3. Enter a user account name that is known to both this host and the file server where the Directory Server configuration file, xtsurl.cfg, is located. This can be a domain account or a local account that is configured on both machines with the same password. The account should have full control access rights to this configuration file location.

    4. Click the OK button.

    5. Start the Directory Server.

Step 2: Select and Define a Network Alias Name

Start of instruction setComplete the following steps:

  1. Choose a network alias name for the Directory Server configuration. This can be SAGXTSDSHOST or any other name you choose.

  2. In the network's DNS settings, make two entries for this alias name, one for each IP address of the two Directory Servers.

    Note:
    The server at the first IP address listed is the Directory Server used by all Directory Server clients. If it should fail, the server at the second IP address listed is used as the failover Directory Server.

    Or:
    You can specify these settings in the hosts file of each machine that will act as a Directory Server client, but the files must be maintained and the entries must be identical on all machines.

Step 3: Modify Your Directory Server Client Configurations

A Directory Server client is any machine that will make user of the Directory Server (for example, Entire Net-Work, Entire Net-Work Client, or Tamino installations).

For each Directory Server client, the alias name you assigned in Step 2: Select and Define a Network Alias Name must be identified in any configuration files that defines the location of the Directory Server (for example, SAGXTSDSHOST=aliasname). This includes the following files:

  • xts.config

  • service.config

  • kernel_name.KERNEL

  • any custom client configurations (these files are usually in uppercase characters with no field extension, by default, in the Entire Net-Work Client installation directory.

Start of instruction setIf you have existing Entire Net-Work 7.3.3 or Entire Net-Work Client 1.3 installations (or later) in place, this update can easily be made using the System Management Hub (SMH) by following these steps:

  1. Right-click on the Entire Net-Work or Entire Net-Work Client service name in SMH.

  2. Select the Set Parameters (in a server definition) or the Set Client Parameters (in a client definition) to access the Directory Server settings.

  3. Specify the Directory Server alias name for the SAGXTSDSHOST parameter on these panels and be sure to select the Update All Kernels or Update All Client Configurations check boxes. Then click OK.

  4. Any running services or kernels must be restarted to pick up the change.

Start of instruction setIf you are installing Entire Net-Work 7.3.3 or Entire Net-Work Client 1.3 for the first time, this update can easily be made during the installation, as follows:

  • When you are prompted for the location of the Directory Server during Entire Net-Work or Entire Net-Work Client installation, specify the alias name assigned this configuration instead of the host name of a Directory Server.

Maintaining the Two Directory Servers

System Management Hub (SMH) maintenance of the primary and failover Directory Servers is the same as for a single Directory Server, but here are some best practice considerations:

  • Maintain a separate SMH entry for each Directory Server, entering the actual host name of the Directory Server for each instance. This allows you to monitor the running or reachable status of each Directory Server separately.

  • If you want, you can set up an SMH entry using the alias name as the host name in the Directory Server configuration, but this will give you not indication of the running status of the individual Directory Servers using the alias. It will only give you the status of the whole alias (failover) structure, which should always show as "reachable." Consequently, this can give a false impression of the true availability or health of the individual Directory Servers using the alias.