Product Documentation

FairCom RTG COBOL Edition User's Guide

Previous Topic

Next Topic

FairCom RTG Server Set-up

This section explains how to install the FairCom RTG Server on your operating system. Certain configuration issues pertaining to the runtime and shared memory communication are explained here. The chapter titled FairCom RTG Configuration dives into detail about the many configuration options provided by FairCom RTG.

In This Section

FairCom RTG for Windows

FairCom RTG for Unix/Linux

Shared Memory for FairCom RTG

Runtime Configuration

Configure the FairCom RTG Server

Connecting to the FairCom RTG Server - RM/COBOL

Secure SSL Communication

Previous Topic

Next Topic

FairCom RTG for Windows

The FairCom RTG installer for Windows creates a Microsoft Windows service that automatically starts the database engine at Windows startup. This allows for seamless and unattended operation. Use the standard Windows service control panels to start/stop and configure various service options.

VSS Backup - FairCom RTG for Windows supports the Windows Volume Shadow Copy Service (VSS) Writer for backups. This support is supplied as a dynamic link library (c-treeACEVSSWriter.dll) that allows Windows VSS Backup to be used. See VSS Integration in the Technical White Papers on the FairCom website.

Previous Topic

Next Topic

FairCom RTG for Unix/Linux

The FairCom RTG tar archive for Unix/Linux contains a ready-to-run FairCom DB database engine:

cd /FairCom/Vx.x.x.RTG/<platform>/server/

./ctreesql

Feel free to include it along with your /etc/init.d startup scripts for fully unattended operation. Consult your local system administrator for details about specific machine configurations.

Previous Topic

Next Topic

Shared Memory for FairCom RTG

FairCom RTG supports the shared memory communication protocol between clients and servers residing on the same machine. Shared memory communication generally provides much better performance for locally running applications.

Note: Shared memory support does not include Linux Kernels 2.4 or Mac OS X systems.

The FairCom DB shared memory communication protocol creates a file used by clients to find the shared memory identifier for its shared memory logon region, and creates a Unix domain socket as a file for initial communication between a client and server.

Configuration

Include the following server configuration in ctsrvr.cfg to enable this support:

COMM_PROTOCOL FSHAREMM

FairCom DB creates the directory /tmp/ctreedbs and the file /tmp/ctreedbs/<servername>.logon. This file name is determined by the value specified with the SERVER_NAME configuration option. This file contains an identifier of a shared memory region used for clients to connect. The following configuration option allows this directory to be directly specified:

SHMEM_DIRECTORY <directory_name>

FairCom DB must have sufficient read, write, create, and delete permissions with this directory. The following server keyword sets the shared memory resource permissions:

SHMEM_PERMISSIONS <permissions>

The default is 660. Caution: A setting of 666 allows access to FairCom DB by any user account, permitting any user to attach to a shared memory segment and read or write to it, which may cause a security breach.

By default, a client application must belong to the server owner’s primary group to use shared memory. This is configurable with the SHMEM_GROUP keyword.

SHMEM_GROUP <group>

Possible errors indicating problems:

FSHAREMM: Could not get group ID for group <group> for shared memory

FSHAREMM: Failed to set group for LQMSG shared memory region: X

Client Configuration

On Unix/Linux system it is necessary to set the CTREE_SHMEM_DIRECTORY environment variable. This allows the directory to be dynamically overridden without having to recompile the client code.

Latest Performance Improvements in V3

The Unix/Linux shared memory communication protocol has been changed to improve performance by improving the internal spin operation to be more efficient, especially for relatively short database operations.

Compatibility Note: It is important to recompile the client due to this shared memory change. A server that uses this modified shared memory protocol only supports shared memory connections from clients that also use this new enhanced protocol. If an older client (pre-V11.6) attempts to connect, it will fail with error SHMC_ERR (841) and the server will log the following message to CTSTATUS.FCS:
Fri May 26 12:13:07 2017
- User# 00016 FSHAREMM: The client's shared memory version (3) is not compatible with the server's shared memory version (4)

In This Section

Shared Memory Resource Considerations

Previous Topic

Next Topic

Shared Memory Resource Considerations

An established shared memory connection can fail and be terminated in case of low shared memory resources.

Please consider the following case:

One of the peers of a shared memory connection may need to require a larger shared memory region (for example, it may need to exchange a message larger than the current shared memory region). The client or server can make a system call to allocate a new shared memory region. The call could fail due to a system limit. In this case, the connection can fail and be terminated.

It is recommended to increase the system's shared memory limits to avoid unexpected shared memory connections terminations.

This is a sample message that you might see in CTSTATUS.FCS if you are running low on memory:

