Product Documentation

Installing FairCom Products

Previous Topic

Next Topic

Configuring the Application Server

FairCom products include an application server that provides HTTP and WebSocket services, such as FairCom's REST API, JSON NAV API, and its browser-based web applications, such as SQL Explorer, Monitor, and MQ Explorer. See Configuring the Browser-Based Tools in the Browser-Based Tools guide.

To change the ports used by the application server, edit the file cthttpd.json located in the folder <faircom-Installation>\server\config.

  • The HTTP and HTTPS settings are used by the REST API and FairCom's browser-based applications, such as SQL Explorer.
  • The WebSocket settings are used by the JSON NAV API and MQTT-over-WebSocket protocol.
  • The MQTT settings are used by the MQTT protocol, which is available in the products FairCom EdgeMQ and FairCom EdgeHUB.

If you have a port conflict, you can change the port to an unused port. FairCom recommends you disable insecure HTTP connections (see below).

For example, FairCom's web applications and REST API are configured to listen for HTTP connections on port 8081 and HTTPS connections on port 8443. JSON NAV API is configured to listen on port 8081. MQTT is configured to listen on port 1883.

Configuring the Application Server (V12.5 and later)

In Version 12.5 and later, the configuration file contains the following JSON:

{

"tls_certificate": "./web/fccert.pem",

"http_port": 8080,

"http_enabled": true,

"https_port": 8443,

"https_enabled": true,

"websocket_port": 8081,

"websocket_tls_connections_only": true,

"websocket_enabled": true,

"mqtt_port": 1883,

"mqtt_tls_connections_only": false,

"mqtt_enabled": true,

"app_root": "./web/apps",

"http_url_to_appserver_map": [

"mqtt;ctmqtt.dll",

"ctree;ctrest.dll",

"AceMonitor;ctmonitor.dll",

"SQLExplorer;ctsqlexplorer.dll",

"ISAMExplorer;ctisamexplorer.dll"

],

"websocket_url_to_appserver_map": [

"json_nav;json_nav.dll"

]

}

  • The "http_url_to_appserver_map" property maps a URL sent over the HTTP protocol to an application server, which is a dynamically linked library (DLL) provided by FairCom. Contact FairCom if you would like to add your own application servers. For example, the mapping "http_url_to_appserver_map": ["mqtt;ctmqtt.dll"] maps the MQTT protocol to the ctmqtt.dll. This DLL processes the MQTT protocol the FairCom EdgeMQ and EdgeHUB products.
  • The "websocket_url_to_appserver_map" property maps a URL sent over the WebSocket protocol to an application server. For example, the mapping "websocket_url_to_appserver_map": ["json_nav;json_nav.dll"] maps the JSON NAV protocol to the json_nav.dll. This DLL processes the JSON NAV messages sent over the WebSocket protocol. The JSON NAV API is available in all FairCom server products.

Additional Security Options

You can add the following security settings to cthttpd.json.

{

"access_control_list": "-0.0.0.0/0,+192.168/16",

"auth_domain": "mydomain.com",

"global_auth_file": "./web/passFile",

"ssi_pattern": "**.shtml$|**.shtm$",

"tls_certificate": "./web/fccert.pem",

"tls_key": "SSL private key",

"tls_ca": "SSL Certificate Authority",

"tls_cipher_suites": "Allowed SSL cipher suites (colon-separated list)"

}

  • The "tls_certificate" property defaults to the file, fccert.pem, which is a self-signed certificate supplied by FairCom. You can change it to use your own certificate.
  • The "tls_key" property optionally specifies a private key. The private key can also be embedded in the file specified by the "ssl_certificate" property. For example, FairCom's default certificate file, fccert.pem, contains both the certificate and the private key, which eliminates the need to specify "ssl_key".
  • The "tls_ca" property specifies an external authority to validate certificates.
  • The "tls_cipher_suites" property specifies a colon-separated list of cipher suites approved for the application server to use.

Additional Web Server Options

You can add the following web server settings to cthttpd.json.

{

"web_thread_count": 10,

"document_root": "./web/apps",

"url_rewrites": "**.doc$=/path/to/cgi-bin/handle_doc.cgi",

"index_files": "index.html,index.htm,index.shtml,index.cgi,index.php,index.lp",

"hide_files_patterns": "secret.txt|even_more_secret.txt",

"extra_mime_type": ".cpp=plain/text,.java=plain/text",

"hexdump_file": "./web/hexDumpFile",

"cgi_interpreter": "#!/path/to/php-cgi.exe",

"cgi_pattern": "**.cgi$|**.pl$|**.php$"

}

