Setting up Qlik Data Gateway - Direct Access

This topic outlines the Qlik Data Gateway - Direct Access prerequisites, provides installation instructions, and describes the limitations and considerations you should be aware of when working with Qlik Data Gateway - Direct Access.

Best practices when using Qlik Data Gateway - Direct Access

For a successful experience when using Qlik Data Gateway - Direct Access, it is strongly recommended to adhere to the following best practices:

• Do not use the same Direct Access gateway for development, user acceptance testing, and production, as this will increase the risk of overloading the available resources and impact system stability. From a business perspective, the combination of insufficient resources and decreased stability, might result in delayed updates to production application data.
• For optimal performance, install the Direct Access gateway on a server that is as close as possible to your data source.

• Direct Access gateway should be installed on a dedicated Windows Server as stipulated in the system requirements below. Do not install it on the actual database server or alongside other Qlik products, including but not limited to, Qlik DataTransfer, Qlik Sense Desktop, and Qlik Sense Enterprise.

System prerequisites

This section describes the software, ports, and hardware requirements for using Qlik Data Gateway - Direct Access.

Software prerequisites

• The Direct Access gateway should be installed on a Windows Server machine behind your firewall. The server should be able to access your data source.

  Supported Windows Server editions:

  • 2016
  • 2019
  • 2022

• Three different .NET versions need to be installed. Install the following .NET versions only:

  • .NET 4.8: Required for the installation.

  • .NET 6.0.x Runtime (x64) and ASP.NET Core Runtime 6.0.x (x64) (latest patch)

    News noteFrom Direct Access gateway 1.6.8, .NET 6.0.x is no longer required.

  • .NET 8.0.x Runtime (x64) and ASP.NET Core Runtime 8.0.x (x64) (latest patch)

  Information noteDirect Access gateway 1.6.6 and 1.6.7 requires both versions - 6.0.x and 8.0.x - of the .NET and ASP.NET Core Runtimes.

  For instructions on how to verify the currently installed .NET version, see https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed.

• Microsoft Visual C++ 2015-2022 Redistributable (x64). The Direct Access gateway setup will prompt you to install the redistributable if it detects that it is not currently installed.

Additional software prerequisites when using SAP data sources

• Install the SAP NetWeaver RFC SDK on the Qlik Data Gateway - Direct Access machine, as described in Installing SAP NetWeaver RFC SDK for Qlik Data Gateway - Direct Access.
• Install Microsoft Visual C++ 2013 Redistributable (x64) on the Qlik Data Gateway - Direct Access machine.

Required ports and protocols

The following section lists the required ports.

Outbound ports

HTTPS/TCP-443 should be opened for outbound communication to <tenant-id>.<region>.qlikcloud.com.

Internal ports

Below is a list of ports used for communication by internal data gateway processes. If any of these ports is being used by another application, reconfigure the other application or uninstall it.

General ports

• 5050 (Connector Agent REST API)
• 9027 (DCAAS REST API)

ODBC ports

• 3005 (ODBC Connector REST API)
• 50060 (ODBC Connector gRPC)

SAP ports

• 3007 (SAP BW Connector REST API)
• 3008 (SAP SQL Connector REST API)
• 3009 (SAP ODP Connector REST API)
• 50070 (SAP BW Connector gRPC)
• 50080 (SAP SQL Connector gRPC)
• 50090 (SAP ODP Connector gRPC)

WSS protocol

In addition to HTTPS, Direct Access gateway also uses WSS (WebSocket Secure) protocol. Therefore, make sure that your firewall and proxy server (if you intend to use one) are set up to allow outbound WSS connections.

Recommended minimum hardware

• 8 cores

• 32 GB memory

• 5 GB storage

System cryptography

Qlik Cloud Government supports using Qlik Data Gateway - Direct Access only when Windows is configured to run in a FIPS 140-2 approved mode of operation (FIPS mode). To turn on FIPS mode, enable the Windows policy: System cryptography: Use FIPS compliant algorithms for encryption, hashing, and signing. For more information, see step 3 of the procedure Using Windows in a FIPS 140-2 approved mode of operation.

Installing Qlik Data Gateway - Direct Access

Setting up the Direct Access gateway involves procedures that need to be performed both in the Administration activity center and on the Direct Access gateway server.

Stage one: Download Qlik Data Gateway - Direct Access

