Adabas TCP/IP

#### Search Results

Search

# Adabas TCP/IP

This section contains information about Adabas TCP/IP (ADATCP) and how it can be used as an access method that provides point-to-point connections between the client application and the Adabas Server. It covers the following topics:

- Basic Communication

- Encrypted Communication (TLS/SSL)

- Internal Architecture

- Licensing

- Troubleshooting

- Nucleus error message

- Connectivity Problems on Linux

- Performance

- Use Cases - FAQ

- Known Restrictions

## Basic Communication

- Concepts

- Adabas Server

- Adabas Client

- Entire Net-Work Client

### Concepts

ADATCP is the new access method that provides point-to-point connections between the client application and the Adabas Server. It is covered by the Adabas Client Interface and the Adabas Server and it is intended for remote database access, although local access via ADATCP is also possible. The currently used access method based on IPC (local or remote via WCP) is still the default method for client applications. The TCP/IP access method can be chosen by using a configuration file on the client side and by configuring the Adabas server via new nucleus parameters. The usage of the new method is transparent for the client application.

The following diagram shows an overview of typical setup:

To enable ADATCP for an Adabas database, additional nucleus parameter settings are required, like the `ADATCP` switch and `PORTNUMBER`. Classic IPC communication is still possible.

To enable ADATCP for a client application, add a connection string for the database ID to the Adabas Client (ACL) configuration file (dbmapping.txt).

In the example above, database 206 is configured to use ADATCP and database 199 to use classic IPC communication.

### Adabas Server

With the release of Adabas Version 6.7, a new TCP/IP-based access method is provided. This new method supports the following scenarios:

- Support Adabas running in a Docker container where TCP/IP is the standard communication method between containers.

- Point-to-Point communication.

- Easy configuration.

- Reduced topology.

Therefore, the Adabas server as well as the Adabas client have been extended. The IPC based communication is still available.

The following table provides an overview of the new Adabas nucleus parameters available for ADATCP:

Parameter | Description
--- | ---
`[NO]ADATCP` | Enable the TCP/IP receiver (NOADATCP to disable it)
`PORTNUMBER` | The TCP/IP port the database listens on.
`TCPRECEIVER` | Number of receiver threads.
`TCPCONNECTIONS` | Maximum number of parallel connections per receiver thread.
`TCPATB` | Attached buffer size for each TCP/IP receiver (similar to LAB/LABX). These buffers are exclusively used by the TCP/IP receiver and are not IPC based.

The ADATCP option needs to be licensed. If this license (the Entire Net-Work license) is missing, ADATCP cannot be enabled. Please read section Licensing for a complete overview of licensing options.

To run the Community Edition of Adabas a license is not required, neither the Adabas license nor the Entire Net-Work license. However, the Community Edition restricts the ADATCP parameters to the following values:

Parameter | Value
--- | ---
`TCPRECEIVER` | 1
`TCPCONNECTIONS` | 4
`TCPATB` | 10 MB

Examples and default values can be found in the corresponding ADANUC documentation.

Note:

Please ensure that the database was started using the required ADATCP parameter settings. The following initialization message is written to the Adabas nucleus logfile during a successful startup:

    ADANUC-I-ADATCPENAB, Adatcp enabled, listening on port: ...

Then you may continue to change the local Adabas Client configuration file.

### Adabas Client

To enable TCP/IP access for existing client applications without any change of the application, a configuration file needs to be updated with the according TCP/IP settings of the database. Please keep in mind that all Adabas utilities are also a kind of client application for the Adabas nucleus.

For each TCP/IP enabled database an entry needs to be added to the configuration file dbmapping.txt:

    <dbid> = adatcp://<fqdn>:<port>

where `fqdn` means "fully qualified domain name". Example for database 200 which runs on host `srvada01` and listens on port 61200:

    200 = adatcp://srvada01.softwareag.com:61200

For Linux the default path and file name of the configuration file is ${ACLDIR}/config/dbmapping.txt.

