Skip to main content

Manage FairCom DB plug-ins

Plug-Ins and Callbacks Extend the FairCom Database Engine

With FairCom V12 a new ability to extend functionality with advanced modular capabilities is provided. Using a new plug‑in architecture, advanced features can be quickly dropped in using independently configured plug-ins that are provided as a shared object with companion configuration file entries. Each plug-in is usually self-contained in its own folder. All plug-in configurations are stored in the <faircom>\config folder.

Several plug‑ins are provided by default. The following plug-ins are provided beginning with V12:

  1. HTTP web services

  2. MQTT message services

  3. REST API services

  4. OPC communication protocols for Industrial IoT (IIoT) services

  5. UA communication interface for IIoT services

  6. PTC ThingsWorx® IIoT integration

  7. PTC ThingWorx® AlwaysOn IIoT protocols

Most of the provided plug-ins are not enabled by default to maximize security and minimize memory usage. FairCom plug‑ins are securely implemented but they can increase the attack surface by possibly opening additional network ports and listening across alternative communication protocols.

Plug-ins are enabled as needed in the standard FairCom ctsrvr.cfg and services.json files. Each plug-in is individually enabled using a configuration line that includes its configured name and shared object location.

Example

; Plugins
PLUGIN cthttpd;./web/cthttpd.dll
PLUGIN ctagent;./agent/ctagent.dll

The ctsrvr.cfg configuration file is now located in <faircom>\server\config (this location is optional and existing locations are supported for full backward compatibility).

Dynamic plug-ins

Interface for Managing Plug-ins on the fly

Beginning with V13, FairCom plug-in support has been enhanced by providing multiple interfaces for loading, starting, and stopping FairCom plug-ins on the fly. Previously, all plug-ins had to be configured and enabled at server launch. Now plug-ins can be loaded, started, and stopped on demand without restarting the server.

Loading, starting, and stopping plug-ins can be accomplished by either uncommenting them in the ctsrvr.cfg server configuration file, using the ctadmn command-line utility, or calling C API functions. A plug-in must first be loaded then it can be started and stopped.

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> is enclosed in quotes as in the following format:

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

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 the 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 the ctadmn command-line utility interactively using option 10 to 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 – Use 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: &gt;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.

Control plug-ins using C API functions

Control plug-ins using the ctSETCFG() and ctPlugin() functions. Use ctSETCFG() to load a plug-in, and use ctPlugin() to start or stop a loaded plug-in.

Example 1 - Load the web services plug-in:

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

Where:

  • setcfgCONFIG_OPTION is a general-purpose option used for passing a string value.

  • "PLUGIN cthttpd;./web/cthttpd.dll" (in quotes) is a string containing the same plug-in name and path as shown in your ctsrvr.cfg server configuration file.

Example 2 - Start the web services plug-in:

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

Where:

  • 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 does not have any output, so this is unused. Pass a pointer to a TEXT string.

  • pOutputBufferSize: Starting and stopping plug-ins does not 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 3 - Stop the web services plug-in:

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