Using a Dundas BI gateway

1. Overview

You can use a gateway to connect to your on-premise data from an instance of Dundas BI version 11 or higher running in the cloud.

Once the gateway is installed on your local network and configured in Dundas BI, users can create data connectors to access the following on-premise data sources via the gateway:

• dBase (DBF) files
• Flat files
• MemSQL
• Microsoft Excel
• Microsoft SQL Server
• MySQL
• OData
• ODBC (install ODBC drivers to use for additional data sources)
• Oracle database
• PostgreSQL
• Teradata
• XML files

2. System requirements

Some data sources may require drivers to be installed on the same computer as the gateway. The gateway also has minimum requirements for the operating system and for .NET that are similar to the server requirements for a Dundas BI instance, but the minimums listed for evaluation use can also be suitable for a gateway.

See Dundas BI - System Requirements for the list of these requirements.

3. On Windows

3.1. Installation

Download BIGateway.msi from the My Account page on the support site, then run it on a computer that can be used to provide access to your data sources to start the Dundas BI Gateway Setup Wizard.

Follow the steps of the wizard. When complete, the Dundas BI Gateway Manager will be installed on the computer.

When a new version of this installation file becomes available corresponding with a newer version of Dundas BI, you can download it and run it again to upgrade your gateway manager to the new version, then use the gateway manager to update your gateway(s) as described below.

3.2. Managing gateways

On the computer where it was installed, run the Dundas BI Gateway Manager from the Start menu.

You can create a gateway for each instance of Dundas BI that you want to be able to access your local data sources through this computer.

Click the Add Gateway button to create a new gateway for a particular Dundas BI instance.

Enter the instance Name (for your reference), and the Dundas BI Gateway Hub URL based on the address you use to access Dundas BI with /GatewayHub/ added. For example, if you can navigate to Dundas BI at https://bi.example.com/, enter https://bi.example.com/GatewayHub/.

You can customize the installation directory if preferred, then click Add to install the gateway files and service.

Once the process is complete, the new gateway is listed in the Gateway Manager along with its status, and a clickable link to the gateway's installation folder and its subfolders such as Logs in case of errors or issues. You can click to Restart the service if required for new installed drivers, for example, or click to Remove the gateway. After installing a new version of the Gateway Manager, you will also be able to click to Update the gateway to the newest version.

Next, click the link for the Config Override File to open it in a text editor, and note the GatewayId and PreSharedKey values located inside the <Setting> elements, which you will need to configure the gateway in Dundas BI.

4. On Linux

4.1. Installation

The Dundas BI Deployment wizard is used to create and manage gateways on Linux.

Follow the instructions in Installing Dundas BI on Linux for downloading and installing the Deployment wizard for your distribution of Linux, but do so on a computer that can be used to provide access to your data sources. Rather than launching the wizard to create an instance, you will create a gateway as shown below.

When a new version of Dundas BI becomes available, you can download and install the new version of the Deployment wizard, then run the step to upgrade your existing gateway.

4.2. Managing gateways

Launch the Dundas BI Deployment wizard in a terminal using the --gateway option. For example:

sudo dundasbi --wizard --gateway

To create a new gateway, type the number indicated for the step Create Gateway followed by the enter key. There are also steps available to Upgrade Gateway and Remove Gateway.

A prerequisites check may run. Follow the prompts, or type y and the enter key to continue if the check passed.

You will be prompted to enter a Name for the Dundas BI instance you want to use this gateway (for your reference), followed by the Dundas BI Gateway Hub URL based on the address you use to access Dundas BI with /GatewayHub/ added. For example, if you can navigate to Dundas BI at https://bi.example.com/, enter https://bi.example.com/GatewayHub/.

These details will be displayed back to you next and you can type y followed by the enter key to confirm and create the gateway.

Once the tasks are complete, note the GatewayID and PreSharedKey values indicated in your terminal, as you will need these when configuring the gateway in Dundas BI. If you need to find them again later, they are also defined within the ConfigOverride.xml file in the App_Data folder.

Once created, your gateway's App_Data directory is located at:

/usr/share/dundas/bi/Gateways/Files/{InstanceName}/App_Data

In some cases, drivers may need to be installed in subdirectories created under this directory if indicated in links from the data sources section of Dundas BI's system requirements. There is also a Logs subdirectory with files that may record errors.

A service is also installed that needs to continue running in order to provide access to your data sources for Dundas BI. You can control or check the status of this service using the following commands (you may need to use the sudo command in front):

systemctl stop dundas-bi-gateway-{InstanceName}.service

systemctl start dundas-bi-gateway-{InstanceName}.service

systemctl restart dundas-bi-gateway-{InstanceName}.service

systemctl status dundas-bi-gateway-{InstanceName}.service

