Advanced Support Operations

Ordinarily, when the Directory Server is installed, it is automatically defined as a Windows service on Windows systems and a UNIX daemon on UNIX systems. In addition, the predefined Directory Server parameters set when you install Directory Server are usually sufficient for the needs of most products and environments. If you find that you have a specific need or are having a specific problem with your Directory Server installation, you should contact Software AG Customer Support. They will assist you in resolving the problem.

This document describes Directory Server operations you might be asked to perform under the guidance of Software AG Customer Support. It covers the following topics:

Windows NT-Based Directory Server Operations
UNIX Directory Server Operations
Manually Configuring the Directory Server
Warning:
We recommend that you perform the operations described in this document with the supervision of a Software AG Customer Support representative.

Windows NT-Based Directory Server Operations

The Directory Server for Windows runs as a Windows service. If used, the Windows Directory Server will start at boot time by default. However configuration and operational control is available via the Windows Directory Server command line program xtsdssvc.

The xtsdssvc program can be used to perform the following tasks:

  • Register the Directory Server as a Windows service.

  • Unregister the Directory Server service and remove the recorded startup parameters.

  • Start the service.

  • Stop the service.

  • Obtain a status of the service.

  • Set the Directory Server parameters.

Note the Windows Services control panel applet can be used to start and stop the service as well. The Directory Server Windows service name is "Adabas Directory Server".

This section covers the following topics:

xtsdssvc Parameters

The following parameters can be passed to xtsdssvc:

Parameter Description
-help
Prints the help message.
-register
Registers the Adabas Directory Server service. It will be started at the next system boot.
-unregister
Removes the Adabas Directory Server service from the database of all registered services. Also removes all registry entries belonging to the Adabas Directory Server service.
-start
Starts the Adabas Directory Server service.
-stop
Stops the Adabas Directory Server service.
-status
Prints the status of the Adabas Directory Server service and displays the current configuration parameters.
-name STRING
Sets the serverDirectory Server name, where STRING is the name. This is not the same as the Adabas Directory Server Windows service name. The default value is "XTSDIR".
-port NUMBER
Sets the Directory Server listen port, where NUMBER is the port number. A value of "0" (zero) means that the value assigned to the well-known name SAGXTSDSport will be used. If SAGXTSDSport is not defined, port number "4952" will be used. The default value is "0".
-directory STRING
Sets the type of Directory Server to be used, where STRING is the Directory Server type. The default value is "INIDIR".
-dirparms STRING
Sets the parameters required by the selected Directory Server, where STRING indicates the Directory Server parameters applicable to the type of Directory Server defined in the -directory parameter. The default value is "file=C:\Documents and Settings\All Users\Application Data\Software AG\xtsurl.cfg".
-logdir STRING

Specifies the directory to contain the Directory Server trace log controlled by the -trace parameter (described below). Enclose value in double quotes if the directory name contains spaces.

The default value set by the installation is "C:\Documents and Settings\All Users\Application Data\Software AG\".

If null, the log will be written to "%SystemRoot%\system32".

The log filename is xtsnnnnn.log, where nnnnn is a sequential number

-trace NUMBER

Sets the trace level to be used by the Directory Server, where NUMBER indicates the trace level.

The default value is "0".

Specify "65534" to obtain full tracing.

Specifying "65535" results in an internal buffer trace only, do not specify "65535",unless specifically instructed to do so.

The Adabas Directory Server Windows service should be stopped and restarted when changing the trace value.

-debug NUMBER

Indicates whether service control manager related debugging output should be produced.

The default value is "0".

NUMBER should be set to "0" (output not produced) or "1" (output produced).

The output is written to the Windows System Event Log.

-tcpip STRING

Sets the TCPIP protocol type used in TCPIP communications. Valid values are "IPV6" (for IPv6 communications), "IPV4" (for IPv4 communications), or "UNSPEC" (to let the domain name server determine the protocol type).

The default is "UNSPEC".

Warning:
We recommend that you use the default value for this parameter, allowing the DNS to determine which communication protocol is appropriate. If you do specify a specific protocol (IPv4 or IPv6), calls to Directory Server via the other protocol type are ignored.

xtsdssvc Sample Commands

