ngrok

Follow this article to use Omnata ngrok tunnel connections for databases

About Omnata-ngrok tunnels

The Omnata-ngrok tunnel using underlying technology from our OEM partner ngrok. The Omnata native app establishes a secure tunnel using TLS between Snowflake and your cloud or on-prem database or endpoint. This architecture ensures that Omnata can connect into your target endpoint, without open your network firewall to incoming traffic from Snowflake IPs.

Should I use Privatelink or ngrok?

You will use one or the other, you don't need both.

Privatelink is the AWS and Azure native routing of traffic from Snowflake to your cloud VPC without traversing the internet. If you have Snowflake Business Critical and the required cloud infrastructure, then we recommend using Privatelink and you won't need ngrok. However, if you have any other Snowflake Edition, mismatched cloud providers and/or on-premise data, then ngrok is the best solution for private connectivity.

If you require more information about ngrok for cyber security, please contact us, for their SOC2 and other trust docs.

Summary of ngrok connection steps:

1. Create the ngrok service API integration

2. Create a connection for your database or endpoint

3. Install the ngrok agent

4. Configure and launch the ngrok agent

5. Complete the end-to-end tunnel

6. Authenticate to your endpoint

Ngrok tunnel configuration - step-by-step

Create the External Access Integration to the ngrok API

Go to Settings > Integrations and follow the steps for ngrok.

This step creates an account-level integration to the ngrok API service in order to provision tunnels.

The actual ngrok tunnels are provisioned during the connection creation process for each plugin.

Create a connection from the plugin page

Navigate to your Plugin > Create a connection.

For plugins that support ngrok, you will have the option to connect:

• Directly via the internet - this is the default method for public API endpoints. For databases, you can use this method if you open your network firewall to Snowflake IPs (Currently not recommended as Snowflake do not offer static IP range for customers)

• ngrok tunnel

• Privatelink - requires Snowflake Business Critical Edition in AWS or Azure with your target server hosted in a matching cloud, or on-premise accessible via a network route.

The Omnata UI will guide you through the configuration of your ngrok tunnel connection.

Install the ngrok Agent

First, you need to install the ngrok agent in your network either on the same server as your target database, or an adjacent VM that can access the database server. The ngrok agent is a lightweight networking application and can run on a minimum spec VM, or on the database server without overconsuming resources.

Some anti-virus software can falsely flag ngrok as malware.

We are working with ngrok to resolve this. You can visit their docs for more info.

For MacOS, use Homebrew:

brew install ngrok/ngrok/ngrok

For Linux, use Apt:

curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo gpg --dearmor -o /etc/apt/keyrings/ngrok.gpg && \
  echo "deb [signed-by=/etc/apt/keyrings/ngrok.gpg] https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

For Windows, use Chocolatey (You'll need to run this in an Administrator Command Prompt):

choco install ngrok

If you don't have one of these package managers installed or prefer to install the ngrok agent yourself, you can download the ngrok agent from the Ngrok website and install it on your network.

Configure & launch the ngrok agent

You can run the ngrok agent either as a standalone process or as a service. Instructions for each are provided in tabs on the 'launch agent' step in the Omnata UI.

Complete the Omnata UI form to populate values

The Omnata UI will provide you with a code snippet that contains the --auth token and --label edge for the connection, these pre-populated values configure the outbound connection from your network to Omnata's ngrok instance.

You will need to provide the [address]:[port] values that points the ngrok agent to the location of your database inside your network.

Run as a standalone process

To run the ngrok agent as a standalone process, follow the steps provided in the Omnata UI. Omnata will provide you with a code snippet that looks like the following:

ngrok tls  --authtoken <<omnata authentication token>> --url <<omnata tls tunnel url>> [address]:[port]

No modifications to this code are required and the configuration is applied and launched in the one command.

If you need to upgrade the ngrok agent, you can run the following command:

ngrok update

Run as a service

This is the recommended approach for production use

Running the ngrok agent as a service ensures a more reliable connection tunnel as it runs independently of user sessions, auto-starts and auto-recovers.

To configure the ngrok agent to run as a service, follow these steps:

• Locate the configuration directory for the ngrok agent.

  • For MacOS, the configuration directory is ~/.config/ngrok

  • For Linux, the configuration directory is ~/Library/Application Support/ngrok

  • For Windows, the configuration directory is %HOMEPATH%\AppData\Local\ngrok

• In the directory, create a configuration file (called omnata.yml) which will be used by ngrok agent. The configuration file should contain the following information:

version: 3
agent:
  authtoken: <<omnata authentication token>>
endpoints:
  - name: omnata
    url: <<omnata tls tunnel url>>
    upstream:
      url: [address]:[port]

• Install the ngrok agent as a service by running the following command:

ngrok service install --config=

• Start the ngrok service by running the following command:

ngrok service start --omnata

Create an External Access Integration to the ngrok tunnel

You now have half a tunnel created. The agent has created an outbound connection from your network to ngrok, and you need to complete the tunnel by creating a connection from Snowflake to ngrok.

The Omnata UI will give you queries to run to create an external access integration. These queries have the same structure as any other connection you make from Omnata to an endpoint.

Authenticate to your database or endpoint

You now have an end-to-end tunnel for private connectivity between Snowflake and your target network location. The final step is to authenticate to the database or endpoint at that location.

You will now be able to create a sync, or run direct queries against the endpoint.

Troubleshooting Connectivity Issues

The following are common error messages when connecting.

Message	Action
Cannot open server "xxxxxxx.ngrok.app" requested by the login. The login failed	Please enter your password again in the connection setup.
The TCP/IP connection to the host xxxxxxx.ngrok.app, port 443 has failed.	Ensure that the ngrok agent is running.