Product Documentation

FairCom Edge IoT Database

Previous Topic

Next Topic


FairCom Edge ships with many plug-ins, which extend its capabilities. They provide the ability to communicate over HTTP, MQTT, OPC UA, REST, ThingWorx AlwaysOn, etc.

Each plug-in is independently enabled and configured with a plug-in based architecture. They are not enabled by default to maximize security. (Plug-ins are secure, but they increase the attack surface by opening extra network ports and listening across more communication protocols.)

The ctsrvr.cfg configuration file contains a list of plug-ins that run when the HUB starts. This file is located in c-treeEDGE-Installation-Folder\server\config.

The example below shows the plug-in section of the ctsrvr.cfg configuration file on a Linux server:

; Plugins

PLUGIN cthttpd;./web/

;PLUGIN ctagent;./agent/

;PLUGIN ctthingworx;./thingworx/

;PLUGIN ctopc;./opc/

;PLUGIN ctaggregation;./aggregation/

In this example, the first plug-in is cthttpd. This is the HTTP plug-in that enables the IIoT Hub’s HTTP protocol, web services, and MQTT services. Following the keyword PLUGIN is the name of the folder containing the plug-in’s configuration file. The configuration file must have the same name as the plug-in’s folder but with the .json extension. In the example above, the name of the plug-in folder is cthttpd and this folder contains a configuration file named cthttpd.json.

All plug-in folders must be located in the FairCom Edge Server working directory (for example c-treeEDGE-Installation-Folder\server). You will see the plug-in sub-folders in this location (for example .\web, .\opc, etc.).

A semicolon must follow the name of the plug-in’s folder.

Following the semicolon is the relative file system path to the plug-in’s executable. The path is relative to the folder that contains the plug-in.

In the example above, ./web/ is the relative path to the plug-in’s executable, which is named

On Microsoft Windows, a plug-in is a Dynamic Linked Library with the extension of .dll. On Linux, a plug-in is a shared object library with the extension of .so. On MacOS, a plug-in is a dynamic library with an extension of .dylib.

To disable a plug-in, put a semicolon (;) before the keyword PLUGIN. To enable a plug-in, remove the semicolon.

Contact FairCom support to request new types of general-use plug-ins. FairCom Professional services can build custom plug-ins for you. You can also build your own plug-ins with help from FairCom support.

In This Section

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

c-tree Server Can Load Plug-In On-Demand after Server Has Started

Interface for Managing Plug-ins on-the-fly

Previous Topic

Next Topic

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.

Previous Topic

Next Topic

c-tree Server Can Load Plug-In On-Demand after Server Has Started

To dynamically load a plug‑in on demand after c-tree Server has started up, use the ctadmn utility or use the same PLUGIN configuration option syntax that you would use in ctsrvr.cfg in a call to ctSETCFG().

Example 1 ‑ ctadmn utility:

  1. Select option

    10. Change Server Settings

  2. Select option 10 again. Change the specified configuration option

    Enter the configuration option and its value:

>> PLUGIN cthttpd;./web/cthttpd.dll

Successfully changed the configuration option.

Example 2 ‑ API function call:

ctSETCFG(setcfgCONFIG_OPTION, "PLUGIN cthttpd;./web/cthttpd.dll");

Previous Topic

Next Topic

Interface for Managing Plug-ins on-the-fly

FairCom plug-in support has been enhanced by providing multiple interfaces for starting, stopping, and making calls to FairCom plug-ins on-the-fly. This allows more flexibility in how and when plug-ins are run. Previously, all plug-ins had to be configured and enabled at server launch. Now, run plug-ins on demand as they are needed and stop them when no longer required. Change the plug-in configurations and restart, allowing new settings to immediately take effect --all without taking the server down. A plug-in must be loaded (by uncommenting it in the server configuration file or via the ctadmn interactive option) before it will be available to stop or start.

Command-Line Administrator Utility

You can call ctadmn as a command-line utility to start and stop a plug-in using the following syntax:

ctadmn -s <server name> -u <user name> -p <password> -c "<command>"

where the <command> format is:

"plugin <plug-in name> start|stop"

Note: The command section must be enclosed in quotes.

ctadmn can execute any generic operation from the plug-in using the following syntax:

ctadmn -s <server> -u <user> -p <password> -c "plugin <plug-in name> <command> <arguments>"

Example 1 - Execute ctadmn command-line utility with direct arguments and start the web services plug-in:

ctadmn -s FAIRCOMS -u ADMIN -p ADMIN -c "plugin cthttpd start"

Example 2 - Execute ctadmn command-line utility interactively via option 10 and load and start the web services plug-in:

  1. Execute the ctadmn utility.
  2. Select option 10 - "Change Server Settings."
  3. Again select option 10 - "Change the specified configuration option."
  4. Enter the configuration option and its value:

    >> PLUGIN cthttpd;./web/cthttpd.dll

    Successfully changed the configuration option.

Example 3 – Using the ctadmn command-line utility to restart the OPC/UA plug-in after changing the settings:

  1. Edit the ctopc.json file to add a device or change the connection details to a device.
  2. Stop the OPC plug-in via ctadmn: ctadmn -s FAIRCOMS -u ADMIN -p ADMIN -c "plugin ctopc stop"
  3. Restart the plug-in via ctadmn: >ctadmn -s FAIRCOMS -u ADMIN -p ADMIN -c "plugin ctopc start"
  4. The OPC/UA plug-in will now load the modified configuration file and use the new settings.

Controlling plug-ins via C API

Control plug-ins via 2 C API functions, ctSETCFG() and ctPlugin(). Use ctSETCFG() to load a plug-in, ctPlugin() to start or stop a loaded plug-in.

ctSETCFG Function Call

NINT ctSETCFG(NINT option, pTEXT value);


  • option: Set this to setcfgCONFIG_OPTION
  • value: Set this to a string containing the same plug-in name and path as shown in your ctsrvr.cfg server configuration file.

Example 4 - Load the web services plug-in:

ctSETCFG(setcfgCONFIG_OPTION, "PLUGIN cthttpd;./web/cthttpd.dll");

ctPlugin Function Call

NINT ctPlugin(ctPLUGIN_COMMAND command, pTEXT inputBuffer, pTEXT outputBuffer, pVRLEN pOutputBufferSize);


  • command: currently, the options are ctPLUGIN_START or ctPLUGIN_STOP (defined by the ctPLUGIN_COMMAND enum type)
  • inputBuffer is flexible; currently, it expects only the plug-in name (loaded in the server by the PLUGIN keyword in ctsrvr.cfg)
  • outputBuffer: Starting and stopping plug-ins doesn’t have any output, so this is unused. Pass a pointer to a TEXT string.
  • pOutputBufferSize: Starting and stopping plug-ins doesn't have any output, so this is unused. Pass a pointer to a VRLEN number set to the length of the string passed to outputBuffer.

Example 5 -Stopping the web services plug-in:

ctPlugin(ctPLUGIN_STOP, " cthttpd ",outBuff,&outBuffLen);

Error Code

A new c-tree error code has been added: INV_CMD_ERR 1167 - Invalid plug-in command.