Adabas Directory Server Concepts

This document covers the following topics:


What is the Directory Server?

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.

graphics/dsrole.png

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.

graphics/dsvcrole.png

Partitioning a Directory Server

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 System Management Hub. 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:

graphics/partssl.png

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 System Management Hub (SMH).

Identifying Which Directory Server to Use

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.

graphics/dsid.png

Software AG products obtain the address of the Directory Server by searching the following sources in the specified order:

  1. The environment variable xtsdsurl. For example,

    set xtsdsurl=tcpip://dshost:port

  2. An xtsdsurl parameter passed by an application call.

  3. 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.

    Name Purpose
    SAGXTSDShost Specifies the IP address of the Directory Server.
    SAGXTSDSport

    Specifies, through an encoded IP address, the listen port of the Directory Server. The encoded IP address is in the following format:

    nnnn.mmmm.0.0

    ""where:

    nnnn = port / 256

    mmmm = port % 256 (256 modulus)

    The default port is "4952", therefore the encoded default port is "19.88.0.0" .

Configuring Directory Server for Windows XP Personal Firewall

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:

Allow Ports for a Specific Executable Program

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

Open a Specific Port

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.

Directory Server Target Entries

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 System Management Hub. For more information, read Maintaining Targets.

This section covers the following topics:

Qualified URL Structure

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.

Qualifiers

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.

Protocols

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:
A random file is required on UNIX systems if the SSL protocol is used or errors will occur. For complete information, read SSL Random File Requirements on UNIX Systems.

TCP/IP The TCP/IP protocol is the standard communication protocol used. It provides the most basic and efficient service.

Parameters

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.

Parameter Qualifier Support Protocol Support Description
cafile

access

connect

listen (client authentication only)

SSL - C applications only

Identifies the file containing the trusted CA certificates. The CA's certificate that signed an inbound certificate must reside in this file.

Note:
The file name specified may include the path information, unless a value for parameter capath is specified.

The cafile and capath parameters are required for client and server authentication.

capath

access

connect

listen (client authentication only)

SSL - C applications only

Supplies a hash value generated by the OpenSSL tool that specifies the location of a cafile in a complex CA structure. This location is not a path.

If parameter cafile includes location information, the value of capath should be ".", which is also the capath default.

The cafile and capath parameters are required for client and server authentication.

cert_file

access (client authentication only)

connect

listen

SSL - C applications only

Specifies the file containing the participant's certificate. The certificate file may contain the participant's private key.

Note:
The file name specified may include the path information. This is useful if the certificate is not in the current directory.

cert_passwd

access (client authentication only)

connect

listen

SSL - C applications only

Specifies the password for extracting information from the certificate file.

Note:
You can specify a fully qualified file name for this parameter. In this case, the file name you provide must contain the password.

charset all RDA Identifies the character encoding of the classic Entire Net-Work node associated with the URL. The value "EBCDIC" must be specified when and only when the URL is for a mainframe connection; no other value can be specified. The default value is "ASCII" which applies to non-mainframe connections.
chirpinterval all

RDA

SSL

TCP/IP

Specifies the number of seconds to wait between broadcast attempts for this connection. This broadcasting validates the availability of the connection specified by the URL.

The valid range is "0" through the maximum integer that can be stored by your operating system. The default value is "300"seconds (5 minutes). A value of "0" implies the default, "300".

key_file all SSL - C applications only

Specifies the file containing the server's private key. Must be specified if the private key is kept separate from the certificate file.

Note:
The file name specified may include the path information. This is useful if the certificate is not in the current directory.

keystore

access (client authentication only)

connect

listen

SSL - Java application only Identifies the Java keystore containing the participant's certificate and private key.
keystore_passwd

access (client authentication only)

connect

listen

SSL - Java application only Specifies the password for extracting information from keystore.
node all RDA Specifies the node ID by which this node will be known to a classic Entire Net-Work installation. The valid range is 1 through 65535. The default value is "7654". If more than one proxy is connected in the same Entire Net-Work domain, the node and nodename must be given to avoid conflicts.
nodename all RDA Specifies the node name by which this node will be known to a classic Entire Net-Work installation. The default value is the name of the proxy. If more than one proxy is connected in the same Entire Net-Work domain, the node and nodename must be given to avoid conflicts.
priority --- none Reserved for future use.
random_file all SSL - C applications only Identifies a text file that contains at least 14 random characters. The random characters in this file are used by the encryption routines to ensure that encryption itself occurs in a random manner.
raw all