The web server options allow you to deliver your own browser-based applications and services. Contact FairCom to learn more before changing these options because they may interfere with the built-in web applications and services. In addition, contact FairCom if you have specific requirements not covered with these options.

Database Connection Options

You can add the following database connection settings to cthttpd.json.

{

"linked_ace_server": "FAIRCOMS@localhost"

}

The "linked_ace_server" property specifies the database that the application server connects to. If it is omitted, it defaults to "FAIRCOMS@localhost", which causes the application server to connect to the database named FAIRCOMS that is running on the same computer as the application server. If you want the application server to connect to a database on another computer or to connect with a database that has a different name than FAIRCOMS, you can change the value of this property.

Configuring the Application Server (Prior to V12.5)

In FairCom product versions prior to 12.5, the configuration file contains the following JSON:


{

"listening_https_port": 8443,

"ssl_certificate": "./web/fccert.pem",

"document_root": "./web/apps",

"mqtt_enabled": true,

"mqtt_listening_port": 1883,

"mqtt_persistence_enabled": true,

"mqtt_log_enabled": false,

"mqtt_websocket_port": 8081,

"mqtt_websocket_ssl_enabled": true,

"mqtt_statistics_interval": 5,

"applications": [

"mqtt;ctMQTT.dll",

"ctree;ctREST.dll"

]

}

"listening_http_port": 8081 - Sets the port number used by the HTTP server for the REST API and browser-based tools. 8081 is the default; you can change it to any available port. (with the exception of the database engine's already two configured ports).

A list of ports is provided in Download and Installation.

Additional App Server Options

Additional options can be configured including secure TLS configurations (recommended). Contact FairCom if you have specific requirements not covered with these options.

{

"access_control_list": "-0.0.0.0/0,+192.168/16",

"auth_domain": "mydomain.com",

"cgi_interpreter": "#!/path/to/php-cgi.exe",

"cgi_pattern": "**.cgi$|**.pl$|**.php$",

"document_root": "./web/apps",

"extra_mime_type": ".cpp=plain/text,.java=plain/text",

"global_auth_file": "./web/passFile",

"hide_files_patterns": "secret.txt|even_more_secret.txt",

"hexdump_file": "./web/hexDumpFile",

"index_files": "index.html,index.htm,index.shtml,index.cgi,index.php,index.lp",

"listening_http_port": 8080,

"listening_https_port": 8443,

"ssi_pattern": "**.shtml$|**.shtm$",

"ssl_certificate": "./web/fccert.pem",

"url_rewrites": "**.doc$=/path/to/cgi-bin/handle_doc.cgi",

"web_thread_count": 10,

"mqtt_enabled": true,

"mqtt_listening_port": 1883,

"mqtt_persistence_enabled": true,

"mqtt_log_enabled": false,

"mqtt_conn_inactive_timeout": 60,

"mqtt_conn_request_timeout": 20,

"mqtt_max_dbconn_count": 30,

"application": [

"mqtt;ctMQTT.dll",

"ctree;ctREST.dll",

"AceMonitor;ctMonitor.dll",

"SQLExplorer;ctSQLExplorer.dll",

"ISAMExplorer;ctISAMExplorer.dll",

"OpsManager;ctMemphis.dll"

],

"linked_ace_server": "FAIRCOMS@localhost"

}

Advanced SSL Certificate Options

The ssl_certificate keyword in the config/cthttpd.json web server plug-in configuration supports the fccert.pem, which is a self-signed certificate we supplied. To use your own certificate, use the following keywords to config/cthttpd.json:

  • ssl_key: SSL private key - This can be embedded in the same file provided the in ssl_certificate. For example, our default fccert.pem certificate file has both the certificate and the private key, so, ssl_key is not required.
  • ssl_ca: SSL Certificate Authority - External authority that issues and validates the certificate.
  • ssl_cipher_suites - Colon-delimited list of SSL cipher suites.

Default linked_ace_server

The HTTP Plug-in (cthttpd, the Web Server Plug-in) supports connecting to a remote c-tree server. The engine to be used by the web server is configured by the linked_ace_server property in cthttpd.json. That option allows you to specify which c-tree server to use for the REST API, MQTT persistence, etc. The default linked_ace_server is NULL, which means FAIRCOMS@localhost. To change this default, change this property in cthttpd.json.

Because the default usage of cthttpd is by the HTTP Plug-in (the Web Server Plug-in loaded by a c-tree server), the plug-in framework already has the "caller" server name in the plug-in structure. So, instead of considering the default linked_ace_server as NULL, we now assume the local server name as default.

Note that if linked_ace_server is configured in cthttpd.json, it will overwrite this local server name as default.

TOCIndex