Bridge Installation for Linux

This document outlines the process for setting up the OvalEdge Bridge, a secure solution that connects the data systems with the OvalEdge cloud platform. The OvalEdge Bridge enables secure communication between the OvalEdge cloud platform and customer-managed data sources, without requiring changes to firewall configurations. It operates over HTTPS using pull-based communication, ensuring seamless data integration while maintaining security standards. Designed to simplify data access and control, the Bridge helps organizations leverage OvalEdge’s full capabilities without compromising on data governance or infrastructure policies.

Purpose of the document

The purpose of this document is to provide clear and concise instructions for installing and configuring the OvalEdge Bridge on Linux-based systems. It enables secure connectivity between customer-managed data sources and the OvalEdge cloud platform, allowing efficient data integration without complex network changes.

Prerequisites

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 machine hosting the OvalEdge Bridge:

Hardware Requirements

Component	Specification
RAM	32 GB
SSD	250 GB
vCPU	8 cores

Software Requirements

Component	Version
Operating System	Ubuntu 24.04
Java Runtime Environment	OpenJDK 17

To verify the installed Java version, use the following commands:

java -version

If Java is not installed or the version is incorrect, install OpenJDK 17 using the following commands:

sudo apt-get update
sudo apt-get install openjdk-17-jdk -y

• The installer uses JAR files for setup. NAR files serve NiFi processors only. The Bridge does not need NAR files for installation.

Placing NAR files on the Bridge VM is safe when the files come from a trusted source. NAR packages load as NiFi extensions with class loader isolation.

Network and Access Configuration

• Static Public IP: Share the static public or NAT IP address of the VM with the OvalEdge team (via Global Customer Success). This IP will be whitelisted on OvalEdge SaaS systems to enable secure communication.

• Verify the Public IP of the VM Run the following command to identify the public IP:

curl ifconfig.me

• Outbound Access Requirements: Ensure that the VM allows outbound traffic to the Bridge server’s IP (shared by OvalEdge) on port 9443.

• Connectivity Check: To confirm connectivity between the Bridge client and the server:

curl -v telnet://<bridge_server_domain>:9443

Replace <bridge_server_domain> with the domain provided by the OvalEdge team.

For the OvalEdge application to crawl data from the customer’s data sources, the VM hosting the Bridge client must have network access to those data sources. It is the customer's responsibility to ensure that the Bridge client VM is permitted to connect to all intended data sources.

OvalEdge recommends the following:

• Only open the required ports on the data sources to allow traffic from the Bridge client VM.

• Create service accounts with read-only access for each data source to ensure secure and minimal access privileges.

Auto NAR update

NiFi can auto load new NAR files from the extensions directory. Ensure the following before an auto NAR update:

1. NiFi version supports auto load.

2. The nifi.nar.library.autoload.directory property points to the extensions directory.

3. The NiFi service user has read and execute permissions on that directory.

4. Keep enough disk space for the new NAR.

5. Remove old NAR versions if a processor must move to a new version after a restart.

6. Refresh the UI to view new components after auto load.

Installation & Configuration

This section outlines the steps required to install the OvalEdge Bridge Client on a Linux-based system.

Step 1: Prepare the Bridge Client Machine

• Deploy a Linux machine that will serve as the Bridge Client. This machine acts as a mediator between the OvalEdge Bridge Server and the customer data connectors.

Step 2: Access the OvalEdge Application

• Log in to the OvalEdge application.

• Navigate to Administration > Connectors to open the Connectors Information page.

  

Step 3: 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 4: 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

Copy the Bridge Secure Connectivity Pack to the Bridge Client VM. Save the Security Code for use during installation.

• Click OK. The new bridge will now be listed on the Bridge page.

  

Step 5: Transfer Installation Files

• Bridge Installation software file:

  • https://oe-saas-distributions-bridgeclient.s3.ap-south-1.amazonaws.com/bridge_client_installer/ovaledge-bridge-client-installer.jar

The size of the Bridge Installation Software file is around 1 GB.

• Download the Bridge Installation Software file and move the file to the Bridge Client VM.

• Proceed with the JAR installer only. Do not search for NAR files for this step. NAR files apply to NiFi extensions, not the installer.

Install and Register Bridge

To install and register the OvalEdge Bridge Client on a Linux machine, follow the steps below:

