Skip to main content

Configure Linux (Unix)

Configure FairCom product settings on Linux-style systems

The default operating system settings on Linux-style operating systems, such as Unix, Linux, Raspbian, Android IoT, AIX, and Solaris, are adequate for running a typical FairCom server. However, you can change the operating system limits listed below to customize the server to meet larger (or smaller) needs. For example, the number of file descriptors must be large enough to accommodate the number of files the FairCom server will access, which can be larger than the operating system's default setting. Please be sure the limits listed below are sized appropriately for your installation.

ulimit

Verify that your ulimit settings are set according to the following specifications:

  • File descriptors should be set to a number greater than:

    FILES + CONNECTIONS + c-tree internal files (11) + SQL internal files

    • FILES = The FILES keyword set in ctsrvr.cfg.

    • CONNECTIONS = The CONNECTIONS keyword setting in ctsrvr.cfg.

    • "c-tree internal files" = (11) The internal files opened immediately by the FairCom server on startup, including CTSTATUS.FCSFAIRCOM.FCS, ctsrvr.cfg, and so forth.

    • "SQL internal files" = At least 1 per SQL connection.

  • The maximum number of user processes should be greater than:

    CONNECTIONS + ctree internal users (25) + Java internal users (approximately 20)

    • CONNECTIONS = The CONNECTIONS keyword setting in ctsrvr.cfg.

    • "c-tree internal users" = (25) The internal operating system threads.

    • "Java internal users" = (20) The approximate number of internal operating system threads consumed by the Java Virtual Machine (JVM) layer.

  • Memory limits (stackmax memoryvirtual memory):

    unlimited

  • Core size:

    unlimited or larger than memory limits

  • File size:

    unlimited

Kernel limits

These are system-wide limits, so you must consider the requirements of all processes system-wide.

  • The semaphore limit for c-tree shared memory is:

    kernel.sem (argument 4) = 2 + shared memory CONNECTIONS

    The maximum shared memory CONNECTIONS is 1022 if no other processes are using shared memory on the system.

    kernel.sem = 250 32000 100 1024

  • The shared memory segments limit is:

    kernel.shmmni = 2 + shared memory CONNECTIONS

    The maximum shared memory CONNECTIONS is 1022 if no other processes are using shared memory on the system.

    kernel.shmmni = 1024

Configure FairCom product settings in Unix-based systems

configureunixAIXSolarisLinuxconfigure settingsKernelunix configuration

Configure shared memory communications on Linux (Unix)

FairCom's ISAM, CTDB, and SQL APIs to communicate with the FairCom server using shared memory and TCP/IP. FairCom's client libraries for these APIs automatically pick the best protocol.

Applications and FairCom servers can reside on the same computer. When they do, ISAM, CTDB, and SQL APIs (including JDBC and ADO.NET) automatically use shared memory communications because shared memory is faster than TCP/IP. When applications and FairCom servers run on different computers, communications automatically occur over TCP/IP.

FairCom's JSON Action APIs communicate using TCP/IP protocols, including HTTP and WebSocket.

By default, the following line in <faircom>/config/ctsrvr.cfg enables shared memory communications:

COMM_PROTOCOL FSHAREMM

Note

The COMM_PROTOCOL option specifies the protocol used for ISAM connections. By default, local SQL connections use shared memory unless the SQL_OPTION NO_SHARED_MEMORY keyword is specified. For more information about the communication protocol for SQL connections, see the FairCom DB SQL server operations and utilities guide.

you can modify the following shared memory settings as needed.

System tools

The <faircom> ipcs utility is useful for listing the shared memory regions and semaphore sets that currently exist on a system. ipcs can also be used to remove shared memory regions and semaphore sets. Under normal circumstances, the FairCom server removes shared memory regions and semaphore sets for connections that have been closed. However, if the FairCom process terminates abnormally, it may be necessary to manually remove the shared memory regions and semaphore sets belonging to this process.

The Linux (Unix) version logs a message when shared memory cannot create a semaphore or segment.

On Linux (Unix) systems, the FairCom server logs a message to CTSTATUS.FCS when it fails to create a system semaphore or shared memory segment due to a resource limit setting. This helps the server administrator understand the cause of the error. Example message:

