Configuring FairCom DB

Unless otherwise instructed, a FairCom Server starts using default settings for all configurable parameters. The FairCom Server takes configuration instructions from a raw text configuration file, ctsrvr.cfg, placed in the <faircom>/config directory. When the FairCom Server finds this file, it uses all the specified configuration values.

Note: Your vendor may also provide a settings file that is not user-configurable, ctsrvr.set.

Note: Keep in mind that the ctsrvr.cfg file needs to be saved in a Unix text file format. Failure to do so may cause an error to occur.

The FairCom Server allows keywords to be entered from the command-line when it is being started. For example, the following shows setting the Index and Data cache sizes to 1 million bytes each:

./faircom IDX_MEMORY 1000000 DAT_MEMORY 1000000

The command-line entries take precedence over any settings in ctsrvr.set, which takes precedence over ctsrvr.cfg.

Examples of reasons the FairCom Server may need to be reconfigured are:

• Communications protocols (for transmitting information to and from the FairCom Server): The default communications support for the FairCom Server is TCP/IP. Implementing other communication techniques requires a FairCom Server configuration file, and the appropriate COMM_PROTOCOL keyword.
• Memory allocations: To change the maximum amount of memory all users, or any given user, will be allocated—and to specify whether this maximum is an absolute rule or only a guideline.
• Backup files: To specify the FairCom Server should look for a dynamic dump script and follow instructions in that script to back up specified files.

FairCom DB Configuration File

To locally configure FairCom DB with a configuration file:

1. Create an ASCII file that is a list of configuration parameters using the file format, configuration keywords and values described in the Configuration Options section.
2. Name this file ctsrvr.cfg and place in the appropriate directory. By default, FairCom DB looks in the config directory, then in its executing directory for a file of this name when it starts.

Tip: The default file name and path can be changed with an environment variable and a command-line keyword, as described in Advanced Configuration Keywords.

1. Start the FairCom Server.

Note: FairCom DB does not explicitly require a configuration file. If one is not present, FairCom DB starts with default values. Frequently, these values will not provide an optimal experience with the application.

Configuration File Format

The format of the FairCom Server configuration file is as follows:

• File name: ctsrvr.cfg
• (see Location note below) Default location of file: <faircom>/config/ctsrvr.cfg

falling back to:
<faircom>/server/config/ctsrvr.cfg

and finally to:
<faircom>/server/ctsrvr.cfg

• File contents: An ASCII text file, consisting of a series of pairs of keyword names and keyword values, separated by one or more spaces (or a line feed). Keyword names are not case sensitive, but some values may be file names that may be case sensitive in certain environments, e.g., the value for COMM_PROTOCOL. Keyword values are strings of characters, without quotes around them, and without commas, decimal points, or indications of units (e.g., 1,000 bytes is entered as 1000). If a keyword is omitted from the configuration file, its default value is used.

For ease of reading and changing, we suggest using a format similar to the following configuration script file:

FILES        2000

CONNECTIONS  15

IDX_MEMORY   500000

DAT_MEMORY   500000

This configuration file specifies the following changes from default settings:

• FILES: Increase the maximum number of files from 1000 to 2000.
• CONNECTIONS: Set the maximum number of concurrent connections to the FairCom Server to 15.
• IDX_MEMORY and DAT_MEMORY: Increase the memory allocated to index cache and data cache, from 225,000 bytes to 500,000 bytes.

Note: Multiple configuration files may be used. For example, create different configuration files for different dynamic dump schedules, or for different communication protocols. Be sure the appropriate configuration file is found by the FairCom Server when starting. Consider specifying the correct configuration via an environment variable, or passing on command line.

Comments in the Configuration File

Individual lines in ctsrvr.cfg can be commented out with a semi-colon (;) in front of a line. Example:

;COMM_PROTOCOL F_TCPIP

In V11.5 and later, FairCom Server supports commenting out a SUBSYSTEM block in ctsrvr.cfg by commenting out just the line containing the SUBSYSTEM keyword. Prior to this enhancement, each line of the SUBSYSTEM block had to be commented out. Now an entire SUBSYSTEM block can be commented as shown below:

;SUBSYSTEM EVENT DISK_FULL_ACTION {

    volume      VOLUME

    limit       LIMIT

    run         EXE [OPTIONS]

    freq        FREQUENCY

    maxruntime  MAXRUNTIME

}

Location

The configuration file can be placed in a directory of your choosing by using any of these procedures:

• Passing a command-line parameter, e.g.:
  ctsrvr CTSRVR_CFG my_path/my_config_filename
• Setting the CTSRVR_CFG environment variable
• Calling ctdbSetConfigurationFile() before calling ctThrdInit() for embedded server models (not supported on FairCom RTG)

All Plug-In Settings and Config Files in config Directory by Default