The following examples illustrate how to perform various tasks using the xtsdssvc command:

Task Sample Command
Register Directory Server xtsdssvc -register

Parameters should be set before registering the server.

Unregister Directory Server xtsdssvc -unregister
Query status of Directory Server xtsdssvc -status
Start Directory Server xtsdssvc -start
Stop Directory Server xtsdssvc -stop
Set Directory Server parameters xtsdssvc -name xtsdir -port 0 -directory INIDIR -dirparms "file=C:\Documents and Settings\All Users\Application Data\Software AG\xtsurl.cfg" -trace0 -debug0

Note:
You can also use a Windows program item to check the status of the Directory Server. Select the following items from the Windows Start Menu: Programs>Adabas Directory Server>Directory Server Status.

UNIX Directory Server Operations

The Directory Server for UNIX is run as a UNIX daemon.

This section covers the following topics:

Running Directory Server as a UNIX Daemon

After Adabas Directory Server is installed, it can be run as a UNIX daemon. Modify the shell script $SAG/common/bin/xtsdsdmn.sh, if desired (no modifications are required), and then invoke it.

The xtsdsdmn Program

The xtsdsdmn program, located in the $SAG/common/bin subdirectory, is used to start and stop the Directory Server.

To stop the Directory Server daemon, first obtain the xtsdsdmn process ID, as follows:

ps -ef | grep xtsdsdmn

Then enter the UNIX kill command and the process ID (nnnnn), as follows:

kill -9 nnnnn

The parameters described in the following table can be passed to xtsdsdmn at start time.

Parameter Value
-name STRING
Indicates the Adabas Directory Server name. The default value is "XTSDIR".
-port  NUMBER
Indicates the listen port for the server. A "0" value indicates that either the value defined by SAGXTSDSport or "4952" will be used. If SAGXTSDSport is not defined then "4952" is used. The default value is "0".
-directory STRING
Indicates the type of Directory Server to be employed. The default value is "INIDIR".
-dirparms STRING

Sets directory parameters appropriate for the Directory Server identified by the -directory parameter. If the -directory parameter is set to "INIDIR", then this parameter is set to the full path name of the Adabas Directory Server URL configuration file.

The installation procedure sets this parameter to reference the file: $SAG/common/xts/com/softwareag/XTS/xtsurl.cfg.