1. In the Administration activity center, select Data gateways.

   Any existing data gateways will be listed in a table showing basic information about each gateway.

2. Click the Deploy toolbar button.

   The Deploy Data Gateway dialog opens.

3. Select Data Gateway - Direct Access, accept the Qlik Customer Agreement, and click Download. The Direct Access gateway setup file (qlik-data-gateway-direct-access.exe) will be downloaded to your machine.

Stage two: Install the Direct Access gateway on a server behind the firewall protecting your data sources

This stage involves installing the Direct Access gateway. You can either install Direct Access gateway interactively or silently.

Interactively installing Direct Access gateway

1. When the download is complete, copy the setup file to a Windows Server machine behind the firewall. Make sure the machine can communicate with your data sources.

2. Open the file to launch the Setup Wizard. Continue clicking Next until setup is complete.
   

   Information note

   • Direct Access gateway requires Microsoft .NET 6.x and .NET 8.x. If setup detects that an earlier version is installed, you will be prompted to install the required version. When the .NET installation completes, you will need to restart the Direct Access gateway machine and then run the Direct Access gateway setup again.

   • Setup will prompt you to install Microsoft Visual C++ 2015-2022 Redistributable (x64) if it detects that it is not currently installed.

   • During setup, you can optionally change the default installation path (C:\Program Files\Qlik\ConnectorAgent).

Silently installing, upgrading, and uninstalling Direct Access gateway

Installing Direct Access gateway silently is useful, for example, if you need to install Direct Access gateway on several machines throughout your organization.

Prerequisites

Make sure to install the correct versions of all the prerequisite software before beginning the silent installation as, unlike the interactive installation, this cannot be done during the installation.

Installing or upgrading Direct Access gateway

Open a CMD prompt as administrator and run the following command from the folder containing the Direct Access gateway executable:

qlik-data-gateway-direct-access.exe /S InstallPath="full-path" AcceptEula=yes

Where full-path should be replaced with the actual installation path in quotation marks, for example, "C:\TMP\Qlik".

Uninstalling Direct Access gateway

Open a CMD prompt as administrator and run the following command from the folder containing the Direct Access gateway executable:

qlik-data-gateway-direct-access.exe /S /uninstall

Troubleshooting the installation

The installation log files provide information that should help you (or Qlik Support) troubleshoot any failures. The full path to the log file is:

C:\Users\<user>\AppData\Local\Temp\Qlik Data Gateway - Direct Access_<Timestamp>.log

Stage three: Setting up Direct Access gateway

This stage includes setting your Qlik Cloud tenant URL, optionally setting a proxy server, and generating a registration key. You will need to copy the key to the data gateway settings in the Administration activity center (in stage three below). The key is used to establish an authenticated connection between the Direct Access gateway and the Qlik Cloud tenant.

On the Direct Access gateway machine, open a Command Prompt as an administrator and change the working directory to the ConnectorAgent subfolder (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent with a default installation).

Then, continue as described below.

Setting the Qlik Cloud tenant

Set which Qlik Cloud tenant to connect to. To connect to the tenant via a proxy server, add the relevant parameters to the command as shown below.

Command for setting the Qlik Cloud tenant without a proxy server:

Syntax:

connectoragent qcs set_config --tenant_url your-qlik-cloud-tenant-url

Example:

connectoragent qcs set_config --tenant_url mytenant.us.qlikcloud.com

Command for setting the Qlik Cloud tenant with a proxy server:

Syntax:

connectoragent qcs set_config --tenant_url your-qlik-cloud-tenant-url --proxy_url http://host:port --proxy_username username --proxy_password password

Example:

connectoragent qcs set_config --tenant_url mytenant.us.qlikcloud.com --proxy_url http://myproxy:1212 --proxy_username admin --proxy_password f56weqs@

For information on proxy limitations, see Connecting to Qlik Cloud via a proxy server.

Setting the CA bundle

The CA bundle authenticates the identity of the Qlik Cloud tenant, thereby ensuring a trusted connection.

Who needs to set the CA bundle?

The CA bundle only needs to be set if you are:

• A Qlik Cloud Government customer
• A Qlik Cloud commercial customer using a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates

Which bundle should I use?

Customers should either use the Qlik CA bundle or bring their own CA bundle, as follows:

