This document describes some advanced configuration techniques you can perform for the Directory Server.
| Listening on Multiple Ports |
| Listening Using Multiple Protocols |
| Configuring a Failover Directory Server |
Ordinarily, the Directory Server listens on only one port for a specific qualified URL. If, however, you want different services of that qualified URL to listen on different ports, you must set up a listen URL for each port of the target. This is also useful if you want to use multiple protocols for the same target. Adabas Directory Server allows you to set up eight listen URLs for the same target.
For example, you might create two listen URLs for a target as follows:
When these two URLs are specified, Adabas Directory Server listens on ports 1000 and 1001 using the TCP/IP protocol.
And, if your Directory Server is named XTSDS, these listen entries would look like this internally:
XTSlisten.XTSDS[0]=TCPIP://localhost:1000 XTSlisten.XTSDS[0]=TCPIP://localhost:1001
To implement this feature, the Directory Server must be reconfigured from the default installation configuration, and these changes differ depending on the platform on which you run Adabas Directory Server. Contact Software AG Support for detailed instructions on implementation.
Ordinarily, the Directory Server listens on only one port using only one protocol. If, however, you want different services of that qualified URL to use different protocols, you must set up a listen URL for each protocol of the target, specifying a different port number for each listen URL. Adabas Directory Server allows you to set up eight listen URLs for the same target.
For example, you might create two listen URLs for a target as follows:
When these two URLs are specified, Adabas Directory Server listens on ports 1000 using the TCP/IP protocol and on port 1001 using the SSL protocol.
And, if your Directory Server is named XTSDS, these listen entries would look like this internally:
XTSlisten.XTSDS[0]=tcpip://localhost:1000 XTSlisten.XTSDS[0]=ssl://localhost:1001?cert_file=xtscappcert.pem&key_file=xtscappkey.pem&cert_passwd=ppppsw
To implement this feature, the Directory Server must be reconfigured from the default installation configuration, and these changes differ depending on the platform on which you run Adabas Directory Server. Contact Software AG Support for detailed instructions on implementation.
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 section covers the following topics:
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 at least version 5.6 (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. Adabas Directory Server clients can then access one of the two Directory Servers, whichever is running, using only the alias name. When the Adabas 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 Adabas 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:
This section describes the steps you must take to configure a failover Directory Server.
Note:
Both the primary and failover Directory Servers must at least be
version 5.6 Directory Servers.
Complete the following steps:
Install two Directory Servers on separate machines, configuring each machine with a static IP address.
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.
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).
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:
Edit the Windows service definition for the Directory Server and select the Log On tab.
On the Log On tab, select the This account radio button.
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.
Click the button.
Start the Directory Server.
Complete the following steps:
Choose a network alias name for the Directory Server configuration. This can be SAGXTSDSHOST or any other name you choose.
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.
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.
If you have existing Entire Net-Work or Entire Net-Work
Client installations in place
This update can easily be made using the Adabas Manager by setting the SAGXTSDSHOST for all services, kernels, and clients. Any running services or kernels must be restarted to pick up the change.
If you are installing Entire Net-Work or Entire Net-Work
Client 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.
Adabas Manager 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 Adabas Manager 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 Adabas Manager entry using the alias name as the host name in the Directory Server configuration, but this will give you no 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.