This document covers the following topics:
The Adabas Directory Server provides central management of directory services. It runs as either a Windows service or a UNIX daemon.
Instead of individual directory service configuration files for each application or machine, a centralized Directory Server enhances control and management of configuration, as shown in the figure below.
All directory information required to accomplish communication between clients and servers is obtained from the Directory Server. Only Directory Server address information, essentially the host and port of the Directory Server, is required for clients and servers to use the Directory Server.
Software AG recommends that you use only one Directory Server in your enterprise. However, if you install more than one, remember:
You will have to manage and administer multiple Directory Server configurations.
The more Directory Servers you use, the more physical resources on your system will be consumed.
You will need to be very careful about which Directory Server you select to use in your installation of a Software AG product -- especially if other Directory Servers have been installed by other Software AG products.
As you are restricted to a single pointer to a Directory Server in your DNS (via its SAGXTSDSHOST and SAGXTSDSPORT entries), all systems required to use a different Directory Server must be redirected using local, manual, administration. For more information on this manual administration, contact your Software AG technical support representative.
Software AG directory services are Uniform Resource Locators (URLs) used to identify the locations of Adabas databases, Entire Net-Work Kernels, and other target servers. These URLs allow a client to access a target server and allow a target server to "listen" for clients, as shown in the figure below.
Partitioning enhances your ability to use one Directory Server for your whole enterprise, rather than separate Directory Servers for different departments within your enterprise. The partitions each need to be managed separately, but only one Directory Server needs to be installed.
Here are some of the advantages of partitioning:
You can use partitioning to direct specific clients to specific databases.
If you have created Adabas databases with identical database IDs, you can use partitioning to correctly identify which client calls get directed to which Adabas database.
You can use partitioning to group client calls to an Adabas database, thus reducing the number of actual connections required for that database. This can be especially useful if you are using Entire Net-Work on the mainframe to access a specific Adabas database. Simply remove the access URL entries for the databases from the appropriate partition.
If your Software AG product supports the use of SSL, you can use impose real security requirements on calls made by clients in specific partitions.
Partitions can be defined for a Directory Server in the Adabas Manager. For complete information on maintaining partitions and the targets in them, read Maintaining Partitions and Maintaining Targets.
Suppose you configure your network as depicted in the following diagram:
In this diagram, partitioning is used to:
Restrict calls for Database 12 (on Machine 1) and Database 10 (on Machine 4) to clients 1 through 4 in the Partition 1 partition.
Restrict calls for Database 12 on Machine 7 to clients in the Partition 2 (Test) partition.
Establish a test environment. The Partition 2 (Test) partition has been set up as a testing partition. Only clients 5 and 6 are included in it and use Database 12 on Machine 7.
Group calls to Database 15 on the mainframe. The calls to this database are grouped by the Kernel 2 in Partition 1 and Kernel 4 in Partition 3, thus reducing the number of connections necessary for the database.
Impose security, via SSL, on the clients who are outside the firewall. Clients in Partition 3 are outside the company firewall. Security restrictions are also enforced when accessing Database 9, which is also outside the security firewall.
Partitions are assigned after installation using Software AG's Adabas Manager (AMN).
More than one Directory Server may be installed for your organization. This section describes how Software AG products determine which Directory Server to use.
The Directory Server implementation diagram is shown below.
Software AG products obtain the address of the Directory Server by searching the following sources in the specified order:
The environment variable
xtsdsurl. For example,
set xtsdsurl=tcpip://dshost:port
An xtsdsurl parameter passed by an
application call.
The well-known names SAGXTSDShost and SAGXTSDSport.
Port "4952" is used if the well-known name SAGXTSDSport is not defined.
The well-known names can be defined to a DNS server or as an
alternative they can be defined in a local "hosts" file. Use of the local
"hosts" file implies manual reconfiguration should the Directory Server host change,
but it has the advantage of supporting different Directory Servers per computer.
Using xtsdsurl has the advantage of using
different Directory Servers per process.
The following table defines the well known names, their purpose, and encoding requirements.
If you have the default Microsoft Windows XP personal firewall enabled on a PC and you would like to install and run the Directory Server on that PC, you will need to allow communications through the firewall on certain ports. You can do this in one of two ways: you can allow ports for a specific executable program or you can open a specific port. This section covers the following topics:
You can allow a specific executable program to open a port. To do so, issue the following commands:
C:\>netsh firewall add allowedprogram program="C:\Program Files\Software AG\Directory Server\xtsdssvcadi.exe" name="Adabas Directory Server" profile=ALL
Program xtsdssvcadi.exe is the Windows service file for Directory Server.
To remove the Directory Server as an allowed program, issue the following command:
C:\>netsh firewall delete allowedprogram program="C:\Program Files\Software AG\Directory Server\xtsdssvcadi.exe" profile=ALL
To open a specific port for use by the Directory Server in the firewall, issue the following command:
C:\>netsh firewall add portopening protocol=TCP port=nnnn name="Adabas Directory Server" profile=ALL
where nnnn is the port number you want to open. The default port for the Directory Server is 4952. For more information about Directory Server ports, read The Directory Server Port Number.
To close a specific port in the firewall, issue the following command:
C:\>netsh firewall delete portopening protocol=TCP port=nnnn profile=ALL
where nnnn is the port number you want to close.
Software AG communication information for your product is stored in one or more Adabas Directory Servers. The client's send message includes the target server name. Your Software AG product forwards the name and a use qualifier to the Directory Server, which returns an appropriate qualified URL (Universal Resource Locator) for the target back to your product.
Physical connection information (transport protocol , protocol specific parameters, timeout, and so on) must be entered in Directory Server target entries as qualified URLs before this communication can occur. The qualified URL contains the information required to direct the message to the correct target. The qualifier identifies which target URL is to be returned, based on the use implied by the qualifier. For example, a client send request returns an access target URL .
Directory Server target entries can be added manually using the Adabas Manager. For more information, read Maintaining Targets.
This section covers the following topics:
Physical connection information (transport protocol , protocol specific parameters, timeout, and so on) must be entered in the Directory Server target entries as qualified URLs before the Directory Server can be used for Software AG communication. Each qualified URL is specified in this format:
qualifier.protocol://host:port[?parm=value][&parm=value]...
For example:
access.tcpip://serverhost:3001?retry=3
| Entry | Meaning |
|---|---|
| "qualifier" | The use of this target URL. Three types of qualifiers are supported: "access", "connect", and "listen". For more information, read Qualifiers. |
| "protocol" | The communication protocol that will be used to connect to the server. For more information, read Protocols. |
| "host" | The name of the host computer where the server runs. |
| "port" | The server's port. The port is a destination or a receiving port, depending upon URL usage. Refer to the documentation for the specific server application to identify its valid port numbers and how they are assigned. |
| "parm" | One of multiple optional parameters that can be used. The first parameter is preceded by a "?" and subsequent parameters, if any, are preceded by an "&". For more information, read Parameters. |
| "value" | The value of the parameter. |
URLs are qualified in the Directory Server target entries by their use. Qualifiers are used to specify this use. Three qualifiers (uses) of a URL are supported in the Adabas Directory Server, as described in the following table:
| Qualifier (Use) | Description |
|---|---|
| access | Defines a communication path between the client and the server. The path provides the means for the client to communicate with the server either directly or through a proxy; this communication path tells the client where to find the server. Internally, a URL with this specification appears as an "XTSaccess" URL. |
| listen | Defines a listen port for the server or the proxy. Internally, a URL with this specification appears as an "XTSlisten" URL. |
| connect | Defines an active connection between a server and a proxy or between a proxy and an Entire Net-Work node. Internally, a URL with this specification appears as an "XTSconnect" URL. |
The following communication protocols can be used in Directory Server URLs.
| Protocol | Description |
|---|---|
| HTTP | The HTTP protocol is the network protocol used by the Web for Web-based browsers, servers, and other useful tools. |
| MHDR | Only Software AG products that require the proxy can use this protocol. The MHDR protocol allows the proxy to communicate with these Software AG products. The MHDR protocol supports two-byte database IDs; therefore, databases with database IDs greater than "255" can be accessed using this protocol. |
| RDA | Only Software AG products that require the proxy can use this protocol. The RDA protocol allows the proxy to communicate with these Software AG products. The RDA protocol does not support two-byte database IDs; therefore access is limited to database IDs less than "256". |
| SSL | The SSL (Secure Sockets Layer)
protocol enables secure TCP/IP point-to-point connections.
Note: |
| TCP/IP | The TCP/IP protocol is the standard communication protocol used. It provides the most basic and efficient service. |
The parameters you can specify in a qualified URL vary, depending on the protocol and qualifier selected. The following table describes the parameters available and indicates which protocols and qualifiers support them.
Software AG has registered port number 4952 with the Internet Assigned Numbers Authority (IANA) for use by the Directory Server. You are not required to use this port number for the Directory Server and can change it. However, use of this IANA port number for the Directory Server, when specified also as the Directory Server port expected by applications can eliminate Directory Server port number confusion. Software AG therefore recommends using the new IANA port 4952.
During Directory Server installation, the port number is usually assigned dynamically. If an existing Directory Server exists and is being upgraded, the Directory Server installation will use the port number of the existing installation. On Windows systems, if a new Directory Server is being installed, the default port number 4952 is used. On UNIX systems, if a new Directory Server is being installed, you are prompted for the port number. Note that in all cases, you can modify the port number used by Directory Server by running the Directory Server installation and modifying it there.
Effective with Version 5.2.1.1 of the Directory Server, you can no
longer specify the Directory Server port as "0" (zero).
However, if you have older installations of Directory Server that use port 0, it is
still supported, but it defaults to 4952. Software AG strongly recommends that
you change any older installations of Directory Server to specify a non-zero port
number, as opposed to using port 0. In addition, if you have specified the
Directory Server port number in the xtsdsurl environment
variable or parameter settings or in the
SAGXTSDSport
environment variable or DNS settings, Software AG strongly recommends setting
these to non-zero port numbers, as well.
When Directory Server 5.2.1.0 was released (with products such as Entire Net-Work 7.3.1 and Entire Net-Work Client 1.2.1), Directory Server ports set to "0" defaulted to the new IANA port number, 4952. This caused some problems with existing applications that expected port 0 to default to 4952. As a result of these problems, in Adabas Directory Server 5.2.1.1 the default for port 0 has been changed back to 4952, shipment of Directory Server 5.2.1.0 has been discontinued, and new Directory Server installations can no longer use port 0. If you upgrade Software AG products that used Directory Server 5.2.1.0 (such as Entire Net-Work 7.3.1 and Entire Net-Work Client 1.2.1) to newer versions of their software, be aware that the upgrade (or reinstallation) to Directory Server 5.2.1.1 will inherit any port 0 settings from the prior release. In these cases, you will need to manually modify the Directory Server port number to a valid non-zero port number after the upgrade (or reinstallation), as described in Modifying a Directory Server Link Definition .
If you need to change the Directory Server port number, follow the
general procedure described in these steps:
Within the settings for your application, change all specifications for the Directory Server port number to the new port number you want to use.
Shut down your application or application services or daemons.
Shut down the Directory Server service or daemon.
Modify the Directory Server installation, as appropriate for the operating system, changing the Directory Server port number to the new port number you want to use when prompted.
Start up the Directory Server service or daemon, if it is not automatically started after its installation was modified.
Start up your application or application services or daemons.
If you will be using SSL on UNIX platforms, a random file is required. This file contains entropy data that is used for generating random numbers by the SSL symmetric key allocation routines. System random files can usually be found as *.rnd files in the /dev/random or /dev/urandom directories. If these devices are not available on your system, contact your system administrator for assistance with installing them; some systems may require a patch.
In lieu of setting up a system random file, you can use a personal random file. For instructions on setting up a personal random file, refer to your system administrator.
Random files are identified to the system in one of the following ways:
The $RANDFILE environment variable can be set to the location of the random file.
A random file (*.rnd) can be stored in the current directory.
A random file (*.rnd) can be stored in the $HOME directory.
The RANDOM_FILE URL parameter can be used to specify the location of the random file.
Note:
Windows platforms have their own automated methods of
establishing the random file; consequently the manual identification or setup
of a random file is not necessary in Windows.
The Directory Server runs as either a Windows service or a UNIX daemon. To start or stop it, simply start or stop the service or daemon -- as you would any other Windows service or UNIX daemon.