Preparation

• Ensure the following files are copied to the Bridge client server:

  • Bridge Secure Connectivity Pack (ZIP file)

  • ovaledge-bridge-client-installer.jar

• Execute the Installer

  • Run the Bridge installer JAR file using the command below:

java -jar path_to_jar.jar

• Proceed with Installation Prompts

  • Press 1 and Enter to confirm the installation prompt. Repeat this step for similar confirmations.

  • Specify the installation directory when prompted. Default path:

/usr/local/ovaledge_bridge

• Enter Registration Details Provide the required inputs when prompted:

  • Security Code: Use the code obtained during the bridge creation in the OvalEdge application (format: BRIDGExxxxxxxxxxxxxxx).

  • M/C IP Address: Enter the same IP address used during bridge setup in the OvalEdge application.

  • Bridge Name: Assign a descriptive name of your choice.

  • Cloud Server URL: Enter the Bridge server URL shared by the OvalEdge team.

    
  • Certificates Path: Specify the path to the Bridge Secure Connectivity Pack ZIP file, which is copied to the VM.

    
  • User Details: Enter the required information (User Name and Email) for User1. (User2 and User3 are optional.

    
• Confirm Inputs

  • Press 1 and Enter to proceed.

  • Confirm the final installation action by entering Y and pressing Enter.

    
• Finalize Installation

  • Provide the path in the format below when prompted:

[/home/ubuntu/bridge/auto-install.xml]

• On successful installation, the system will display the following confirmation:

Bridge software installed Successfully

Running Bridge as a Service (Optional)

OvalEdge enables the Bridge Client to run as a service on customer-hosted machines. This approach ensures the Bridge remains available and automatically restarts after unexpected shutdowns, thereby improving reliability and minimizing the need for manual intervention.

Overview

Bridge installed manually using command-line methods can stop functioning when the client machine restarts or goes down. Running the Bridge as a service resolves this issue by automatically starting the Bridge component when the system boots. This setup enhances uptime and aligns with SLA targets of 99.999% availability.

Configuration Steps

Before creating the Bridge service, stop the running NiFi service.

• Stop NiFi Service

  • Navigate to the NiFi installation path and stop the service:

sh nifi.sh stop

• NiFi supports service installation on Linux. Run bin/nifi.sh install from the NiFi directory to register a system service, if needed.

• Create a Systemd Service File

  • Navigate to the system service directory:

cd /etc/systemd/system

• Create a new service file:

vim nifi.service

• Paste the following configuration into the file:

[Unit]
Description=Apache NiFi
After=network.target

[Service]
Type=forking
Environment=JAVA_HOME=/usr/lib/jvm/java-17.0-openjdk-amd64/
ExecStart=/home/ovaledge/nifi-server/nifiinstall/nifi-1.16.3/bin/nifi.sh start
ExecStop=/home/ovaledge/nifi-server/nifi-1.16.3/bin/nifi.sh stop
User=ovaledge
Group=ovaledge
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

• Modify the file as required:

  • ExecStart / ExecStop: Update paths based on NiFi installation location.

  • User / Group: Replace with the actual VM username and group.

Managing the Service

After creating the service file, run the following commands to manage the NiFi service:

• Reload systemd:

sudo systemctl daemon-reload

• Start the service:

sudo systemctl start nifi.service

• Enable the service on boot:

sudo systemctl enable nifi.service

• Check service status:

sudo systemctl status nifi.service

Use Cases

Once NiFi is configured as a service, it can be managed from anywhere on the machine using:

• Start NiFi:

sudo systemctl start nifi

• Stop NiFi:

sudo systemctl stop nifi

• Check Status:

sudo systemctl status nifi    

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, select the 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.

• Save & Configure 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.

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

Key	Value	Description
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://

Modify these values only when there is a clear understanding of the deployment environment and the integration requirements. Incorrect configuration may impact data connectivity or system stability.

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: A sudden interruption of the Bridge Client process during an ongoing crawl operation results in 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 for errors.

• To check service status and recent entries:

sudo systemctl status nifi.service

FAQ

1. Why use a NAR file with the Bridge? A NAR file packages NiFi processors and the dependencies. Use a NAR when a data flow needs a custom processor or an updated processor. The installer and runtime use JAR files. NAR files extend NiFi only.

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 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 allows external systems, like 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