-logdir STRING
Specifies the directory to contain the Directory Server process log controlled by the -trace parameter. (Refer to the documentation for -trace below. The installation default value is null, which results writing to the root directory by default.
-trace NUMBER

Turns on Directory Server process logging. The log is written to the root directory or the directory set by -logdir parameter. The default value is "0".

Specify "65534" to obtain full tracing. Specifying "65535" results in an internal buffer trace only, do not specify "65535", unless specifically instructed to do so.

The Directory Server should be stopped and restarted when changing the trace value.

-pid This parameter is optional. Indicates the file where the Directory Server daemon process identifier will be recorded. When the daemon is terminated, an attempt will be made to delete the file identified in this parameter.
-help
Prints the help message.
-tcpip STRING

Sets the TCPIP protocol type used in TCPIP communications. Valid values are "IPV6" (for IPv6 communications), "IPV4" (for IPv4 communications), or "UNSPEC" (to let the domain name server determine the protocol type).

The default is "UNSPEC".

Warning:
We recommend that you use the default value for this parameter, allowing the DNS to determine which communication protocol is appropriate. If you do specify a specific protocol (IPv4 or IPv6), calls to Directory Server via the other protocol type are ignored.

Manually Configuring the Directory Server

Most configuration specifications for Directory Server can be made using AMN. Manual configuration of the Directory Server might be required if a configuration is lost or corrupted. Under normal circumstances, manual configuration is not required.

If you need to perform manual configuration of the Directory Server, please contact Software AG Customer Support for assistance.

This section covers the following topics:

Windows Manual Configuration

Start of instruction setTo manually configure the Directory Server:

  1. Position to the Adabas Directory Server installation directory.

  2. Set the Directory Server parameters.

  3. Register the Directory Server service.

  4. Start the Directory Server service.

  5. Confirm the configuration.

Refer to the following sections (Example Commands (Windows) and Example Commands (UNIX) for examples of each of these steps.

Example Commands (Windows)

Note in the following commands "x:" is used to indicate the drive where the Adabas Directory Server has been installed. This would normally be the "C" drive. Substitute the installation's actual value before issuing the commands. From a Windows command prompt window, issue the following commands:

Activity Example Command
Position to the Adabas Directory Server installation directory. cd x:\Program Files\Software AG\Directory Server
Set the Directory Server parameters. xtsdssvc -name XTSDIR -port 0 -directory INIDIR -dirparms "file=c:\Documents and Settings\All Users\Application Data\Software AG\xtsurl.cfg" -logdir "c:\Document and Settings\All Users\Application Data\Software AG" -trace 0 -debug 0
Register the Directory Server service. xtsdssvc -register
Start the Directory Server service. xtsdssvc -start
Confirm the configuration. xtsdssvc -status

Once the Directory Server is registered it will be automatically started at boot time. The Windows Services control panel application can be used to confirm the automatic start setting. Navigate the following program items to get to the services control panel applet: Start>Settings>Control Panel>Administrative Tools>Services (Windows 2000) . The Adabas Directory Server service is listed as Adabas Directory Server.

Special Considerations

This section covers the following topics:

The -port 0 Setting

Setting the port parameter to "0" indicates that the actual port to be used is determined by the DNS resolution of SAGXTSDSport. If SAGXTSDSport is not resolved, then port "4952" is used. The port number is encoded as an IP address, explained below. One should determine the setting or non-setting of SAGXTSDSport. If set, then confirm that the desired port is encoded correctly. To confirm, issue the following ping command:

PING SAGXTSDSport

Text similar to the following should appear if SAGXTSDSport is defined:

Pinging SAGXTSDSport [19.88.0.0] with 32 bytes of data:
Reply from 206.24.181.1: Destination host unreachable.
Reply from 206.24.181.1: Destination host unreachable.
Reply from 206.24.181.1: Destination host unreachable.
Reply from 206.24.181.1: Destination host unreachable.
Ping statistics for 19.88.0.0:
Packets: 
Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum =0ms, Maximum = 0ms, Average = 0ms

The "Destination host unreachable" is expected as the SAGXTSDSport is the port number encoded as an IP address and as such is not a real IP address.

The port as an IP address encoding is done as follows:" port/256.port%256.0.0"

In above case, "19.88.0.0" equates to "4952" (i.e., 256*49+187).

If SAGXTSDSport is set but is not encoded to the the desired port value then one of the following should be done:

  1. Correct DNS entry.

  2. Define SAGXTSDSport in the local "hosts" file.

    • Under windows the local hosts file can be found at %systemroot%\system32\drivers\etc

    • Example entry for using port 4952: "19.88.0.0 SAGXTSDSport ".

The -dirparms Setting

The -dirparms parameter specifies the fully qualified name of the flat file repository to be used by the Directory Server. There should be an xtsurl.cfg file in the standard Windows application data subdirectory:

c:\Documents and Settings\All Users\Application Data\Software AG\.

SAGXTSDShost Needs to be Set

In order for applications to access the Directory Server, SAGXTSDShost must be set and point to the Directory Server host. If SAGXTSDShost is not set, confirm with a PING SAGXTSDShost command , then set SAGXTSDShost in one of the following ways:

  • Define to a DNS server.

  • Define in the local hosts file for each computer needing access to the Directory Server.

  • Set an XTSDSURL environmental variable for any process that needs access to the Directory Server.

For example: set xtsdsurl=tcpip://dirserverhost:port.

The xtsdssvc -help Command

The command xtsdssvc -help will display help on other xtsdssvc commands.

UNIX Manual Configuration

Under UNIX, manual configuration is possible by modifying the $SAG/common/bin/xtsdsdmn.sh script.

The SAGXTSDSport and SAGXTSDShost settings should be confirmed as in the Windows case.

The xtsurl.cfg file is located at $SAG/common/xts/com/softwareag/XTS. If xtsurl.cfg does not exist at the location there should be an xtsurl.ghost file at that location. If no xtsurl.cfg exists at $SAG/common/xts/com/softwareag/XTS the xtsurl.ghost file can be renamed to xtsurl.cfg.