User# 00017 FSHAREMM: Failed to create a semaphore set: 28

For more information about shared memory, see Shared Memory Client-Server Communication for Unix/Linux in the FairCom Server Administrator's Guide.

Previous Topic

Next Topic

Runtime Configuration

ACUCOBOL-GT allows a program to interface with more than one external file system in the same program.

To specify the indexed file system that the program will use, you must set the DEFAULT_HOST configuration variable. For example, to define a file system for use with a particular file, you set the filename_HOST configuration variable.

For an introduction to ACUCOBOL-GT runtime configuration variables and the configuration file, see section 2.7, "Runtime Configuration," in Book 1 of the ACUCOBOL-GT documentation set.

Micro Focus COBOL can be configured to use external file handlers in two different ways: you can insert the CALLFH directive inside your COBOL program and recompile it, or you can use dynamic redirection. Please refer to your Micro Focus COBOL documentation.

Previous Topic

Next Topic

Configure the FairCom RTG Server

Note: The FairCom RTG server (a specialized version of FairCom DB) is configured separately from the FairCom RTG client. Client configuration is discussed in the next section, FairCom RTG Configuration.

ctreeRTG configuration

For information about configuring the FairCom RTG Client, see the FairCom RTG Configuration chapter in this manual.

For information about configuring the FairCom RTG Server, refer to the Configuring the FairCom DB Server chapter of the FairCom DB Server Administrator's Guide.

 
The FairCom RTG Server has a multitude of options for configuring many of the various database subsystems including:

  • Data and index cache control
  • Transaction logging features
  • Memory files
  • Backup scripts
  • Diagnostic options
  • Operational statistics logging

Unless otherwise instructed, the FairCom RTG Server starts with default settings for all configurable parameters. The FairCom RTG Server takes configuration instructions from a configuration file, ctsrvr.cfg, placed in the FairCom RTG Server directory. When the FairCom RTG Server finds a ctsrvr.cfg file, it uses all the specified configuration values.

FairCom RTG is delivered with appropriate settings for the server. If you want to change these settings, the ctsrvr.cfg file can be edited using the FairCom DB Config Manager, located in: FairCom\vX.X.X.RTG\<win*>\Tools\gui\c-treeConfigManager.exe (where FairCom\vX.X.X.RTG\<win*>\ is the installation directory) for Windows installations, or simply edit this file using any text editor on Unix/Linux systems.

For more information, refer to Configuring the FairCom DB Server in the FairCom DB Server Administrator's Guide.

Previous Topic

Next Topic

Connecting to the FairCom RTG Server - RM/COBOL

The following table indicates when the application connects to, and disconnects from, the FairCom RTG Server:

 

Connects when...

Connects to...

Exceptions

Disconnect when...

isCOBOL

COBOL program starts

All instances defined in the configuration file

Instances with connect="no" are connected on first file-system operation on files belonging to the instance

COBOL program exits

ACUCOBOL

First file-system operation (typically an OPEN)

Only the instance owning the file affected by the file-system operation

Instances with connect="yes" are connected when program starts

COBOL program exits

Micro Focus
(and other ExtFH-based programs)

First file-system operation (typically an OPEN)

Instance owning the file affected by the file-system operation and any instances with connect="yes"

 

Any file-system operation after which no files or transactions are open in any instances

COBOL-IT
(compiled with ‑fctree)

First file-system operation (typically an OPEN)

Only the instance owning the file affected by the file-system operation

Instances with connect="yes" are connected when the program starts

COBOL program exits

COBOL-IT
(compiled with
‑use‑extfh)

First file-system operation (typically an OPEN)

Instance owning the file affected by the file-system operation and any instances with connect="yes"

 

Any file system operation after which no files or transactions are open in any instances

For an explanation of <instance>, the connect attribute, and other aspects of the configuration file, see Configuration File Elements.

Previous Topic

Next Topic

Secure SSL Communication

FairCom RTG Supports TLS/SSL Protecting Data in Transit for Network Communication

FairCom RTG applications can secure data in transit between c-tree network clients and FairCom DB Servers. Transport Layer Security (TLS, also commonly referred to as its predecessor SSL, Secure Sockets Layer) is a cryptographic protocol designed for secure network communications using public key cryptography for authentication of the communicating party. Symmetric cryptography is used to encrypt transmitted data over the wire. FairCom DB TLS relies on OpenSSL toolkit support (version 1.0.2g) and implements TLS protocol V1.2 exclusively, as earlier versions of TLS (and predecessor SSL) protocols contain known and exploited vulnerabilities. FairCom DB supports TLS via TCP/IP communications protocols (IPv4 and IPv6). (For more about TLS, see SSL/TLS in Wikipedia.)