For Windows the default path and file name of the configuration file is %ACL64DIR%\..\config\dbmapping.txt.

When used for the first time, the file dbmapping.tmpl provided in the configuration directory can be copied to dbmapping.txt and then modified accordingly.

These entries describe the mapping of Adabas DBIDs to a connect string with the appropriate TCP/IP parameters needed on the client side. If a different mapping file should be used, the path name can be specified by the environment variable `ADA_DB_MAPPING`.

There are parameters for the mapping that can influence the TCP/IP behavior. The format of the target entry with parameters is:

    <dbid> = adatcp://<fqdn>:<port>[?parm=value][&parm=value]…

The following table provides an overview of the parameters that are related to TCP/IP:

Parameter | Description
--- | ---
`TCPKEEPALIVE=yes|no` | Used to check if the connection is still valid and to prevent the connection from being closed due to inactivity. When set to yes, this option is passed to the TCP endpoint.
`TCPKEEPIDLE=number` | This parameter is only used if `TCPKEEPALIVE` is set. The time (in seconds) that the connection must remain idle before TCP starts sending keepalive probes.
`TCPKEEPINTVL=number` | This parameter is only used if `TCPKEEPALIVE` is set. The time (in seconds) between individual keepalive probes.
`TCPKEEPCNT=number` | This parameter is only used if `TCPKEEPALIVE` is set. The maximum number of keepalive probes that TCP should send before dropping the connection.
`TCPCONNECTTIMEOUT=number` | The maximum time in seconds that are allowed for the connection attempt. The default is 3 seconds. Set this to zero to disable the timeout handling.

Examples:

    66 = adatcp://srvada01.softwareag.com:51066?tcpconnecttimeout=1.5

    66 = adatcp://srvada01.softwareag.com:51066?tcpkeepalive=yes&tcpkeepidle=100

    66 = ada-tcp://srvada01:60100?cluster=adatcp://srvada02:60100;adatcp://srvada03:60100&tcpconnecttimeout=1.5

### Entire Net-Work Client

If the Entire Net-Work Client has been installed, and the appropriate environment is set, the Adabas Client and the Entire Net-Work Client will use a common configuration file and a common syntax for database entries. The file will be searched in the following order:

1. Evaluate the environment variable ADA_DB_MAPPING.

2. Evaluate the environment variable WCLCONFIG.

3. Search in the directory specified by the environment variable WCLDATADIR for the file xts.config..

4. Search in the default directory for the default file name (see above).

The common syntax is the same as that known from Entire Net-Work:

    <partition>#XTSaccess.<dbid>[0]=<protocol>://<host>:<port><?params>

where

- <partition> is the partition name as used by Entire Net-Work (see also the Entire Net-Work documentation: Concepts and Facilities: Understanding Partitioning);

- <dbid> is the database ID;

- <protocol> is the name of the ADATCP protocol: either adatcp or adatcps;

- <port> is the listen port of the database;

- <?params> is a list of optional parameters of the form: ?parameter1[&parameter2…].

Important
The database definition in the configuration file decides whether a database will be accessed via TCP or via IPC. If a database was added to the mapping file, only TCP/IP communication will be used. No other communication method (neither local IPC communication nor Entire Net-Work) is used. See also Troubleshooting.

## Encrypted Communication (TLS/SSL)

- Concepts

- Adabas Server

- Adabas Client

### Concepts

With the release of Adabas Version 6.7.1, an additional TCP/IP-based access method is provided, which allows encrypted communication between Adabas Server and Clients supporting the Transport Layer Security (TLS), formerly known as Secure Sockets Layer (SSL).

To use the encrypted communication functionality, the ADABAS Encryption for Linux (AEL) license is required.

Transport Layer Security (TLS) is a standard protocol used to manage the security of message transmissions in an open communications network, such as the Internet. Two types of security are provided:

- Authentication

- Encryption

TLS uses TCP/IP for its physical communications. In addition, TLS uses public and private key encryption for both authentication and data encryption keys. These keys are obtained from a certificate authority (CA).

