Bridge Installation for Windows
This document outlines the process for setting up the OvalEdge Bridge, a secure and reliable solution that connects customer-managed data sources with the OvalEdge cloud platform. The Bridge enables communication without requiring changes to firewall rules by utilizing a client-side component installed within the customer’s infrastructure. It supports HTTPS and uses pull-based communication to ensure secure data exchange. The Bridge simplifies connectivity while supporting various data sources, allowing users to access and manage data through the OvalEdge platform without impacting network security or compliance.
Purpose of the document
The purpose of this document is to provide clear and concise instructions for installing, configuring, and running the OvalEdge Bridge on Windows-based systems. It includes prerequisites, installation procedures, firewall setup, and optional service configuration. This ensures secure connectivity between customer data sources and the OvalEdge platform, without requiring complex network changes.
Prerequisites
Bridge installation is a one-time process completed within the client infrastructure using downloadable components from the OvalEdge server.
To install and run the OvalEdge Bridge properly, the system must meet these minimum requirements and have the required network access configured.
Recommended System Configuration
The following hardware and software specifications are recommended for the virtual machine hosting the OvalEdge Bridge:
Hardware Requirements
RAM
32 GB
SSD
250 GB
vCPU
8 cores
Software Requirements
Operating System
Windows Server 2019 / 2022
Java Runtime Environment
OpenJDK 17.0
Network & Security Requirements
The static public/NAT IP address of the VM must be shared with OvalEdge to configure access in the SaaS Bridge firewall.
Outbound Port 9443 must be opened in the firewall to allow communication with OvalEdge’s Nifi Server.
Make sure that the Bridge Client IP is whitelisted in all connector data sources for seamless data access.
URLs: OvalEdge will share the NiFi-Server and Application URLs for bridge connectivity.
Auto NAR update prerequisites
For auto NAR updates on Windows:
1. Use a NiFi version that supports auto load.
2. Set nifi.nar.library.autoload.directory to the extensions directory in nifi.properties.
3. Grant the service account read and execute permissions on that directory.
4. Keep enough disk space for new NAR files.
5. Remove older NAR versions if a restart must switch versions.
6. Refresh the UI to view new components after auto load.
Java JDK Installation and Configuration
Step 1: Access the Server
Log in to the AWS Windows Server instance via Remote Desktop (RDP).
Step 2: Install Java OpenJDK 17.0
Download OpenJDK 17.0:
Download and run the JDK installer.
Accept the license agreement and proceed with the default settings.
Step 3: Configure Environment Variables
Set JAVA_HOME:
Navigate to: Control Panel > System and Security > System > Advanced System Settings > Environment Variables
Under System Variables, create a new variable:
Variable Name: JAVA_HOME
Variable Value: C:\Program Files\Java\OpenJDK 17.0.x_xx (replace x_xx with the installed version number).
Update PATH Variable:
Add the Java bin directory to the system PATH.
Under System Variables, find and select Path, then click Edit.
Click New and add the path to the Java bin folder (e.g., C:\Program Files\Java\jdk-xx\bin).
Click OK to save changes.
Step 4: Verify Installation
To verify the installed Java version, use the following commands:
java -versionExpected Output: Displays the installed Java version.
Configuring Windows Defender Firewall for Bridge Communication
To establish secure and uninterrupted communication between the Nifi-Bridge Client and the Nifi-Server hosted in the OvalEdge SaaS environment, you must configure Inbound and Outbound port rules in Windows Defender Firewall with Advanced Security.
Follow the instructions below to create the necessary firewall rules:
Step 1: Inbound Rule Configuration (Port 9443)
Open Firewall Settings:
Go to the Start Menu, search for Windows Defender Firewall with Advanced Security, and open it.
Create New Inbound Rule:
Click on Inbound Rules in the left panel.
Select New Rule from the right-side panel.
Rule Type Selection:
Select Port as the rule type.
Click Next.
Protocol and Port Settings:
Select TCP.
Select Specific local ports and enter: 9443
Click Next.
Action:
Select Allow the connection.
Click Next.
Profile Selection:
Apply the rule to the appropriate profiles (Domain, Private, or Public) according to the network setup.
Click Next.
Naming the Rule:
Provide a meaningful name such as: Nifi-Bridge-Client-Inbound-Port
Finish:
Click Finish to apply the rule.
Step 2: Outbound Rule Configuration (Port 9443)
Open Firewall Settings:
Navigate back to Windows Defender Firewall with Advanced Security.
Create New Outbound Rule:
Click on Outbound Rules in the left panel.
Select New Rule from the right-side panel.
Rule Type Selection:
Select Port.
Click Next.
Protocol and Port Settings:
Select TCP.
Select Specific local ports and enter “9443”.
Click Next.
Action:
Select Allow the connection.
Click Next.
Profile Selection:
Apply the rule to the relevant profiles.
Click Next.
Naming the Rule:
Provide a meaningful name such as: Nifi-Bridge-Client-Outbound-Port
Finish:
Click Finish to complete the configuration.
Verifying Connectivity: Bridge Client to Nifi Server
After completing all prerequisite configurations, it is essential to confirm that the Bridge Client can successfully communicate with the Nifi Server hosted in the OvalEdge SaaS environment.
Connectivity Test Procedure
To verify the connection:
Open Command Prompt on the Bridge Client VM.
Run the following command:
curl -v telnet://<domain-shared-by-ovaledge>:9443Expected Outcome: If the connection is successful, you will observe a "Connected" response.
Bridge Installation Steps
Follow these steps to set up the OvalEdge Bridge in the VM:
Download the Bridge Artifacts from the OvalEdge application.
Install and Register the Bridge on the on-premise system.
Download the Bridge Artifacts
Step 1: Access the OvalEdge Application
Log in to the OvalEdge application.
Navigate to Administration > Connectors to open the Connectors Information page.
Step 2: Add a New Bridge
Click the Manage Bridge icon to open the Bridge Details page.
Click the “+” icon to open the Add Bridge pop-up window.
Enter the Bridge IP Address:
If the Bridge Client VM has a public IP, enter it.
If the VM does not have a public IP address, enter the private IP address instead.
Click Save.
Step 3: Retrieve Bridge Connection Details
A pop-up window will appear with the following information:
Bridge ID
Security Code (e.g., BRIDGExxxxxxxxxxxxxxx)
Download link for:
Bridge Secure Connectivity Pack (ZIP file)
Bridge Installation Software
Download the Bridge Secure Connectivity Pack to your desktop from the pop-up.
Download the Bridge client installer using the link below. https://oe-saas-distributions-bridgeclient.s3.ap-south-1.amazonaws.com/bridge_client_installer/ovaledge-bridge-client-installer.jar
Click OK. The new bridge will now be listed on the Bridge page.
Install and Register Bridge Client
To install and register the OvalEdge Bridge Client on a Windows machine, follow the steps below:
Step 1: Create Installation Directory
Navigate to the C Drive.
Create a new folder and name it: Bridge-Client.
Download the ovaledge-bridge-client-installer.jar file from the provided link.
Move the downloaded file into the newly created Bridge-Client folder.
Step 2: Launch Installer
Double-click on the ovaledge-bridge-client-installer.jar file to launch the installer.
Step 3: Choose Installation Path
Click Next.
Enter the directory path where the Bridge Client should be installed.
Step 4: Provide Registration Details
On the registration screen, enter the following details:
Token String
Enter the Security Code noted during the bridge creation process.
Machine IP Address
Enter the IP address of the machine where the Bridge is being installed.
Bridge Name
Provide a unique name to identify the Bridge Client.
Cloud Server URL
Enter the Bridge Server URL (provided by the OvalEdge team).
Bridge Secure Connectivity Pack Location
Provide the path where the Secure Connectivity Pack is saved on the system.
User Name
Enter full name.
Email Address
Enter a valid email address.
Phone Number
Enter the contact number
Click Next to proceed.
Step 5: Load Secure Connectivity Pack
The installer will automatically pick up the Secure Connectivity Pack from the specified location.
Processing will begin immediately.
Step 6: Complete Installation
Once the process completes successfully, a confirmation message will appear: "OvalEdge Bridge Software Installed Successfully on your computer."
Running Bridge as a Service (Optional)
OvalEdge offers the capability to run the Bridge Client as a Windows service, enhancing reliability and eliminating the need for manual intervention.
Overview
When the Bridge is installed manually on a client machine, it must be restarted if the server or virtual machine goes down. To mitigate this risk and ensure high availability, OvalEdge provides a "Bridge as a Service" option.
This approach ensures the Bridge Client automatically restarts on system reboot, supporting seamless connectivity to client data sources.
Key Benefits
Automated Restart: Automatically starts with the system, reducing manual overhead.
High Availability: Supports service-level availability of up to 99.999%.
Client-Side Reliability: Ensures the Bridge Client remains operational even after VM or system restarts.
Hybrid Support: Works for both SaaS-hosted Bridge Servers and client-hosted environments (cloud or on-premises).
Prerequisites
Download the BridgeAsAService.zip file from the link below:
Download BridgeAsAService.zip
Administrator access on the Windows machine.
If running the service under a non-administrator user, ensure the JAVA_HOME environment variable is set as a system variable, and the user has full access permissions to the entire NiFi installation directory.
Installation Steps for Windows
Unzip the BridgeAsAService.zip file to a local directory.
Copy nifi-windowsservice.VERSION.jar from the extracted folder.
Paste them into:
<nifi-installation-directory>/lib/bootstrap
Copy the remaining three files from the ZIP archive.
Paste them into:
<nifi-installation-directory>/bin
Navigate to the NiFi /bin folder in Command Prompt.
Run the following command:
install_service.batThis will register the service as Apache NiFi in the Windows Service Control Manager.
On Windows, install the NiFi service by using the Windows service wrapper files, then run install_service.bat. Confirm JAVA_HOME for the service account.
Open Services (type services.msc in the Start Menu).
Locate Apache NiFi in the list.
Ensure that the Apache NiFi status shows as 'Running'.
Set up a connection
To connect On-Premise data sources using the OvalEdge Bridge, follow the steps below:
Access the Connectors Module
Navigate to Administration > Connectors. The Connector Information page will appear.
Initiate a New Connection
Click the “+” icon to open the Add Connection pop-up window.
Select Connection Type
In the pop-up, choose the desired connection type (e.g., MySQL). A MySQL-specific configuration window will be displayed.
Select Bridge and Enter Connection Details
From the Bridge dropdown, select the appropriate Bridge (populated from the Bridge page).
Enter the required connection parameters.
Click the Validate button.
Validate and Save Connection
Upon successful validation, the "Save" and "Save & Configure" buttons will be enabled.
Click Save to establish the connection.
Click Save & Configure to open the Connection Settings window and configure additional parameters.
View Connection Details
Once saved, the new connection appears in the Connector Information page, displaying the Bridge ID and Bridge Name used for the connection.
Uninstallation of Bridge as a Service
To uninstall the Bridge as a Service, follow the steps below:
Delete the Windows Service.
Execute the following command in the Command Prompt with administrator privileges:
sc delete nifi-serviceThis removes the nifi-service entry from the Windows Service Manager.
Run the Uninstallation Command.
Navigate to the NiFi installation directory and run:
/bin/nifi-service.exe //DS//nifi-serviceThis command detaches the service configuration associated with nifi-service.
Bridge Configurations
OvalEdge Bridge Configurations allow users to manage and customize key parameters that influence how the application behaves and interacts with other systems. These settings are critical to ensuring the Bridge component is correctly aligned with operational needs and infrastructure standards.
Configuration Parameters
ovaledge.bridge.mode
True / False
Enables or disables the Bridge functionality in the application.
Parameters:
The default value is False.
If set to True, the Bridge functionality gets enabled.
If set to False, the Bridge functionality gets disabled.
ovaledge.bridgesoftware.path
/home/ubuntu/BridgeSoftware/
Specifies the path to the Bridge software on the client machine.
Default: /home/ubuntu/BridgeSoftware/
bridge.type
rest / nifi
Defines the Bridge type to be used: REST-based (Bridge Lite) or NiFi.
Parameters:
The default value is REST.
If set to REST, then the Bridge Lite gets activated.
If set to NIFI, then the Bridge NiFi gets activated.
bridge.protocol
http:// or https://
Defines the communication protocol for the Bridge.
Default: http://
Troubleshooting Bridge Issues
This section outlines common issues that may occur while using the OvalEdge Bridge and provides recommended solutions for each scenario. Proper monitoring and quick resolution of these errors help ensure reliable connectivity between OvalEdge and client-managed data sources.
Issue 1: Bridge is Down During Crawl Attempt
Description: A crawl is attempted while the Bridge Client (on the customer side) is down, but the OvalEdge Server is active. This results in a 504 Gateway Timeout error.
Root Cause: The connector cannot reach the Bridge Client due to network or service failure on the client side.
Resolution: Ensure that the Bridge Client machine is running and network traffic from it to the connector is not blocked by a firewall or proxy settings.
Issue 2: Bridge Goes Down Mid-Crawling
Description: The Bridge Client goes offline in the middle of a crawl operation. The job log shows a partial success message.
Root Cause: Sudden interruption of the Bridge Client process during an ongoing crawl operation causes incomplete job execution.
Resolution: Navigate to Manage Bridge in OvalEdge and verify the Bridge status. If the status is red, confirm whether the Bridge Client service is active on the client machine and restart if necessary.
Issue 3: OvalEdge Bridge is Down While Client Bridge is Up
Description: The Client Bridge Server is operational, but the OvalEdge Bridge Server is offline. The job logs reflect this state.
Root Cause: The OvalEdge server-side bridge service is down, leading to communication failure despite the client’s bridge being active.
Resolution: Report the issue to the OvalEdge support team to check and restore the Bridge Server on the OvalEdge infrastructure.
Issue 4: Attempting to Crawl When OvalEdge Bridge is Down
Description: User initiates a crawl/profile operation while the OvalEdge Bridge Server is offline and the Client Bridge is running. An error appears.
Root Cause: The crawl operation depends on the OvalEdge Bridge Server to orchestrate and interpret the results. Without it, requests cannot be processed.
Resolution: Notify the OvalEdge team to restart or recover the OvalEdge Bridge Server.
Issue 5: Client Bridge is Down While Trying to View Data in OvalEdge
Description: The user tries to access data under Data Catalog > Data Object > Data, but the Client Bridge Server is offline.
Root Cause: The Bridge Client is responsible for fetching data from the source; without it, the OvalEdge UI cannot display real-time data.
Resolution: Start or restart the Client Bridge Server to restore access to data in the OvalEdge application.
Issue 6: Query Sheet Throws an Error
Description: The Query Sheet module returns an unexpected error.
Root Cause: Currently under investigation.
Resolution: Await updates from the OvalEdge development team. A fix will be rolled out once the root cause is fully identified.
Issue 7: OvalEdge Bridge is Up, But Client Bridge is Down While Accessing Data
Description: The user attempts to access data in Data Catalog > Data Object > Data, but the Client Bridge is down.
Root Cause: Although the OvalEdge side is active, it relies on the Client Bridge to pull data. With the client-side offline, the request fails.
Resolution: Inform the OvalEdge team. Since the client manages the Client Bridge, ensure it is operational or restarted.
Issue 8: Connecting More Than 10 Bridges
Description: When attempting to establish more than 10 bridge connections, the system throws an error.
Root Cause: OvalEdge enforces a limit of 10 active bridges to maintain system performance and reliability.
Resolution: Disconnect unused or redundant bridges to stay within the 10-bridge limit before adding new connections.
NiFi Bridge logs:
NiFi writes logs under the NiFi installation logs folder. Review nifi-app.log and nifi-bootstrap.log. Open Services to confirm the service state if access fails.
FAQ
Why need a NAR with the Bridge? Use a NAR only when a NiFi flow needs a custom or updated processor. The Bridge installer and core runtime use JAR files.
Is it safe to add a NAR to the customer Bridge VM? Yes, when the source is trusted. NiFi isolates each NAR with a separate class loader.
Pre-requisites for auto NAR upgrade. Ensure the NiFi version supports auto-load, configure nifi.nar.library.autoload.directory, confirm permissions and disk space, and remove old NAR versions if a restart is needed.
Pre-requisites for NiFi Bridge log retrieval configuration. Access the Bridge VM with read permissions for the NiFi installation and logs folder, and ensure service control privileges on the host.
From where to get the Bridge NiFi server logs? Go to the NiFi installation logs folder on the Bridge VM. Review nifi-app.log and nifi-bootstrap.log.
Glossary
OvalEdge Bridge
A component that enables secure connectivity between OvalEdge (hosted on the cloud) and on-premises data sources, without requiring firewall changes. The Bridge uses pull-based HTTPS communication to regularly poll the OvalEdge Server for jobs such as crawling and query execution. Each Bridge instance connects to only one OvalEdge Server.
OvalEdge Server (Cloud)
The centralized, cloud-hosted OvalEdge platform is used to manage data cataloging, governance, and analytics. It serves as the central control hub, processing jobs and handling communications initiated by the Bridge.
Public IP Address
An IP address assigned by the Internet Service Provider (ISP) that is accessible directly from the Internet. It enables external systems, such as the OvalEdge cloud, to recognize and communicate with your network.
Token String
A sequence of characters used to break a string into meaningful parts or “tokens.” In the context of the Bridge, it may refer to a unique string used for authentication or identification during secure communication.
Copyright © 2025, OvalEdge LLC, Peachtree Corners GA USA
Last updated
Was this helpful?