Two modes of TLS connections are available: basic and peer authenticated. Basic TLS connections are encrypted using only a server-side certificate; there is no local certificate requirement for a client. This makes deployment and management of secured connections easy.

TLS Certificates

It is the server administrator’s responsibility to ensure a correct and valid certificate pair, as well as proper configuration of allowed TLS connections.

Creation and management of TLS certificates, as well as use of a Certification Authority (CA), is beyond the scope of this document. Consult OpenSSL and other TLS supporting documentation and be sure you firmly grasp all details regarding use of TLS for network security before deploying.

Server certificates may be created and provided as two separate files: a certificate and a key. They can also be combined into a single file. There is no required file naming convention. Certificate files are usually created and/or provided as Base64 encoded X.509 certificate files and denoted with a .pem extension (Privacy Enhanced Mail). They can be identified with this set of surrounding identifiers within the file:

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

The private key is likewise identified:

-----BEGIN PRIVATE KEY-----

-----END PRIVATE KEY-----

The private key is often included in the same certificate file or as a separate .key file.

A certificate key can be optionally passphrase protected. However, this then requires the passphrase to be presented at server startup. FairCom DB key store files provide this ability.

Always securely maintain key files. Store key files only in permissions protected server areas and never distribute.

Peer Authentication - TLS Connection with Server Certificate Validation

By default, a c-tree client requires a PEM file containing the server public certificate—ONLY the public certificate, not the server private key.

Important: The server private key should be securely maintained only at the FairCom Server location at all times.

By default, c-tree client libraries use the file ctsrvr.pem in the client process' working directory when connecting.

When the client does not use a server certificate, the connection is encrypted, but there is no guarantee that the client is connected to that specific server. This implies that a "man in the middle" attack could be possible.

Server-Side Configuration

To enable TLS (SSL), add a SUBSYSTEM COMM_PROTOCOL SSL section to ctsrvr.cfg containing your specified TLS configuration options. Supported options include:

  • SERVER_CERTIFICATE_FILE (required) - This is the name of a PEM-encoded certificate file containing FairCom DB Server's certificate. It can also optionally include the private key. The server certificate can be self-signed.
  • SERVER_PRIVATE_KEY_FILE (optional) - If the private key is in a different file than the certificate, use this option to indicate the name of the file containing the private key. If this option is not specified, the private key is expected to be found in the file whose name is specified by the SERVER_CERTIFICATE_FILE option.
  • SERVER_ENCRYPTED_STORE_FILE (optional) - If the private key is encrypted, use the ctcpvf utility to create an encrypted store file containing the passphrase used to decrypt the private key and specify the name of the encrypted store file with this option.
  • SSL_CONNECTIONS_ONLY (optional) - Default: NO. If this option is specified with a value of YES, only TCP/IP connections that use SSL are permitted to connect to FairCom DB Server. Otherwise, both unencrypted and SSL-enabled TCP/IP connections are allowed.
  • SSL_CIPHERS (optional) - Default: AES256-SHA256:AES256-GCM-SHA38:DHE-RSA-AES256-SHA256
    If this option is specified, it sets the encryption ciphers that are allowed to be used for encrypting the SSL connection. The default specifies full AES 256-bit encryption. Ciphers are separated by a colon, (":"). An exclamation point ("!") symbol explicitly disables a cipher. @STRENGTH sorts the list in order of encryption algorithm key length. For more information, see https://www.openssl.org/.

Standard c-tree TCP/IP ports are used for connections regardless of TLS configuration. That is, a single ISAM port will handle both TLS encrypted and non-encrypted connections, and likewise for the SQL port. There is no need for separate port configurations.

Client-Side Configuration

TLS (SSL) communication support is enabled in FairCom RTG through two new attributes to the <instance> configuration element.

  • <instance ssl=""> specifies if a secure connection should be used to connect to FairCom RTG server. It accepts "yes" or "no" as possible values and defaults to "no".
  • <instance sslcert=""> specifies a server public certificate when server certificate validation enabled.

Example

<config>

<instance ssl="yes" sslcert="ctsrvr.pem" server="FAIRCOMS@localhost" user="ADMIN" password="ADMIN" connect="no" versioncheck="no">

...

</instance>

</config>

OpenSSL libraries are statically linked to the server binary requiring two shared libraries:

  • libcrypto.so.1.0.0
  • libssl.so.1.0.0

Current TLS support is OpenSSL 1.0.2

Support for TLS / SSL (1.2) is available for Windows, Linux, and Mac OS X. Others operating systems considered upon request.

TOCIndex