#### Authentication

Using digital signatures, the partners in a conversation (the client and server) can be authenticated.

A digital signature is a digital code that can be attached to an electronically-transmitted message that uniquely identifies the sender. The purpose of a digital signature is to authenticate the identity of the individual sending the message using a private key to sign the message, and a public key to verify the signed message. These keys are obtained from a certificate authority of some kind, as described in

Certificate Authorities.

#### Encryption and Decryption

Using data encryption and decryption, messages are secured as they pass through the network.

Encryption is the conversion of data into cipher text, which cannot be easily understood without access to the encryption or decryption key. Decryption is the process of converting encrypted data back into its original form, so it can be understood. To decrypt the contents of an encrypted message, a decryption key is required. Encryption keys are generated automatically after the successful handshake between the client and server. The handshake between the client and server is handled through the use of private and public keys, which are obtained from a certificate authority of some kind, as described in Certificate Authorities.

#### Certificate Authorities

A certificate authority issues and manages certificates for message encryption. It also verifies (authenticates) the information provided by the requestor of a digital certificate. If verification is successful, the certificate authority can then issue a certificate.

The following diagram shows how certificates are used during authentication:

The following diagram shows how certificates are used during data encryption:

Various organizations, such as VeriSign, act as external certificate authorities for other companies and supply certificates for authentication and encryption as requested by their clients. For Adabas, you can use an external certificate authority to provide your certificates or, for testing purposes only, you can use the open source SSL Toolkit to become your own certificate authority.

The following diagram shows an overview of typical TLS/SSL enabled configuration:

### Adabas Server

In order to use Adabas with TLS, the ADATCP must be enabled, and the SSL port number (SSLPORTNUMBER parameter) must be set. If only SSL communication is desired, the TCP/IP port number (PORTNUMBER parameter) can be set to '0' which disables the non-encrypted communication. Adabas uses version 1.1 based OpenSSL libraries, which are part of the distribution.

Any valid TLS/SSL certificate issued by a certificate authority or a self-signed certificate will be accepted. In the case of self-signed certificates, the verification level (SSLVERIFY) must be set to ‘0’. Client certificates are not validated in this case, but nevertheless the communication is still encrypted. The following table provides an overview of the Adabas nucleus parameters related to the encryption with OpenSSL:

Parameter | Description
--- | ---
SSLPORTNUMBER | The TCP/IP port that the database listens on for SSL encrypted communication.
SSLCERTFILE | The fully-qualified path name to the certificate file.
SSLKEYFILE | The fully-qualified path name to the private key file.
SSLCADIRECTORY | Directory name where the certificates of the Certificate Authority (CA) are stored.
SSLCAFILE | CA certificate file or certificate chain file.
SSLPASSWORD | Passphrase or file name which contains the passphrase. In the case of a file, the password is encrypted on the first access and written back to the file. The file must have write access permissions. After the encryption, change the file access permissions to read-only. Password rules: Leading or trailing white spaces (like tabs and spaces) are ignored when reading the password from the file.
SSLVERIFY | Verification level of client certificates: 0 = no verification 1-10 = maximum depth for the certificate chain verification that shall be allowed.

This feature, called Adabas Encryption for Linux (AEL), must be licensed separately and is available only on Linux. To activate the encryption, copy the AEL license file to <installation directory>/common/conf/ael68.xml.

### Adabas Client

The Adabas Client allows encrypted connections using the keyword adatcps for the connection string (instead of adatcp) in order to support protected communications between the client and the server. The format of the secured target entry is:

    <dbid> = adatcps://host:port[?parm=value][&parm=value]…

The following table provides an overview of the Adabas Client parameters related to the encryption with OpenSSL:

