|
|
|
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/libcthttpd.so
;PLUGIN ctagent;./agent/libctagent.so
;PLUGIN ctthingworx;./thingworx/libctthingworx.so
;PLUGIN ctopc;./opc/libctopc.so
;PLUGIN ctaggregation;./aggregation/libcttimestamp.so
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/libcthttpd.so is the relative path to the plug-in’s executable, which is named libcthttpd.so.
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.
|
|
|
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.
|
|
|
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:
10. Change Server Settings
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");
|
|
|
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:
>> 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:
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);
Where:
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);
where:
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.