By default, all of the current plug-ins' settings files and configuration are loaded from the config directory. This applies to Replication Manager, web server, ThingWorx, OPC, and Automatic System Time/TimeStamp) settings files.

Best Practice: User-created plug-ins do not have to follow this practice, because they can be written to load their settings from wherever you want. However, for consistency and simplicity of administration, it is strongly recommended as a best practice to place all settings files in the config directory.

Password Security Options (Commented Out) in Default Server Configuration File

Password security options have been added to the default ctsrvr.cfg file. These options are commented such they do not affect your configuration. They are easily enabled by removing the semicolon (";") at the beginning of the initial SUBSYSYEM line:

;SUBSYSTEM SECURITY PASSWORD {

  MINIMUM_LENGTH   8

REQUIRED_CLASSES 3

EXPIRE_IN_DAYS   180

}

Configuration Flexibility with Environment Variables

FairCom DB allows many of its configuration options to include an environment variable name that will be substituted with its value when the configuration file is read. For example, on Windows an administrator might want to set the FairCom DB data directory based on the PROGRAMDATA environment variable:

LOCAL_DIRECTORY %PROGRAMDATA%\FairCom\V*\bin\ace\sql\data

In this example, %PROGRAMDATA% is replaced with the value of the PROGRAMDATA environment variable (according to the environment variables that are defined in the logon session in which FairCom DB is running).

If you want to specify a literal % sign that is not treated as part of an environment variable name, use %%. For example, if you want to specify a value of ABC%DEF, specify it as ABC%%DEF. A literal % sign cannot be used in an environment variable name; it always signifies the end of the environment variable name. For example, %MY%%VAR% is treated as two environment variables, MY and VAR, rather than one variable named MY%VAR.

The following configuration options support this feature:

• ADMIN_MIRROR
• BROADCAST_DATA 
• CTSRVR_CFG
• DISK_FULL_ACTION
• DISK_FULL_VOLUME
• DYNAMIC_DUMP 
• KEY_EXCHANGE_PARAMS 
• LOCAL_DIRECTORY
• LOG_EVEN
• LOG_EVEN_MIRROR
• LOG_ODD
• LOG_ODD_MIRROR
• MASTER_KEY_FILE
• MIRROR_DIRECTORY
• NULL_STRING
• PREIMAGE_FILE
• SERVER_DIRECTORY (deprecated)
• SHMEM_DIRECTORY
• SIGNAL_DOWN
• SIGNAL_MIRROR_EVENT 
• SIGNAL_READY
• SIGNAL_USER_DOWN 
• SIGNAL_USER_READY 
• SQL_LOGFILE
• START_EVEN
• START_EVEN_MIRROR
• START_ODD
• START_ODD_MIRROR
• TMPNAME_PATH

FairCom DB Standard Wildcards

The FairCom DB standard wildcard pattern matching variables apply to the FairCom Server keywords that operate with files names, such as MEMORY_FILES, KEEPOPEN_LIST, REPLICATE, the !FILES command within the dynamic dump script, and so on. The available list of wildcards is:

* - Multi-character match

? - Single-character match

^ - Negation (must be first character)

For example, consider this list of files:

KEEPOPEN_LIST file1.dat

KEEPOPEN_LIST file2.dat

KEEPOPEN_LIST file30.dat

An asterisk can be used as a wildcard character to match file1.dat, file2.dat, and file30.dat (or fileanythingelse.dat):

KEEPOPEN_LIST file*.dat

A ? can be used to match a single character, which will match file1.dat and file2.dat but not file30.dat:

KEEPOPEN_LIST file?.dat

NOTE: Wildcard matching does not recognize symlinked folders. For example, if the path "myapp/dx30" has a symlink that renames it to "myapp/dx", a REPLICATE wildcard of “myapp/dx/data*” does not match files in “myapp/dx30” because only the actual file open path is matched.

Scaling Factors for Configuration Keyword Values

The FairCom Server’s data and index cache configuration options support specifying a scaling factor used when interpreting cache memory sizes. The supported scaling factors are:

• KB: interpret the specified value as a number of kilobytes.
• MB: interpret the specified value as a number of megabytes.
• GB: interpret the specified value as a number of gigabytes.

Example

DAT_MEMORY 100 MB

The following configuration keywords support scaling factors along with their limits.

The following keyword was not changed to support specifying a scaling factor:

XTDKSEG_SRC_SIZE

Note: An operating system might impose a lower limit on the amount of memory available to a process than the configuration option limits that the FairCom Server supports

Alternative Configuration Methods

FairCom Server offers several methods of setting configuration options. This section explains those options.

Settings File

Your vendor may supply an encrypted settings file, ctsrvr.set, that is not user configurable. Configuration options in this file are critical to the vendor’s application, and should not be deleted. It is possible for the vendor to configure FairCom DB to require this file for startup. Review your vendor’s documentation for guidance on this settings file.

Environment Variables

