Running ngrok Behind a Corporate Firewall

When you need to deploy ngrok behind a corporate firewall, you may need to take additional steps to make sure ngrok works properly. As background, this is usually not an issue. Firewalls usually allow outbound connections, which is what an ngrok agent makes to establish a session with the ngrok service and subsequently your tunnel.

Running the ngrok Kubernetes Operator instead of the agent? Its egress requirements differ. See network egress requirements for the hosts and ports to allow.

However, certain corporate firewalls have more restrictions around outbound connections. For example, ngrok may be blocked on Fortinet firewalls. If you’re having trouble using the ngrok agent to start a tunnel, the first step is to run ngrok diagnose which produces a report that helps you identify connection issues.

$ ngrok diagnose
  Testing ngrok connectivity...

  Internet Connectivity
    Name Resolution                           [ OK ]
    TCP                                       [ OK ]
    TLS                                       [ OK ]
  ngrok Connectivity
    Name Resolution                           [ OK ]
    TCP                                       [ OK ]
    TLS                                       [ OK ]
  Tunnel Protocol                           [ OK ]

Successfully established ngrok connection! (region: 'us', latency: 54.895145ms)

To resolve these issues, you have a couple of options:

Work with the network team in charge of the corporate firewall to provide exceptions that allow ngrok to make the necessary outbound connections.
Set up a custom Connect URL.

When working with the network team, set up exceptions that allow the following:

Connect URLs (the default is connect.ngrok-agent.com, but there is one for each region), so that the ngrok agent can connect with ngrok servers
The update URL (the default is update.ngrok-agent.com), so that the ngrok agent can quickly update itself. Agent versions before 3.36.0 used update.equinox.io as the update URL.

Equinox is fully owned by ngrok and used exclusively for building and distributing ngrok binaries. See the FAQ page for more details.

Setting up a custom Connect URL can be useful because it ensures that no one can bring their own ngrok account. In this case, the network admins could continue to block traffic to the default Connect URLs and only allow your custom branded Connect URL. For this, you need to:

Set up a custom Connect URL in your ngrok dashboard
Edit your ngrok agent configuration file with a connect_url parameter, set to your custom Connect URL

Certificate revocation list

One of the steps in agent connection is checking the certificate revocation list. This requires an outbound connection on port 80 to the CRL URL (crl.ngrok.com for agent versions 3.9.0 and before, crl.ngrok-agent.com for agent version 3.10.0 and after). If your network blocks port 80, set crl_url to https://crl.ngrok-agent.com/ngrok.crl to fetch the CRL over HTTPS on port 443 instead. If you can’t connect to this URL at all, you can skip the CRL check by setting crl_noverify: true in your configuration file. However, disabling the CRL check exposes you to the possibility of using a certificate that has been revoked, which could mean that a third party could intercept and view your traffic.

Testing in a Kubernetes cluster

If you’re using ngrok from within a Kubernetes cluster, you may need to diagnose the network connectivity from the cluster to the ngrok cloud. To do this, you can run the previously mentioned ngrok diagnose command using the pre-built Docker images for the agent as a Job in Kubernetes. Create a manifest file (for example ngrok-manifest.yaml):

apiVersion: batch/v1
kind: Job
metadata:
  name: ngrok-diagnose
spec:
  template:
    spec:
      containers:
        - name: ngrok-diagnose
          image: ngrok/ngrok:latest
          command: ["/bin/sh", "-c"]
          args: ["ngrok diagnose"]
      restartPolicy: Never

Apply this manifest to your cluster:

kubectl apply -f ngrok-manifest.yaml

Wait a few seconds and check its logs to see the diagnose command’s output:

kubectl logs -l "job-name=ngrok-diagnose"

  TLS                                       [ OK ]
Localhost Connectivity
  Name Resolution                           [ OK ]
ngrok Connectivity - Region: Auto (lowest latency)
  Name Resolution                           [ OK ]
  TCP                                       [ OK ]
  TLS                                       [ OK ]
  Tunnel Protocol                           [ OK ]
Successfully established ngrok connection! (region: 'auto', latency: 54.895145ms)

To generate the more verbose diagnostic report, update your job’s args with the -w flag and file location:

apiVersion: batch/v1
kind: Job
metadata:
  name: ngrok-diagnose
spec:
  template:
    spec:
      containers:
        - name: ngrok-diagnose
          image: ngrok/ngrok:latest
          command: ["/bin/sh", "-c"]
          args:
            [
              "ngrok diagnose -w /tmp/diagnose_output.txt && cat /tmp/diagnose_output.txt",
            ]
      restartPolicy: Never

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Running ngrok Behind a Corporate Firewall

Certificate revocation list

Testing in a Kubernetes cluster