|
|
|
This section explains how to install the c-treeRTG Server on your operating system. Certain configuration issues pertaining to the runtime and shared memory communication are explained here. The chapter titled c-treeRTG Configuration dives into detail about the many configuration options provided by c-treeRTG.
|
|
|
The c-treeRTG 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 - c-treeRTG 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.
|
|
|
The c-treeRTG 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.
|
|
|
c-treeRTG 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)
|
|
|
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.
|
|
|
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.
|
|
|
Note: The c-treeRTG server (a specialized version of FairCom DB) is configured separately from the c-treeRTG client. Client configuration is discussed in the next section, c-treeRTG Configuration.
For information about configuring the c-treeRTG Client, see the c-treeRTG Configuration chapter in this manual. |
For information about configuring the c-treeRTG Server, refer to the Configuring the FairCom DB Server chapter of the FairCom DB Server Administrator's Guide. |
The c-treeRTG Server has a multitude of options for configuring many of the various database subsystems including:
Unless otherwise instructed, the c-treeRTG Server starts with default settings for all configurable parameters. The c-treeRTG Server takes configuration instructions from a configuration file, ctsrvr.cfg, placed in the c-treeRTG Server directory. When the c-treeRTG Server finds a ctsrvr.cfg file, it uses all the specified configuration values.
c-treeRTG 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.
|
|
|
The following table indicates when the application connects to, and disconnects from, the c-treeRTG 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 |
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 |
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 |
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.
|
|
|
c-treeRTG Supports TLS/SSL Protecting Data in Transit for Network Communication
c-treeRTG 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:
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 c-treeRTG through two new attributes to the <instance> configuration element.
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:
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.