RDA

SSL

TCP/IP

Indicates whether transport subsystem headers are sent. If present, then no transport subsystem headers are sent and no proxy is possible. Values are "on" and "off". The default value is "off".

RDA target entries must specify raw=on or the connections will not work.

reconnect all

RDA

SSL

TCP/IP

Indicates whether or not to reconnect if disconnected. Values are "on" or "off". The default value is "on".
recvtimeout all

RDA

SSL

TCP/IP

Specifies a protocol timeout value in seconds. Valid values range from "0" through the maximum integer that can be stored by your operating system. The default is "60" seconds. A value of "0" implies the default, "60".

This parameter is most useful for performance tuning. We do not recommend that you modify this parameter unless necessary. For assistance, contact Software AG Customer Support.

retry all

RDA

SSL

TCP/IP

Specifies the number of times to retry a connection. The valid range is 0 through 2147483648. The default value is "0" (no retry).
retryint all

RDA

SSL

TCP/IP

Specifies the interval in seconds between retries. The valid range is 0 through 2147483648. The default value is "60000" seconds.
security all RDA Specifies the name of a security file containing a list of IP addresses authorized to access this protocol. There is no default value.
sendtimeout all

RDA

SSL

TCP/IP

Specifies a protocol timeout value in seconds. Valid values range from "0" through the maximum integer that can be stored by your operating system. The default is "60" seconds. A value of "0" implies the default, "60".

This parameter is most useful for performance tuning. We do not recommend that you modify this parameter unless necessary. For assistance, contact Software AG Customer Support.

trace all

RDA

SSL

TCP/IP

Indicates whether or not to trace this connection. Values are "on" or "off". The default value is "off".
truststore

access

connect

listen (client authentication only)

SSL - Java application only Identifies the Java truststore containing the trusted CA certificates. The CA's certificate that signed an inbound certificate must reside in this file.
truststore_passwd

access

connect

listen (client authentication only)

SSL - Java application only Specifies the password for extracting information from the truststore.
ttl --- none Reserved for future use.
verify

access

connect

listen (client authentication only)

SSL - both C and Java applications Identifies the certificate processing level.

For C applications, valid values are:

0 (No peer verification occurs. This is the default value.)
1 (The application requests that the peer certificate be verified.)
2 (The application requests that the peer certificate be verified. A fatal condition occurs if there is no certificate.)
4 (The application requests that the peer certificate be verified only once.)
8 (The application requests that the issuer name is checked against the host name.)

Values 1, 2, and 4 can be specified in combination. For example, if you want to specify both 1 and 2, you would add them and set the verify parameter to "3".

Note:
This parameter must be set to "3" if you are performing client authentication.

For Java applications, valid values are:

0 (No peer verification occurs. This is the default value.)
1 (The application requests that the peer certificate be verified.)
2 (The application requests that the peer certificate be verified. A fatal condition occurs if there is no certificate.)
Values 4 and 8 are not valid for Java.

version all SSL - both C and Java applications

Indicates the SSL version:

1 (TLSv1)
2 (SSLv2). This value is required for Java applications.
3 (SSLv23). For C applications only, this indicates that Version 2 or 3 should be used.
4 (SSLv3)

The Directory Server Port Number

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 .

Changing the Directory Server Port Number

Start of instruction setIf you need to change the Directory Server port number, follow the general procedure described in these steps:

  1. Within the settings for your application, change all specifications for the Directory Server port number to the new port number you want to use.

  2. Shut down your application or application services or daemons.

  3. Shut down the Directory Server service or daemon.

  4. 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.

  5. Start up the Directory Server service or daemon, if it is not automatically started after its installation was modified.

  6. Start up your application or application services or daemons.

SSL Random File Requirements on UNIX Systems

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.

Starting and Stopping the Adabas Directory Server

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.