5. On Docker

Like other Dundas Docker images, the gateway can run as a Docker container using the image dundas/dundas-bi-gateway. This allows you to run on other machines that can access your data sources besides the supported Windows and Linux environments if compatible.

The gateway is configured using environment variables set when starting the container:

You should set up the Gateway Manifest in Dundas BI as described in the following section first using the gateway ID and pre-shared key you plan to set as environment variables, and then start up your gateway container.

Here is an example for starting the container using docker run:

docker run -it \
-e DUNDAS_BI_EXTERNAL_APPLICATION_URL="https://dundas.example.com/" \
-e DUNDAS_BI_GATEWAY_ID="b3f999b0-5dc5-4790-bc9c-3a2e97d8701f" \
-e DUNDAS_BI_GATEWAY_PRESHARED_KEY="h9LR6yUxFpdXAserzdXjVxB4DQdNl3rTdKDj2Mxr" \
-e DUNDAS_BI_AGREE_TO_TERMS_OF_GATEWAY_EULA="true" \
dundas/dundas-bi-gateway

6. Set up Dundas BI

Dundas BI must be set up for gateways before you can use them, by installing a gateway hub and configuring it for your on-premise gateway.

6.1. Install the gateway hub

Add the gateway hub to your Dundas BI instance on the server where Dundas BI was installed, which will add support for connecting with your gateway running on-premises.

Use the same installation tool you used to install your Dundas BI instance:

• On Windows, run Dundas BI Deployment (available from the start menu on the server) and go to the Extras section to find and choose the option to add the gateway hub.
• When Dundas BI is installed directly on Linux, run the Dundas BI Deployment Wizard and choose the option to add the gateway hub. If you are using your own reverse proxy configuration rather than the Deployment wizard's provided one, it will need to be updated for the gateway hub.
• For Kubernetes deployments, use the dundas.bi.gatewayhub Helm chart options.
• If you are running Dundas BI containers yourself with Docker directly, configure your reverse proxy for the dundas-bi-gateway-hub container to be accessible as the subpath /GatewayHub under your instance.

6.2. Configure your gateway

Log into Dundas BI as an administrator user and access the Admin area from the main menu on the left.

Click to expand Setup and then to navigate to Config to access Dundas BI's configuration settings.

Find or search for the Gateway Manifest setting (located in the Data category), and double-click it or select it and click Edit. If gateway options are missing when using Dundas BI version 11 or higher, you may need an updated license with this feature enabled.

In the configuration dialog, click Edit value, and then enter your configuration as a JSON array like the following:

[{
    "Id": "c3c2e1f3-7962-4a38-a9d7-d0af3ea73e3b",
    "DisplayName": "Office",
    "PreSharedKey": "Ut5x8VGGPolxpylVmF5h5iVgmgDlphkJXiRUiTnf"
}]

If you have multiple gateways, you can provide multiple comma-separated objects as defined within curly braces { }. Each object should provide the following details for a gateway:

• Id - The gateway ID provided to you earlier, from your gateway's Config Override File or from your terminal after adding the gateway on Linux.
• DisplayName - The name used to identify this gateway when using it in a new data connector.
• PreSharedKey - The pre-shared key value provided to you earlier along with the gateway ID.

Submit the dialog for the configuration to take effect.

6.3. Configure the gateway hub

Also in configuration settings, ensure that the Gateway Hub URL is set to the /GatewayHub/Gateway/ subpath under your Dundas BI instance. For example, if the address for Dundas BI's administration pages including configuration settings begin with https://bi.example.com/Admin/, the gateway hub URL should be https://bi.example.com/GatewayHub/Gateway/.

6.4. Restart services

You may need to restart the website's application pool, service, or container for the changes to take effect once the gateway and gateway hub are configured.

7. Connect to your gateway

Once your gateway and gateway hub are set up and any necessary drivers are installed, Dundas BI users can use that gateway to connect to on-premise data sources in data connectors.

When creating or editing a data connector with Data Provider set to a supported data source, select the Use Gateway checkbox and then select your Gateway from the list that appears.

Now you can enter the connection details your gateway should use to access your data source.

8. Security

• The gateway uses only outgoing connections, so your environment does not need to support incoming or inbound connections.
• Your gateway connects to the Dundas BI URL you specified when adding it. Your Dundas BI instance should be configured to use HTTPS encryption to secure this traffic.
• Trust is established between your Dundas BI instance and gateway through the pre-shared key used during configuration, so that your instance will only accept incoming connections from your gateway.
• When data source connection details need to be communicated to your gateway, a pre-shared key is used with AES encryption and a SHA-512 hash function.

9. See also

• Connect to data and view it on a dashboard
• Configuration settings
• Dundas BI - System Requirements
• Configuration best practices