Parameter | Description
--- | ---
CERT_FILE | The fully-qualified path name to the certificate file.
KEY_FILE | The fully-qualified path name to the private key file.
CA_PATH | Directory name where the certificates of the Certificate Authority (CA) are stored.
CA_FILE | CA certificate file or certificate chain file.
PASSWORD | Passphrase or file name which contains the passphrase. In the case of a file, the password is encrypted on the first access and written back to the file. The file must have write access permissions. After the encryption, change the file access permissions to read-only. Password rules: Leading or trailing white spaces (like tabs and spaces) are ignored when reading the password from the file.
VERIFY | Verification level of server certificates: 0 = no verification 1-10 = maximum depth for the certificate chain verification that shall be allowed.

## Internal Architecture

The following diagram shows an overview of the data flow between internal components:

The major building blocks are:

- ADATCP Listen Thread

  - Listens for incoming TCP and/or SSL connections

  - Accepts and initializes or rejects connections

  - Allocates the user context

  - Distributes workload to one of the receiver threads (configurable number of instances)

- ADATCP Receiver Threads

  - Starts a ReadEventLoop per thread

  - Waits for read request of an accepted connection

  - Does a TCP- or SSL-Read, depending on the allocated user context

  - Prepares and hands over the call to the Adabas Command Queue

- Adabas Nucleus Worker Threads

  - Does the Adabas command processing

  - Does a TCP- or SSL-Send,depending on the allocated user context

The listen and receiver threads are working event driven, which means they do not consume CPU time until the appropriate event happens.

## Licensing

The point-to-point communication with Adabas on Linux and Windows based on TCP/IP is part of the Entire Net-Work solution regardless whether the client using this communication method is local or remote to the database.

To use the encrypted communication functionality, the ADABAS Encryption for Linux (AEL) license is required.

The following table provides an overview of the different licensing possibilities regarding ADATCP:

License Available | ADATCP Activation
--- | ---
ADA + WCP + AEL | Enabled without restrictions
ADA + WCP | Enabled without encryption feature
ADA | Disabled
WCP | Community Edition with restrictions
None | Community Edition with restrictions

Appropriate messages are provided in the nucleus log file.

Activating the Entire Net-Work License on Linux

1. Copy the license key to a temporary location on your machine.

2. Change your directory to the Adabas/INSTALL directory of your main installation directory.

3. Execute the following adalic command to activate the license file:

       adalic activate license_file

   Where license_file is the fully qualified path to your license file.

Activating the Entire Net-Work License on Windows

1. Copy the license key to a temporary location on your machine.

2. Start a Command Prompt to activate the license via the Start menu under: All Programs> Start Menu group name > Administration > Adabas 6.8 > Activate License.

3. In the Command Prompt execute the following adalic command to activate the license file:

       adalic activate license_file

   Where license_file is the fully qualified path to your license file.

## Troubleshooting

New keywords are available or output has been changed for the following utility commands:

- ADAOPR ... DISPLAY=TCPCONNECTIONS

- ADAOPR ... TCPDISCONNECT=<ID>

- ADAOPR ... DISPLAY=STATIC_PARAMETERS

The Adabas Client program `getdbinfo` has been extended to print not only Adabas version and operating system information, but also an Adabas subcode in case of problems as well as the established communication type.

Output in case of problems:

    adabas@server1> getdbinfo 199

       get platform and version info of database 199

    Database 199 .. ** Response code 148 (subcode=1034) from ADABAS for Open call

    adabas@server1> getdbinfo 206

       get platform and version info of database 206

    Database 206 .. ** Response code 148 (subcode=1038) from ADABAS for Open call, adatcp access to 'server1.aan.xy.sag:63206'

Output in case of success:

    adabas@server1> getdbinfo 199

       get platform and version info of database 199

    Database 199 is active, V6.7.0.0, Platform = 20, opsys=Linux/Windows, classic local access

    adabas@server1> getdbinfo 206

       get platform and version info of database 206

    Database 206  is active, V6.7.0.0, Platform = 20, opsys=Linux/Windows, adatcp access to 'server1.aan.xy.sag:63206'

## Nucleus error message

    %ADANUC-F-ADATCPINIFAIL, ADATCP initialization failed: creation of receiver thread(s) failed

