Advanced Support Operations

#### Search Results

Search

# 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

- xtsdssvc Sample Commands

### 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

- The xtsdsdmn Program

### 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

- UNIX Manual Configuration

### Windows Manual Configuration

To 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)
- Special Considerations

#### 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
- The -dirparms Setting
- SAGXTSDShost Needs to be Set
- The xtsdssvc -help Command

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

### On this page

- Windows NT-Based Directory Server Operations
- UNIX Directory Server Operations
- Manually Configuring the Directory Server