Configuration Options

Version 22.0.8486

Configuration Options

CData Connect comes pre-configured to work out-of-the-box in any environment. If desired, you can customize the way you access the data exposed in Connect by modifying the service.json file in the CData Connect installation directory (for Windows, this is C:\Program Files\CData\CData Connect by default). This file contains parameters you can modify for each of the categories listed below.

Customizing Service Ports

You can run CData Connect on custom ports by modifying these options:

Setting Description Default Value
“odata.port” The HTTP (OData and Web admin console) endpoint port 8080
“sql.tds.port” The Virtual SQL Server endpoint port 8033

Configuring Security

CData Connect supports security features that help safeguard your application and data. You can set the following options in service.json to set security policies:

Setting Description Default Value
“sql.dynamiciprestrictions.enabled” When set to true, if the Virtual SQL Server daemon receives five failed login attempts from a single IP address in a three-minute window, the IP address is blocked for 10 minutes. false

Configuring Encryption

For security purposes, CData Connect encrypts configuration files that contain saved connections and user and schema information. The encryption key file is randomly generated during installation and saved in the CData Connect installation directory as CData.key.

To change the encryption key, you can modify this file, or you can point the following item in service.json to a new encryption key file. You can also disable encryption by leaving this property blank:

Setting Description Default Value
“service.encryption.key” The path to the file containing the encryption key The installation directory

Enabling SSL

You may run CData Connect with SSL to ensure security and compatibility with newer web browsers. These are the configurations options for running CData Connect with SSL:

Setting Description Default Value
“service.ssl.cert” The SSL certificate used to run Enterprise Hub. If you are using a PEM file that contains more than one certificate, set this field to the certificate subject.  
“service.ssl.certtype” The SSL certificate type (“PFXFILE”, “JKSFILE”, “PEMFILE”, etc.)  
“service.ssl.jks.alias” The SSL certificate alias. This is only required if the certificate file is a JKS file and contains more than one certificate.  
“service.ssl.subject” The SSL certificate subject. This is only required if the certificate file is a PEM file and contains more than one certificate.  
“service.ssl.password” The SSL certificate password  
“odata.ssl.enabled” Whether SSL is enabled for the OData endpoint false
“sql.ssl.enabled” Whether SSL is enabled for the Virtual SQL Server endpoint false
“sql.ssl.required” Whether SSL is required for the Virtual SQL Server endpoint false

Specifying PEM File Private Keys

If you are using a PEM file for your SSL certificate, you must combine the certificate and private key into one file. The contents must follow this format, with the BEGIN and END delimiters intact:

<certificate content>

<private key content>

You can issue concatenate commands to create this combined file. On Windows, you can use PowerShell for this, and on Linux, you can use any terminal emulator. An example is shown below, which outputs the combined certificate and private key into the combinedKey.pem file:

cat publicCertificate.crt > combinedKey.pem
cat privateKey.key >> combinedKey.pem

When you create the file this way, ensure that the output file matches the required formatting outlined above.

Alternatively, you can manually create the PEM file by opening the certificate and key files in a text editor and combining them into a .PEM file according to the required formatting outlined above.

Configuring the Firewall

If you are hosting CData Connect in a restricted network with no direct outbound connectivity, you might need to configure firewall options for both the Connect Server application and for individual data connections. The application-level firewall can be set in the service.json file using to the properties listed below:

Setting Description
“firewall.type” The firewall type (“TUNNEL”, “SOCKS4” or “SOCKS5”)
“firewall.server” The firewall server
“firewall.port” The firewall port
“firewall.user” The firewall user
“firewall.password” The firewall password

Note: The application-level firewall is not used for connections to individual data sources. The firewall used for connections to data sources can be defined in the Advanced Settings tab of each connection.

Hardening Server Security Settings

You can increase the security of Connect server by setting the configuration parameter ScriptingEngineHardeningLevel in your environment variables. By default, this parameter is set to 0, which does not block any operations. You can set it to a value between 0 and 3, where each higher value increases security by disabling certain operations. The list below shows which operations are disabled at each hardening level:

  • 0: All operations are allowed. This is the default setting.
  • 1: The most vulnerable operations are disabled. This includes any operations that allow the user to interact with the host system in an arbitrary way.
  • 2: In addition to the operations disallowed in level 1, this level also disables operations for creating new users, accessing files on disk in a non-arbitrary way, and introducing recurring tasks.
  • 3: In addition to the operations disallowed in levels 1 and 2, this level also disables operations for obtaining sensitive information from the server or performing arbitrary http requests.

Enabling Logging

Enabling a log can be useful for troubleshooting. The following options allow you to configure the location and verbosity of CData Connect logging:

Setting Description Default Value
“service.log.folder” The location of the service logs. If you want to log to standard output (stdout), set this value to “STDOUT://”. Note that using stdout will hide the Logs tab in the CData Connect UI. The installation directory
“service.log.level” The verbosity level of the service log (“Error”, “Warning”, “Info”, or “Debug”). Please note that Debug-level verbosity can include some sensitive information, such as TDS login packets. Please review logs of this level for sensitive information before sharing them outside of your organization. “Info”
“service.log.retaindays” The number of days to retain service and driver logs. Logs that are older than this value are automatically deleted every day. 30

The verbosity of driver logs is configured separately for each connection. For more information, see Data Model.


Connect Server supports the following miscellaneous settings:

Setting Description Default Value
“service.connection.maxcustomschema” The maximum number of custom schema allowed per connection 100

Enabling High Availability

CData Connect Server supports high-availability topologies, which ensure that critical services are always on. To enable a high-availability configuration, each CData Connect node must use a shared data folder in which connections, users, permissions, and other CData Connect settings are saved. However, logs must be stored independently on each node.

Follow the steps below to enable high availability across two or more nodes:

  1. On each CData Connect node, mount a common remote directory (e.g. /mnt/cdata/connect/). Make sure that the users running the CData Connect service have read and write permissions at this path.
  2. Install CData Connect on each node.
  3. Copy the file drivers.json and the directory lib from one of your installations into the shared remote directory.
  4. In the service.json file of each CData Connect installation, set the property “” to the path of the shared directory defined in the first step.
  5. In each node, set the value of “service.log.folder” in the service.json file to a unique local path (e.g. /opt/cdata/logs/).
  6. Launch the CData Connect service on each node.

Password Reset

CData Connect provides the ability to reset an administrator’s password, which enables the administrator to regain access to the application if they are locked out. The Java command below can be used to accomplish this:

java -jar connect.jar -resetpassword -user <user> -password <newpassword> -f service.json

When issuing this command, substitute the administrator username for <user> and the desired password for <newpassword>.