• Qlik provides the CA bundle: Should be used by Qlik Cloud Government customers with a standard environment. A standard environment is an environment that does not have a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates.

  In a default Direct Access gateway installation, the CA bundle file can be found in the following location: C:\Program Files\Qlik\ConnectorAgent\caBundle\qcg_ca_bundle.pem

  Information noteYou can rename the CA bundle file, but make sure that it has a .pem extension (for example, qlikcerts.pem). Then, run the command(s) described below.
• Customers bring their own CA bundle: Should be used if the customer's environment is using a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates. If those certificates are self-signed, then in addition to the command for setting the CA bundle, you also need to run the command for allowing the CA bundle. Both of these commands are described below. This applies to both Qlik Cloud Government customers and Qlik Cloud commercial customers alike.

Command for setting the CA bundle

Run the following command to set the CA certificate bundle:

Syntax:

connectoragent qcs set_config --ca_bundle_path path-to-ca-bundle-file

Example:

connectoragent qcs set_config --ca_bundle_path c:\ca\cacerts.pem

Command for allowing the CA bundle

Some environments use a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates. This command only needs to be run if the security appliance itself uses a self-signed certificate. In such a case, the CA bundle might not be trusted unless you run the following command:

connectoragent qcs set_config --ca_bundle_allow_invalid_certs true

Generating and showing the registration key

The key is used to establish an authenticated connection between the Direct Access gateway and the Qlik Cloud tenant.

Command for generating the registration key

connectoragent qcs generate_keys

Command for showing the registration key

connectoragent qcs get_registration

The key is shown.

Copy the entire key as shown in the example above. You will need to paste it into the Administration activity center in the next stage.

Stage four: Return to the Administration activity center and register the data gateway

1. In the Administration activity center, select Data gateways.

   Any existing data gateways will be listed in a table showing basic information about each gateway.

2. Click the Create toolbar button.

   The Create data gateway dialog opens.

   

3. Specify a name for the data gateway.

4. Optionally, provide a description for the data gateway.

5. From the data gateway type drop-down list, select Direct Access.

6. From the Associated space drop-down list, select a space.

   When associating the Direct Access gateway with a space, you should be aware of the following:

   • Data gateways can be created in Shared or Managed spaces only
   • To be able to create a data connection in one space that uses a data gateway from another space, you must have the Can consume data role in the data gateway space.

   • To be able to create a data gateway, the user needs to be a space owner or have the Can manage role. In addition, the user needs Professional or Full User entitlement. Assign Professional entitlement manually or by turning on Enable dynamic assignment of professional users in the Administration activity center.

     For more information on user entitlements and dynamic assignment of professional access, see Managing user entitlements

   • Data gateways can be associated with a single space only.

7. Paste the registration key you generated earlier into the Key field.

8. Click Create.

   The data gateway is added enabled to the Data gateways list.

Stage five: Start the Qlik Data Gateway - Direct Access service on the Direct Access gateway server

On the Direct Access gateway server, do one of the following to start the service:

• Open the Windows Services console and start the Qlik Data Gateway - Direct Access service.

• Open a Command Prompt as an administrator and change the working directory to the ConnectorAgentsubfolder (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent with a default installation). Then, run the following command:

  connectoragent service start

  A confirmation that the service started successfully will be shown.

See also: Running the service under a different account

Stage six: Add a connection to your data source

Locate your gateway in the Data gateways list and verify that its State is “Connected” (you might need to refresh your browser to see the current status). You can then proceed to add a connection to your data source.

There are several ways you can load data from data sources: 

• Adding and managing data sources from spaces

• Loading and managing data with Data Manager

• Loading and transforming data with scripting

The list of available data sources will contain duplicate entries for those data sources that support gateway connectivity. Gateway-compliant data sources can be identified by the words "via Direct Access gateway”, which appear in parenthesis after the source type.

Supported data sources

• ODBC sources. For more information, see ODBC databases ‒ Qlik Cloud.

• SAP BW and SAP SQL sources. Requires Direct Access gateway 1.2.0 or later.

  For information on setting up connectivity to these sources, see SAP NetWeaver.

General limitations and considerations

• Direct Access gateway can connect to a single tenant only.
• If, for any reason, the Direct Access gateway server is rebooted during a Qlik application reload, the reload will fail. Restart the Qlik application reload to refresh the data.

• Reload script queries cannot exceed 500,000 characters.

  For information on reloading scripts, see Reloading scripts.