or

    %ADANUC-F-ADATCPINIFAIL, ADATCP initialization failed: creation of listen thread failed

If there is no other information given in the log file, it is usually a timing problem. The threads must start within 10 seconds. If one of them does not, because the host is too busy, the nucleus is stopped. If a more specific error message is logged, the thread was started but another problem occurred.

#### Example:

    %ADANUC-F-ADATCPINIFAIL, ADATCP initialization failed: cannot bind listen socket to port 62111 (Address already in use)

    %ADANUC-F-ADATCPINIFAIL, ADATCP initialization failed: creation of listen thread failed

## Connectivity Problems on Linux

When many clients start in parallel, this might lead to connection problems. In this case, check the kernel parameter `net.core.somaxconn` and increase the value to be equal to the number of clients started in parallel. After changing the value, you must restart the database(s).

#### Root User Example:

    adabas@server1> sysctl net.core.somaxconn
    net.core.somaxconn = 128
    adabas@server1> sysctl -w net.core.somaxconn=2048

#### Root User Example to Make the Setting Permanent:

    adabas@server1> sysctl -w net.core.somaxconn=2048 >> /etc/sysctl.conf

## Performance

Interaction of NT and TCPRECEIVER parameter:

After analyzing our heavy load test results, we recommend to maximum increase/decrease the value for "number of receiver threads" (TCPRECEIVER) by a factor of 2 in comparison to the "number of threads be established for the Adabas session" (NT).

    NT/2 <= TCPRECEIVER <= 2*NT

## Use Cases - FAQ

- Q: Is it possible to get information about the client communication type without checking the configuration file?

  A: Yes, the Adabas Client program `getdbinfo` has been extended to provide such information.

- Q: Different applications on one node need to be able to access the same database by either TCP or IPC. How can this been achieved?

  A: Set the required TCP parameters like `ADATCP` and `PORTNUMBER` in the DBINI file of your database and start it. Use an Adabas Client environment for the first application without changing the configuration file to use classic IPC communication. Use an additional Adabas Client environment for the application which should use TCP and add the necessary connection information in the configuration file or use the `ADA_DB_MAPPING` environment variable with a prepared configuration file before starting this application.

- Q: Customer has hundreds of clients and wants to migrate to TCP step by step. Do you have any recommendations?

  A: To avoid copying a prepared configuration file or adapt the existing dbmapping.txt file in the Adabas Client (ACL) config folder, we recommend to set the environment variable `ADA_DB_MAPPING` and use a prepared configuration file on a shared folder for all clients.

- Q: After trying out ADATCP, how can I switch back to the classic IPC communication method?

  A: Delete the database entry from the dbmapping.txt file. The database might still be ADATCP enabled, but all clients are using the classic IPC access method from now on.

- Q: Is it possible to use SSL communication without a client certificate and key?

  A: Client certificates are not necessary if the verification level of the server (`SSLVERIFY`) is set to `0`. We do not recommend to use such a configuration in a production environment, but nevertheless the communication will be encrypted.

- Q: How to disallow non-encrypted connections via ADATCP?

  A: Enable the TCP/IP receiver (`ADATCP` parameter), define `SSLPORTNUMBER` and set `PORTNUMBER=0` in the DBnnn.INI file.

- Q: Is there a tool available to encrypt the `SSLPASSWORD` (server parameter) or `PASSWORD` (client parameter) value stored in a file?

  A: No, but we recommend to give your configuration a try in a test environment. After the first access, the value is encrypted and written to a file which must have write access permissions. Copy the encrypted version of the file with read-only access permissions to your production environment.

## Known Restrictions

ADATCP nucleus parameter values can neither be added nor updated while the database is up.

### On this page

- Basic Communication
- Encrypted Communication (TLS/SSL)
- Internal Architecture
- Licensing
- Troubleshooting
- Nucleus error message
- Connectivity Problems on Linux
- Performance
- Use Cases - FAQ
- Known Restrictions