Fri Aug 22 15:14:44 2014

   User# 00013  FSHAREMM: Failed to create system semaphore: check system semaphore limits such as SEMMNI

Fri Aug 22 15:14:44 2014

   User# 00013  NewUser: Unable to create an instance of a named pipe

FairCom ISAM and SQL ports are independent of each other. In general, there is a shared memory connection protocol enabled for each, in addition to TCP/IP ports. Keep in mind, that's a total of four connection protocols, with configuration options for each.

Possible SQL shared memory connection errors can appear such as the following. Analyze and correct these as you would for the ISAM errors previously mentioned as the same parameters should be examined.

User# 00012   sqlshmlisten: shared memory protocol initialization failed:  1

User# 00012   sqlshmlisten: shared memory protocol accept failed:  2

User# 00012   sqlshmlisten: Failed to get shared memory environment: XX

Named pipe creation failed with error ERROR_PIPE_BUSY. The operation will be retried

User# 00012   sqlshmlisten: shared memory protocol listen failed:  4

Failed permissions on the temporary directory needed.

User# 00012   SQLSHAREMM: Failed to open /tmp/ctreedbs/CTSQL_6597 for shared memory: 13

When more than one FairCom server was run on a Unix system, the shared memory keys used by different servers could have the same value, which prevented connections to the servers. In addition, it was possible for unrelated applications to collide with default keys generated by FairCom servers.

To address this key collision, it is possible for an administrator to specify specific shared memory keys for ISAM and SQL shared memory communication protocols ensuring the keys do not match existing keys already in use on the system.

FairCom server configuration options are available to directly specify a shared memory key. SQL and ISAM each require separate shared memory support:

SHMEM_KEY_ISAM <isam_shared_memory_key>

SHMEM_KEY_SQL <sql_shared_memory_key>

Shared memory key values can be specified in either decimal or hexadecimal format. For example:

; Set shared memory key for ISAM connections to the specified decimal value:SHMEM_KEY_ISAM 12345

; Set shared memory key for ISAM connections to the specified hexadecimal value:SHMEM_KEY_ISAM 0xabcd

FairCom servers on Unix and Linux use a Unix domain socket instead of named pipes for the initial shared memory protocol communication between the client and server.

  • The FairCom server uses a Unix domain socket instead of a pair of named pipes for the initial communication when a client connects to the server. The FairCom Server creates the named pipes, and when a client connects, the server waits for the client to write to either the socket or the named pipe. In this way, the server is able to support both clients that use the new method and those that use the original method.

  • The FairCom server configuration option COMPATIBILITY SHMEM_PIPE can be used to restore the behavior of earlier releases that only used named pipes. We expect this keyword to be used only in an unexpected situation in which the new option is not working as well as the original option.

  • FairCom clients (both ISAM and SQL) use the Unix domain socket method when connecting using the shared memory protocol if the server indicates that it supports it. If not, the clients use the original method.

  • A FairCom client library can be compiled with #define NO_ctFeatUNIX_SHMEMsocket to force the client to use the original method only.

On Unix/Linux systems, a user can belong to more than one group of which one group is the primary group, and all other groups are secondary groups. When the SHMEM_PERMISSIONS option is used to only enable user and group permissions on shared memory resources, the resources created for shared memory connections (files, semaphores, shared memory regions) are assigned with the user's current primary group by default.

To address this situation, the configuration option, SHMEM_GROUP, prevents a user account that shares a secondary group with the user account under which the FairCom server process is running failing to connect using shared memory.

This option causes the FairCom server to assign group membership to the specified group. This option applies to the resources for both the ISAM and the SQL shared memory protocol.

Example 1. Two user accounts
  • user1 belongs to groups group1 and group2

  • user2 belongs to group group2

If the user1 account runs the FairCom server with SHMEM_PERMISSIONS 660 in ctsrvr.cfg, a client program run by the user2 account will fail to connect using shared memory.

To allow the client program run by user2 to connect, add the following configuration option to ctsrvr.cfg and restart the FairCom server:

SHMEM_GROUP group2

This causes the shared memory resources to be assigned to group2, which allows the user2 client program to connect.