By default, FairCom DB looks for Server configuration, settings, and license files (named ctsrvr.cfg, ctsrvr.set settings file, and ctsrvr*.lic) in the following locations relative to the working directory of the FairCom DB process:

1. The directory ../config

2. The directory ./config

3. The current directory

FairCom DB supports specifying the location and file name of the Server configuration, settings, and license files using the following environment variables:

• Configuration files: FCSRVR_CFG_DIR or FCSRVR_CFG1
• Settings files: FCSRVR_SET
• License files: FCSRVR_LIC

This feature allows an administrator to specify alternate configuration for specialized purposes.

FCSRVR_CFG_DIR sets the directory where the server will look for its configuration files.

FCSRVR_CFG sets the name of the server configuration file (ctsrvr.cfg).

The environment variables (FCSRVR_CFG_DIR, FCSRVR_CFG, FCSRVR_SET, and FCSRVR_LIC) override the default names and locations when FairCom DB is launched. The environment variable should contain a complete file name for the configuration file.

Example

The environment variables FCSRVR_CFG_DIR and FCSRVR_CFG affect the search for the main configuration file in the following ways:

1. When FCSRVR_CFG_DIR is specified and FCSRVR_CFG is not specified, FairComDB uses the file named ctsrvr.cfg in the directory specified by the FCSRVR_CFG_DIR environment variable.

For example, if FCSRVR_CFG_DIR is set to "../../myconfigdir", FairComDB uses the configuration file named "../../myconfigdir/ctsrvr.cfg".

2. When both FCSRVR_CFG_DIR and FCSRVR_CFG are specified, FairComDB uses the file having the name specified by the FCSRVR_CFG environment variable.

For example, if FCSRVR_CFG_DIR is set to "../../myconfigdir" and FCSRVR_CFG is set to "myconfigdir/ctsrvr.cfg", FairCom DB uses the configuration file named "myconfigdir/ctsrvr.cfg".

To direct FairCom DB to use .\work\my_config.001 as its configuration file on a Windows platform, define FCSRVR_CFG as:

set FCSRVR_CFG=.\work\my_config.001

Likewise, FCSRVR_SET overrides the name and location of the Server Settings file:

(Unix example)

set FCSRVR_SET=/usr/production/my_set.abc

export FCSRVR_SET

FCSRVR_LIC overrides the default name and location of the FairCom Server license file. For example, to use .\myFolder\ctsrvr12345678.lic as the license file:

set FCSRVR_LIC=.\myFolder\ctsrvr12345678.lic

Command-Line Parameters

FairCom DB accepts configuration information from the command-line in addition to the settings and configuration files. Configuration keywords and values listed as command-line arguments take affect after an encrypted settings file, ctsrvr.set, if any, and before the standard configuration file, ctsrvr.cfg. A command-line entry cannot override a settings file entry, and a configuration file entry cannot override a command-line entry (or a settings entry). For more information on the encrypted settings file (ctsrvr.set), see additional documentation included in the Security section of the Knowledgebase in the Customer Portal.

All valid configuration file keywords are supported and may be listed on the command line followed by an appropriate value. No special switch symbols or syntax is required. Simply enter each keyword followed by a value as follows:

faircom FUNCTION_MONITOR YES LOCAL_DIRECTORY C:\MYDATA\

or

ctsrvr FUNCTION_MONITOR YES LOCAL_DIRECTORY C:\MYDATA\

To specify the name and location of your server configuration file, ctsrvr.cfg, when launching the FairCom Server from the command-line, use the command-line keyword CTSRVR_CFG followed by a fully qualified configuration file name as follows:

faircom CTSRVR_CFG C:\myServer\ctsrvr.cfg

faircom CTSRVR_CFG  /usr/myserver/myinfo.cfg

or

ctsrvr CTSRVR_CFG C:\myServer\ctsrvr.cfg

ctsrvr CTSRVR_CFG  /usr/myserver/myinfo.cfg

The CTSRVR_CFG command line keyword is typically used when running two servers on the same machine, described elsewhere.

Note: The FCSRVR_CFG environment variable supersedes the CTSRVR_CFG keyword, so the file specified in the environment variable will always be the file used.

After successfully opening its main configuration file, FairCom DB uses the location of the main configuration file as the location of its other configuration files.

Here is a list of the other configuration files that FairCom DB uses:

ctagent.json - Configuration file for the ctagent plugin

ctopc.json - Configuration file for the ctopc plugin

ctthingworx.json - Configuration file for the ctthingworx plugin

cttimestamp.json - Configuration file for the cttimestamp plugin

dbnotifyconnections.json - Configuration file for the fcmqclient plugin. The mqclient tables folder named dbnotify is located as a subdirectory of the location of this configuration file

faircomssl.cnf - Configuration file for OpenSSL

fcmemgrid.json - Configuration file for the fcmemgrid plugin

services.json - Configuration file for the cthttpd plugin